[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Please review changed man-file of w3m

Going through the draft man page:
>        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").
>    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

	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

>    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.

>        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.
>        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
>        -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.
>        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

For an absolutely legitimate use of cat there's always:
      $ cat header.html footer.html | w3m -T text/html > full.txt

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:
I don't know if many of them are worth mentioning, but WWW_HOME makes
a major difference to the program's usefulness.

>        This is the w3m 0.5.3 Release.
>        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: