Man page isn't synchronized

[Tiago Silva]

w3m's man page version (0.2.1) is not in sync with the program version (currently 0.5.2).
This behavior has existed, as far as I recall, since the Gutsy release.

[Matthew Bohy (matt-bohy)]

How is this dealt with? The upstream tarball has the same version man page. Do we simply ask the developers to update the documentation?

[Matthew Bohy (matt-bohy)]

Can anyone who actually uses w3m tell us whether the man page is actually inaccurate, rather than just old? I don't want to bother the developer if the only problem is the version number at the bottom of the page. If something is documented in the man page but doesn't work, or something works that is not documented, please post it here.

[Tiago Silva (tiagosilva)]

The man page is inaccurate. For instance, newer flags are missing.

[Matthew Bohy (matt-bohy)]

Tiago: If you think you know it well enough to update the docs yourself, do that and send the patch upstream. If you know it well enough to describe what's missing in the docs, send them an e-mail. If you don't want to do that, please give a more detailed description of what's inaccurate, and I'll send it along to them. Or if you know of a better option than these, please let me know. I'm very new to bug fixing, so I'll defer to your judgement. :)

[Tiago Silva (tiagosilva)]

I really don't know how to help you Matthew since I don't know what's inaccurate or missing... because it's missing.
Let me try to explain it: I started using w3m (in early Ubuntu versions) with the assistance of many tutorials found on-line, but then I made notice that some of the flags in these tutorials could not be met in the man page. Roughly at the same time I began using ELinks and never returned to w3m.

Recently I accidentally a flamefest of CLI browsers and wondered if the man page was updated... and it wasn't.

So, I'll take your advice and send them an email this weekend to ask what is going on.

[Matthew Bohy (matt-bohy)]

Awesome, thanks for the additional info. And thanks for taking the initiative on contacting upstream. You said that tutorials online were using options not in the man page, which made me think: where are they learning about these options? Sure enough (duh!) the --help option listed some newer options not in the man page. Also, there is a MANUAL.html included with the source that lists even more options, and in more detail. Some of these options, though, need to be compiled in to w3m, so I'm not sure how those are accounted for in man pages. I will look into comparing the the three sources and see if I can update the man page accordingly. I'll attach a patch when I have something. So if you do send them an e-mail, please let them know what we've found regarding the different sources of documentation. Maybe ask if they are already working on an updated man page, or if they'd appreciate help to that end. Thanks!

[Tiago Silva (tiagosilva)]

I e-mailed several of the developers via their sourceforge contact and so far no reply was received.
Tomorrow I'll try to write something in their mailing-list or something like it.

[Matthew Bohy (matt-bohy)]

I've created a patch to update the man page to reflect the current --help options. However, it's specific to Debian-based systems because there is a Debian patch in place to disable certain options which would conflict with w3m being used as a pager in the Debian "alternatives" system. Still, the patch may be better than nothing, at least for our own use. I've attached the patch, and a copy of the update man page in case anyone doesn't know what to do with the patch. I'll send it upstream to Debian and to the developers to see if anything sticks. Not very optimistic though, based on Tiago's experience. :P

[Matthew Bohy (matt-bohy)]

Here's the updated man page. If you want to check it for accuracy (please do!), just download it somewhere and use the command "man -l <path_to_downloaded_page>". Compare it with the current man page ("man w3m") and with the "w3m --help" listing. Let me know if there are any issues.

[Tatsuya Kinoshita (tats-debian)]

I've uploaded w3m 0.5.2-10 in Debian unstable, which includes
updated man page.

[Sebastien Bacher (seb128)]

the new version has been synced