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

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
> w3m \- a text based Web browser and pager
> .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

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

> 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 ]
> .\".\" 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 -

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

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


> .TP
> \fB-dump\fP
> dump formatted/rendered page into STDOUT
> .\" bugreport 285251


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


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


> .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
> .\"fixes Bug report 380560 Use simplest example


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


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

> .TP
> \fC${HOME}/.w3m/keymap\fP
> user defined key binding, overrides default key binding
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.


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/

> \fBw3m\fP has incorporated code from several sources.
> Users have contributed patches and suggestions over time.
> 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: