Re: Re: Please review changed man-file of w3m
Hello Justin,
below my view on your hints and corrections. You will find the
respective changes in Version _3 of the manual
Best regards
Markus
-----------------------------------------------------------------
>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").
OK
>> 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
section SYNOPSIS reduced, section EXAMPLES is extended now
>> 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".
OK.
[...]
>> 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.
I had already worked out these additional "selling point". See version _3
>> 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:
I introduced a section ARGUMENTS in version _3
> 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.
Buffers and tabs are now mentioned in section DESCRIPTION
>(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?)
I regard the stack of buffers as useful. It is an emacsism. You get
the buffers listed with s and select one with arrow-up or arrow-down
and return.l
> 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).
As I already wrote: WWW_HOME is ignored here
$ WWW_HOME=http://lune
$ echo $WWW_HOME
http://lune
$ w3m
w3m version w3m/0.5.3+cvs-1.1055, options lang=en,m17n,image,color,ansi-color,mouse,gpm,menu,cookie,ssl,ssl-verify,external-uri-loader,w3mmailer,nntp,gopher,ipv6,alarm,mark,migemo
usage: w3m [options] [URL or filename]
options:
-t tab set tab width ...
>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:
I share your view. Establishing groups of options and sort the group
members alphabetically was the main idea behind the csv-file.
>> -B starts with default bookmark file ~/.w3m/bookmark.html
>
>The convention is to use uninflected (imperative?) verb forms: "start"
>(cf "set tab width").
OK
>"-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".
I tend to mention files containing user data with the default
information, i.e. to mention ~/.w3m/bookmark.html here. In contrast,
the section FILES would only contain configuration 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.
>This reminds me that unless we mean the package or the binary (which
>are both named in lowercase) we should be talking about W3M.
Strange. Does this uppercase W3M tnen refer to this software in
general, i.e. the source code delivered by the w3m project? Note that
my previous versions of the manpage 'w3m' inside text paragraphs
already was marked with bold letters.
>> -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:
Thats true. There is an extra option open_tab_blank for change runtime
behaviour.
>
> -N distribute multiple command line arguments to separate
> tabs. By default they are loaded in a stack of buffers.
Changed description
>> -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.
>
OK
>> -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.
Yes,
>> -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).
You are right. Nevertheless these options work. Having -graph and -no-graph in one line would slighly shrink the cobweb
>> -dump dump rendered page into STDOUT
>Add the implied "and exit"? Maybe even group them with -help?
I do not think it necessary to mention that the dump options imply an exit.
>> -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".
OK
>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
I used input because this means html code from all sources. As far as
I can see output into a pipe only works in combination with one of the
dump options.
My problem wie "HTML output": I regard it as plain text output. -cols
acts on the HTML block element <p>, it is part of the rendering. -cols
combined with -dump_source has no effec.t
>> -post file
>> use POST method with file content
Meanwhile, I think this option deserves as well a place among our
mystery options. With it, w3m displays usage information, apparently
take no notice of anything else in the command line.
>> EXAMPLES
>> w3m as a pager
>> $ ls | w3m
>>
>> HTML files displayed by w3m
>
>"w3m as a text pager", "w3m as an HTML renderer"?
I introduced it as an alternative. Let's decide later.
>> $ w3m foo.html |
>
>That doesn't return. How about
> $ w3m foo.html | head
>
Strange. It looks as " | command " implies option -dump. But I think
the point is, the manpage shall explain explicite control of w3m.
>> $ 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.
Obviously, I'm infected with lynxism without having ever used lynx.
>For an absolutely legitimate use of cat there's always:
> $ cat header.html footer.html | w3m -T text/html > full.txt
Beautiful and primitive. Exactly what I prefer.
>> FILES
>
>Hang on, it doesn't mention ~/.w3m/bookmark.html!
Now added to the option -B
>> $~/.w3m/config
>> user defined configuration file, overrides $/etc/w3m/config
> ;
>We don't need the leading dollars.
Yes. Now I see it is a remnant of the ${HOME}
>> $~/.w3m/pre_form
>> contains predefined values to fill recurrent HTML forms with
>You don't need the "with".
OK
>
>>
>> $~/.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.
Just mentioning these variable would be ok. But I fear the effort of
analysing their dependencies to other configuration approaches: Why
does w3m invoke mutt as mail user agent instead of mailx although
there is no trace of it in .w3m/config?
Reply to: