Re: Please review changed man-file of w3m
Markus Hiereth wrote:
> while translating w3m manpage into German, I found a lot of things
> that could be improved about it. I would appreciate if some subscriber
> of the list checked the attached file with respect to language and
> style.
Okay. A diff of the changes would have made things simpler...
> .nr N -1
> .nr D 5
> .TH W3M 1 "2014-10-23"
> .\"improvements with respeckt to bugreport 268211
This should be in the accompanying metadata (e.g. commit message),
not in the file. (Also, s/respeckt/respect/.)
> .UC 4
> .SH NAME
> w3m \- a text based Web browser and pager
> .SH SYNOPSIS
> .SS
> pager mode
(Ah, all these "modes" are your addition.)
> \fBw3m\fP [-t | -r | -M | -config \fIfile\fP | -I \fIcharset\fP | -O \fIcharset\fP ]
> .SS
This fails to mention that it takes a file argument (or STDIN), and
falsely implies that -t, -r etc are mutually exclusive. You want
something like
w3m [-M] [-r] [-config file] [-I charset] [-O charset] [-t tab] [filename]
with appropriate nroff highlighting; but why mention these particular
options and not, for instance, "+<num>" or "-W" or "-S"? (Oh, wait,
the man page claims "-S" is "squeeze blanks", but no, that's "-s".)
> browse and file view mode
Unclear. Do you mean "browser mode"? What kinds of files can w3m
"view" that don't already fall under "pager" or "browser" (given that
those may have handle fancy MIME-handling)?
> .\"fixes bugreports 530468 345084
Again, this is metadata that shouldn't be written into the installed
file.
> \fBw3m\fP [-t | -r | -B | -M | -N | -W | -X | -num | -graph | -cookie | -title | -reqlog ] \fIfile\fP | \fIURL\fP [...]
> .SS
Again, mostly shouldn't be separated by vertical lines. And if we're
going to rewrite it, can we please distinguish the ones that take
parameters (such as -t) and put them into some sort of order?
w3m [-M] [-N] [-W] [-X] [-r] [-cookie] [-num] [-graph] [-reqlog] [-title[=TERM]] [-t tab] file | URL [...]
Also of course you can use "pager" options in "browser" mode and vice
versa, but I suppose this is the sort of simplification that's
accepted.
> remote target data mode
Technically the header-dumping and so on also work on a local URL...
maybe it should be something like "HTTP data mode"? But then again
what exactly *does* -m do?
> \fBw3m\fP [-m | -dump_source | -dump_head | -dump_both | -dump_extra ] \fIURL\fP
At least these presumably are mutually exclusive and do deserve the
vertical lines.
> .SS
> filter mode
> \fBw3m\fP [ -dump | -cols \fIN\fP | -I \fIcharset\fP | -O \fIcharset\fP | -T \fItype\fP ] [ \fIfile\fP | \fIURL\fP ]
"-cols N" but not "-t tab"?
> .SS
> special startups
> \fBw3m\fP [ -v | -B | -bookmark \fIfile\fP ]
Fair enough.
> .SS
> usage information
> \fBw3m\fP [ -o | -show-option | -help | -version ]
> .SH DESCRIPTION
> .\".\" This defines appropriate quote strings for nroff and troff
> .\".ds lq \&"
> .\".ds rq \&"
> .\".if t .ds lq ``
> .\".if t .ds rq ''
> .\".\" Just in case these number registers aren't set yet...
> .\".if \nN==0 .nr N 10
> .\".if \nD==0 .nr D 5
What are these changes for?
>
> \fIw3m\fP is a World Wide Web (WWW) text based client. It has English
Pre-existing English error: "World Wide Web (WWW) text based client"
should be "text-based World Wide Web (WWW) client". Or really it
could take it for granted we all learned what WWW means decades ago
and just say "text-based web client".
> and Japanese help files and an option menu and can be configured to
Isn't your objective to create further help files?
> use either language. It will display hypertext markup language (HTML)
> documents containing links to files residing on the local system, as
Again, this millennium we can just say "HTML documents", but there's a
bigger problem: it can display them even if they don't contain links
to files anywhere else at all. This is a piece of gibberish that also
used to be in the package description for lynx-cur, but I managed to
get that fixed back in 2009 -
https://lists.debian.org/debian-l10n-english/2009/07/msg00054.html
All it's trying to say is something like
It can render local or remote web pages and
follow links.
But once you've boiled it down to this it's fairly pointless. That's
the minimum functionality required before we'll describe something as
a "web browser".
> well as files residing on remote systems. It can display HTML tables
The part about tables and frames is worth having, in that it makes it
clear that unlike Lynx it supports HTML 3. On the other hand we
might mention that it has no support for CSS, JavaScript, etc.
> and frames. In addition, it can be used as a "pager" in much the same
> manner as "more" or "less". Current versions of \fBw3m\fP run on
> Unix (Solaris, SunOS, HP-UX, Linux, FreeBSD, and EWS4800) and on
> Microsoft Windows 9x/NT.
How many of these operating systems still exist?
> .SH OPTIONS
>
> At start up, \fBw3m\fP will load any local ile or remote URL specified
^
Preexisting typo.
> at the command line. For help with runtime options, press \fI"H"\fP
> while running \fBw3m\fP. Command line options are:
(In no particular order...)
>
> .TP
> \fB-t\fP \fIN\fP
> set tab width to N columns
> .TP
> \fB-r\fP
> ignore backspace effect
The SourceForge user manual is clearer, explaining at least partway
that it prevents the backspace-and-underline or overstrike bolding
used (e.g.) in nroff.
ignore backspaces used for nroff-style effects
> .TP
> \fB-l \fIN\fR
> preserve N lines of STDIN input (default 10000)
In English text that should be "10,000". But what does it preserve it
against?
> .TP
> \fB-I \fIcharset\fR
> user defined character encoding of input data
> .TP
> \fB-O \fIcharset\fR
> user defined character encoding of output data
> .TP
> \fB-T \fItype\fR
> explicite characterization of input data by MIME type
Spelling: explicit. Wikipedia seems to think that these days we're
meant to call them "Internet Media Types", but until I see an RFC
backing that up my position is [Citation Needed].
> .TP
> \fB-B\fP
> load stored bookmarks
It would make at least as much sense to mention ~/.w3m/bookmark.html
here, given that that's what -B loads. It might also mention that
this overrides any argument.
> .TP
> \fB-bookmark \fIfile\fR
> specifies bookmark file to be used (default \fC~/.w3m/bookmark.html\fP)
> .TP
> \fB-v\fP
> allows starting with no defined input via STDIN, file or URL
Well, that's better than the nonsensical "visual mode", but it could
be clearer. For a start, "w3m -v" isn't the same as saying plain
"w3m" (which goes to WWW_HOME).
> .TP
> \fB-F\fP
> render frames
> .TP
> .\"fixes bugreports 530468 345084
Omit. (Nice, though. Ooh, it even combines with -title.)
> \fB-N\fP
> distributes series of input, one tab per file or URL. By default series of input files loaded in a stack of buffers.
In English:
distribute files or URLs to separate tabs. By default multiple targets are loaded in a stack of buffers
> .TP
> \fB-M\fP
> monochrome display
> .TP
> \fB-no-mouse\fP
> do not use mouse
> .TP
> \fB-num\fP
> display each line's number
> .TP
> \fB+\fIN\fR
> go to line N, only effective for N larger than number of lines in the terminal
More grammatically:
go to line N; only effective for N larger than the number of lines in the terminal
> .TP
> \fB-m\fP
> internet message mode
Capital I for Internet. SourceForge has more information, but not
enough to be intelligible.
> .TP
> \fB-graph\fP
> use graphic characters for borders of frames and tables
> .TP
> \fBno-graph\fP
You've lost a leading hyphen.
> do not use graphic characters for borders of frames and tables
> .TP
> \fB-S\fP
> squeeze multiple blank lines
No, that's -s (which upstream claim has something to do with Japanese
legacy charsets.)
> .TP
> \fB-W\fP
> toggle wrap search mode
toggle wrapping in searches
> .TP
> \fB-title\fP
> use the buffer name as terminal title string.
> If TERM is specified, TERM style title configuration is used
So it needs to say something like "\fB-title\fP [=TERM]".
> .TP
> \fB-X\fP
> do not use termcap init/deinit
Termcap doesn't exist on GNU/Linux, so maybe it should say
do not use terminfo/termcap init/deinit
or
do not initialize/deinitialize the terminal
> .TP
> \fB-ppc \fIN\fR
> width of N pixels per character. Range of 4.0 to 32.0, default 8.0.
> Larger values will make tables narrower.
Yes, it warps tables, but there's no sign of characters changing size.
Is this for something Japanese-specific?
> .TP
> \fB-ppl \fIN\fR
> height of N pixels per line. Range of 4.0 to 64.0.
Ditto.
> .TP
> \fB-dump\fP
> dump formatted/rendered page into STDOUT
> .\" bugreport 285251
Omit.
> .TP
> \fB-dump_source\fP
> dump source code into STDOUT
The SourceForge versions are clearer:
Read document specified by URL and dump the source.
> .TP
> \fB-dump_head\fP
> dump response of HEAD request into STDOUT
Read document specified by URL and dump the HEAD
> .TP
> \fB-dump_both\fP
> dump HEAD and source code into STDOUT
> .TP
> \fB-dump_extra\fP
> dump HEAD, source code and extra information into STDOUT
Etc.
> .TP
> \fB-cols \fIN\fR
> renders HTML input to lines of N characters length (to be used with -dump)
render HTML for lines of N characters length (for use with -dump)
> .TP
> \fB-post \fIfile\fR
> use POST method with file content
> .TP
> \fB-header \fIstring\fR
> insert string as a header
> .TP
> \fB-no-proxy\fP
> do not use proxy
> .TP
> \fB-4\fP
> IPv4 only (equivalent to -o dns_order=4)
> .TP
> \fB-6\fP
> IPv6 only (equivalent to -o dns_order=6)
> .TP
> \fB-cookie\fP
> accept and use cookies
> .TP
> \fB-no-cookie\fP
> neither accept nor use cookies
> .TP
> \fB-show-option\fP
> show all available config option
options
(The option name itself has the same error)
> .TP
> \fB-config \fIfile\fR
> use file instead of the default configuration file \fC~/.w3m/config
> .TP
> \fB-o \fIoption=value\fR
> assign value to config option
> .TP
> \fB-help\fP
> show \fBw3m's\fP version and help on invocation of the programm in the command line
Spelling: program. It also provides help for invocation of w3m even
if you're planning to do it from (e.g.) a cronjob, and it also lists
compile-time flags, so maybe:
show a summary of compiled-in and runtime options
(The -h output has spelling and grammar problems of its own.)
> .TP
> \fB-version\fP
> show version version of \fBw3m\fP
Repetition.
> .TP
> \fB-reqlog\fP
> log headers of HTTP communication in file \fC~/.w3m/request.log
Or indeed HTTPS... though apparently not FTP, so say "HTTP(S)".
> .TP
> \fB-debug\fP
> DO NOT USE
> .SH EXAMPLES
> .\"fixes Bug report 380560 Use simplest example
Omit.
> .TP
> \fBw3m\fP as a pager
> \fC$ ls | w3m\fP
> .TP
> HTML files displayed by \fBw3m\fP
> \fC$ w3m foo.html |
> .br
> $ cat foo.html | w3m -T text/html\fP
Useless Use Of Cat. What's wrong with
$ w3m -T text/html < foo.html
...? Of course this just makes it obvious you'd never do that.
> .TP
> Conversion of HTML content by \fBw3m\fP
> $ cat foo.html | w3m -dump -T text/html >foo.txt
More Useless Use Of Cat, plus UUO "-dump -T text/html" - you'd get the
same result from just:
$ w3m foo.html > foo.txt
For a more plausible scenario try:
web page rendering
$ find -name "*.html" | xargs w3m | mail $USER
> .\"fixes bug report 403634 man w3m: add a FILES section
Omit.
> .SH FILES
> .TP
> \fC${HOME}/.w3m/config\fP
> user defined configuration file, overrides \fC$/etc/w3m/config\fP
Why "${HOME}/.w3m/" instead of just "~/.w3m/"?
(In fact if upstream were more active I'd suggest adopting
$XDG_CONFIG_HOME.)
> .TP
> \fC${HOME}/.w3m/keymap\fP
> user defined key binding, overrides default key binding
bindings;
The comma in all of these would be better as a semicolon (or stop).
> .TP
> \fC${HOME}/.w3m/menu\fP
> user defined menu, overrides default menu
> .TP
> \fC${HOME}/.w3m/mouse\fP
> user defined mouse settings
> .TP
> \fC${HOME}/.w3m/cookie\fP
> deposit of cookies between termination and start of of \fBw3m\fP
If you mean "place where they're stored", that's conventionally the
"cookie jar". "Termination" makes it sound as if you mean SIGTERM...
how about:
cookie jar (written on exit, read on launch)
> .TP
> \fC${HOME}/.w3m/history\fP
> history of visited files and URLs
This makes it sound as if it's the history of the files. Say
browser history - visited files and URLs
> .TP
> \fC${HOME}/.w3m/passwd\fP
> password and username file
> .TP
> \fC${HOME}/.w3m/pre_form\fP
> contains predefined values to fill recurrent html forms with
I'm not crazy about "recurrent", but it'll do. "html" should be
"HTML", though.
> .TP
> \fC${HOME}/.w3m/mailcap\fP
> external viewer configuration file
> .TP
> \fC${HOME}/.w3m/mime.types\fP
> MIME types file
> .\" .TP
> .\" .I ${HOME}/.w3m/urimethodmap
> .\" ???
No idea.
> .SH NOTES
Isn't this SEE ALSO?
> This is the \fBw3m\fP 0.5.3 Release.
> .PP
> Please see the MANUAL.html file distributed with \fBw3m\fP for
> more detailed documentation.
Actually this makes the man page more detailed than the MANUAL.html
file for a lot of stuff.
> .PP
> Additional information about \fBw3m\fP may be found on its Japanese
> language Web site located at:
> .br
> http://w3m.sourceforge.net/index.ja.html
> .br
> or on its English version of the site at:
> http://w3m.sourceforge.net/index.en.html
Those are both the same "site"; say
Additional information about w3m may be found in Japanese or English
on its web pages at http://w3m.sourceforge.net/
> .SH ACKNOWLEDGMENTS
> \fBw3m\fP has incorporated code from several sources.
> Users have contributed patches and suggestions over time.
> .SH AUTHOR
> Akinori ITO <aito@fw.ipsj.or.jp>
(Phew, that took me longer than I expected. Sorry it's still only
inline comments rather than a proposed diff.)
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: