Re: Please review changed man-file of w3m
Going through the draft man page:
> NAME
> w3m - a text based Web browser and pager
Modern style guides (e.g. the Chicago Manual of Style) say it's
"the Internet" (uppercase "I") but "the web" (lowercase "w").
> SYNOPSIS
> pager mode, reading from STDIN
If "pager mode" means unrendered, that doesn't strictly depend on the
source; it depends on whether W3M knows that it's HTML (though yes,
reading from STDIN without a -T is a good way to stop it knowing).
I'm still not sure of the best way of presenting this; maybe the
SYNOPSIS should just deal with the overall syntax of options and
arguments and grouping them into modes should be in the option
listings:
w3m [-opt]... [ file | URL ]...
w3m -v | -B | -bookmark file | -help | -show-option | -version
(Brackets mean "optional", ellipses mean "may be repeated", so saying
"[-opt]..." is a hint that it's "w3m -x -y -z" and not "-xyz".)
> w3m [-rM | -config file | -I charset | -O charset ]
These aren't alternatives, and you can't merge options ("-rM").
If we keep this appropach it's either
w3m [-r] [-M] [-config file] [-I charset] [-O charset]
or maybe just
w3m -r -M -config file -I charset -O charset
>
> browser mode
> w3m [-t | -r | -B | -M | -N | -W | -X | -num | -graph | -cookie |
> -title | -reqlog ] file | URL [...]
Again, the "|"s are mostly not appropriate, except here:
[ file | URL ]...
meaning "zero, one, or more instances of either a file or URL
argument".
>
> target and transfer information mode
> w3m [-m | -dump_source | -dump_head | -dump_both | -dump_extra ] URL
Still a baffling name... and not a very intuitive set, if you're
including -m.
> filter mode
> w3m [ -dump | -cols N | -I charset | -O charset | -T type ] [ file |
> URL ]
Ditto re "|". These are a more natural set, but they're not
"filtering", they're affecting the rendering.
> special startups
> w3m [ -v | -B | -bookmark file ]
>
> usage information
> w3m [ -o | -show-option | -help | -version ]
I've merged these in my alternative proposal above. Wait, we missed -h.
-o requires an argument and has nothing to do with the rest of these.
>
> DESCRIPTION
> w3m has been developped as a text based web client. It displays HTML
> documents residing on a local and a remote system. It renders HTML
> tables and frames. w3m ignores Java Script and Cascading Style Sheets.
> For plain text files, it can be used as a "pager" in much the same man-
> ner as "more" or "less".
This needs some English fixes (especially "developped"):
W3M is a text based web client; it can read and render local or remote
web pages, and is capable of handling HTML features such as tables and
frames (but ignores JavaScript and Cascading Style Sheets). For plain
text files, it can be used as a "pager" in much the same manner as "more"
or "less".
Plus maybe:
W3M supports "tabbed browsing" and (if w3m-image is installed) can
display inline graphics within an X terminal. Alternatively, if its text
rendering is not enough, W3M makes it easy to launch a different browser
for the current content.
> OPTIONS
> At start up, w3m will load any local file or remote URL specified at
> the command line. For help with runtime options, press "H" while run-
> ning w3m. Command line options are:
An original grammar error I missed: "At startup".
I have always wished more man pages would include a separate
ARGUMENTS section instead of cramming that syntax in under OPTIONS
like this; but that's not traditional. Adding more information here
about multiple arguments and STDIN and WWW_HOME and the different
handling of "w3m *" and "w3m -N *" would make things worse. Maybe we
should skip straight to:
For help with runtime options, press "H" while running W3M.
Command line options are:
and then end the OPTIONS section with an entry for
Argument handling:
At startup, W3M will load any URL(s) or local file(s)
specified on the command line. Multiple arguments will by
default be loaded as separate buffers.
(I've never quite understood how this is useful without -N; the only
way I know of skipping between arguments is via the history function.
Am I missing something? Maybe it's an emacsism?)
In the absence of an argument (or an option such as -B), W3M
will default to reading STDIN (which means it will not be able
to guess the file type; to have HTML input rendered, use -T).
If that isn't available, the last fallback argument is the
contents of the environment variable WWW_HOME (see ENVIRONMENT).
Next the options, which should either be strictly alphabetical or
sorted into explicit themed groups (and alphabetical within a group),
but I'm not going to impose that here:
> -t N set tab width to N columns
>
> -r ignore underline or bolding markup constructions that use
> backspace (e.g. in nroff)
>
> -l N preserve N lines of STDIN input (default 10000)
10 000)
or maybe
-l N mystery flag for padding out the command line
> -I charset
> user defined character encoding of input data
>
> -O charset
> user defined character encoding of output data
>
> -T type
> explicit characterization of input data by MIME type
>
> -B starts with default bookmark file ~/.w3m/bookmark.html
The convention is to use uninflected (imperative?) verb forms: "start"
(cf "set tab width").
"-B" is a special kind of launch while "-bookmark foo" just changes a
setting, so you can legally combine them as "w3m -B -bookmark foo".
Maybe I was wrong and it shouldn't mention the default here:
-B start with bookmark file
> -bookmark file
> specifies another bookmark file to be used
user defined bookmark file
And maybe *all* of these "user defined" options should say what the
default is - or just say "see FILES".
> -v allows start with no defined input via STDIN, file or URL
That's true for all the "special" group, which should probably also
include -help etc.
If you look at "document info" it calls itself "W3M startup page"
with a blank "Current URL", so:
-v start with W3M startup page
(Why -v, I wonder?)
This reminds me that unless we mean the package or the binary (which
are both named in lowercase) we should be talking about W3M.
> -F render frames
>
> -N distributes files or URL content to tabs. By default multiple
> targets are loaded in a stack of buffers.
Come to think of it this is only true for CLI arguments, not URLs
loaded via links, etc, so:
-N distribute multiple command line arguments to separate
tabs. By default they are loaded in a stack of buffers.
> -M monochrome display
>
> -no-mouse
> do not use mouse
>
> -num display each line's number
>
> +N go to line N, only effective for N larger than the number of lines in the terminal
^
Strictly that comma should be something stronger, such as a semicolon.
> -m Internet message mode
A feature so allegedly useful that it's the second bullet-point in the
package description, but I've been trying to get it to work and
getting nowhere. Maybe there should be a "mystery options" group.
> -graph use graphic characters for borders of frames and tables
>
> -no-graph
> do not use graphic characters for borders of frames and tables
It only seems to mark borders if they're declared via the "border"
attribute, long deprecated in favour of CSS, so these are getting a
bit cobwebby (though not when you compare them to the gopher proxy
options).
> -S squeeze multiple blank lines
>
> -W toggle wrapping in searches
>
> -title use the buffer name as terminal title string. If TERM is speci-
> fied, TERM style title configuration is used
>
> -X do not initialize/deinitilize the terminal
>
> -ppc N width of N pixels per character. Range of 4.0 to 32.0, default
> 8.0. Larger values will make tables narrower.
>
> -ppl N height of N pixels per line. Range of 4.0 to 64.0.
>
> -dump dump rendered page into STDOUT
Add the implied "and exit"? Maybe even group them with -help?
> -dump_source
> dump the page's source code into STDOUT
>
> -dump_head
> dump response of a HEAD request for an URL into STDOUT
^
> -dump_both
> dump HEAD and source code for an URL into STDOUT
^
> -dump_extra
> dump HEAD, source code and extra information for an URL into STDOUT
^
Most anglophones still say "a U R L" rather than "an url". Oh, and
the style I've been using everywhere else would add a comma -
dump HEAD, source code, and extra information for a URL
into STDOUT (and exit)
These dump_foo options tend to have unpleasant results for me, since
they don't do any uncompressing of parts that are sent compressed!
> -cols N
> combined with -dump, HTML input is rendered to lines of N char-
> acters length
This probably shouldn't say "input", and it's also true for output
into a pipe even without -dump.
-cols N
for rendered HTML output to a pipe or via -dump, use line
widths of N characters
> -post file
> use POST method with file content
>
> -header string
> insert string as a header
>
> -no-proxy
> do not use proxy
>
> -4 IPv4 only (equivalent to -o dns_order=4)
>
> -6 IPv6 only (equivalent to -o dns_order=6)
>
> -cookie
> accept and use cookies
>
> -no-cookie
> neither accept nor use cookies
>
> -show-option
> show all available config options
>
> -config file
> use file instead of the default configuration file ~/.w3m/config
>
> -o option=value
> assign value to config option
>
> -help show a summary of compiled-in and runtime options
>
> -version
> show the version of w3m
>
> -reqlog
> log headers of HTTP communication in file ~/.w3m/request.log
>
> -debug DO NOT USE
Like the Ren and Stimpy "Space Madness" History Eraser Button. Though
come to think of it for browsers that's a perfectly sensible option.
> EXAMPLES
> w3m as a pager
> $ ls | w3m
>
> HTML files displayed by w3m
"w3m as a text pager", "w3m as an HTML renderer"?
> $ w3m foo.html |
That doesn't return. How about
$ w3m foo.html | head
> $ cat foo.html | w3m -T text/html
>
> Conversion of HTML content by w3m
> $ cat foo.html | w3m -dump -T text/html >foo.txt
If you're sending it to a pipe you don't need -dump, do you? That's a
lynxism.
For an absolutely legitimate use of cat there's always:
$ cat header.html footer.html | w3m -T text/html > full.txt
> FILES
Hang on, it doesn't mention ~/.w3m/bookmark.html!
> $~/.w3m/config
> user defined configuration file, overrides $/etc/w3m/config
;
We don't need the leading dollars.
> $~/.w3m/keymap
> user defined key bindings; overrides default key bindings
>
> $~/.w3m/menu
> user defined menu, overrides default menu
>
> $~/.w3m/mouse
> user defined mouse settings
>
> $~/.w3m/cookie
> cookie jar; written on exit, read on launch
>
> $~/.w3m/history
> browser history - visited files and URLs
>
> $~/.w3m/passwd
> password and username file
>
> $~/.w3m/pre_form
> contains predefined values to fill recurrent HTML forms with
You don't need the "with".
>
> $~/.w3m/mailcap
> external viewer configuration file
>
> $~/.w3m/mime.types
> MIME types file
>
And as I mentioned, it might be nice if it had an ENVIRONMENT section
to explain what it does with some of the things that "grep -r getenv"
finds in the source:
COLUMNS
EDITOR
HTTP_PROXY
LANG
LINES
MAILER
NNTPSERVER
PAGER
SHELL
TERM
TMPDIR
WWW_HOME
etc
I don't know if many of them are worth mentioning, but WWW_HOME makes
a major difference to the program's usefulness.
> NOTES
> This is the w3m 0.5.3 Release.
>
> SEE ALSO
> README and example files are to be found in the doc directory of Your
^
Anglophones don't do that capitalising-second-person-pronouns thing.
> w3m installation. Recent information about w3m may be found in Japanese
> or English on the project's web pages at http://w3m.sourceforge.net
[...]
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: