Re: Re: Please review changed man-file of w3m
Hello Justin,
just for Your information: Changes in Version _3 shall as well reflect
hints and corrections of Your second mail of monday 27th.
Best Regards
Markus
----
>>>> \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".)
>>
>> I'm still undecided whether it makes sense to have the options
>> explicitely listed instead of "[OPTIONS]" in the synopsis.
>>
>> The seperated treatment of a "pager mode" and a "browser" mode was
>> primarily meant to stress that w3m expects data from STDIN if no
>> target file is delivered. One remainig problem: I never saw
>> constructions like
>>
>> cat file | w3m
>> or
>> STDIN | w3m
>> or
>> w3m < STDIN
>>
>> in the synopsis of a manpage.
>
>It's true, this is more EXAMPLES material (though I wouldn't use any
>of these examples; if you really want a use of cat, make it something
>slightly less useless like "cat *.txt | w3m").
>
>In a synopsis you'd just say "program [ file | URL ]..." and explain
>later that without an explicit argument or arguments it falls back on
>STDIN (though in fact, wait, it falls back on $WWW_HOME, and *then*
>STDIN).
section SYNOPSIS is now cut back zu options and target
I set WWW_HOME as a local variable in xterm. w3m ignores it.
>>>> 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)?
>>
>> My assuptions for classification:
>>
>> capability:
>> Read from STDIN -,
>> Display plain text -+--,
>> Display HTML -+--+--,
>> Follow URLs -+--+--+--,
>> | | | |
>> v v v v
>>
>> typical pager y y n n
>> typical browser n n y y
>>
>
>Or less contortedly,
> browserlike: follow URLs and render HTML
> pagerlike: read from STDIN and display it verbatim
>
>But really it's slightly more complicated...
>
> if given an argument or arguments (or special startup option):
> for URLs, use "webby" mode (working out MIME types via headers)
> for path arguments, use "local" mode (relying on the filename)
> if given no argument:
> fall back on $WWW_HOME (may be a URL or path), *then* STDIN
> (with reduced ability to guess MIME types), *then* error.
>
>"Webby" mode can still browse to .txt files, "local" mode can still
>open foo.html as a rendered web page, and a single invocation of w3m
>can handle separate targets in different "modes" at the same time.
>
>(I notice that you can't say "w3m -"; that isn't accepted either as
>meaning STDIN or as the file "./-". Not that I'm claiming anyone's
>ever likely to want that functionality.)
I introduced this explanations on the possible sources of data
>>>> 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.
>>
>> Yes, a combination of these dump-options makes no sense. Using the "|"
>> was a mistake because it stands for OR.
>
>As an argument in favour of having at least some of the options
>explicitly explained like this in the synopsis rather than summarised
>along the lines of "w3m [-opts] [arg]...", note that you can't say
>"w3m -rM"; it has to be "w3m -r -M".
>
>> What do You think of "target and HTTP meta data mode"?
>
>I don't follow; it sounds as if it means "the mode of the target and
>the HTTP meta data" or something.
>
>> To avoid difficult questions of how to label "modes" of usage, one
>> could shorten the section "SYNOPSIS" and extend section "EXAMPLES".
>
>Or indeed the "third option" of grouping option-flags under explicit
>subheadings in the OPTIONS section.
With Version _3, we try it this way
>>>> and Japanese help files and an option menu and can be configured to
>>>
>>> Isn't your objective to create further help files?
>>
>> This would be an argument to omit references to English and Japanese
>> as avaible language, doesn't it?
>
>Yes, we want to rip out the bits that were obviously written in a
>previous millennium *and* the bits that might change next month!
I erased the reference to the available languages.
>>>> 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 let's not forget the "tabbed browsing", "graphics in an xterm",
>and "iceweasel handover" selling points.)
These points are mentioned now too.
>>>> 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?
>>
>> I don't know. I assumed that You regard this statement as obsolete too
>> and dropped it.
>If we knew enough to update it, I'd keep it - upstream might still
>consider portability a major feature of w3m.
I wrote two further mails, hoping for support from one of the
developers.
>[...]
>>>> .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?
>>
>> Is this separation with commas obligatory in English? The German
>> equivalent with dots is obligatory. Introducing the comma would force
>> the integer to be "translated too. A strong reason to avoid the dubios
>> helpers.
>It's optional for four-digit numbers but normal for five-digit ones.
>Some standards allow "10 000" for international compatibility - that's
>supposed to be a thin non-breaking space, but you could get away with
>a plain space.
We should use a plain space.
Correction: The German equivalent is not obligatory! Dots are
sometimes used, but more often, numbers appear in groups of three.
>> I did not test this setting, assuming that additional lines could get
>> lost.
>
>"printf '%s\n' {0..99999} | w3m" seems to get all of the input even
>without -l.
>
>MANUAL.html says:
>
> Specify line number preserved internally when reading text/plain
> document fron standard input. Default is 10000.
>
>which sounds as if it's talking about... I don't know, maybe guessing
>how long the file is going to be?
Changed towards the explanation in MANUAL.html
>>>> .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).
>>
>> As far as I know there is no WWW_HOME. Without target file or STDIN
>> input, w3m puts out help lines.
>
>Several text browsers honour $WWW_HOME if it's set in the environment;
>it's obscure, but I don't think it's Debian-specific. Aha, no indeed:
>
>http://info.cern.ch/hypertext/WWW/LineMode/Defaults/Customisation.html
I noticed who wrote the piece. With this manpage, we proceed
turtle-like. But on the other hand, with Your reference on Tim
Berners-Lee explanations is to be expected from a browser, I had
somehow the pleasure of grabbing a stone from the stone age of the web
age.
>[...]
>>>> .TP
>>>> \fB-S\fP
>>>> squeeze multiple blank lines
>>>
>>> No, that's -s (which upstream claim has something to do with Japanese
>>> legacy charsets.)
>>
>> -e, -j and -s commandline options are not accepted by w3m here. It
>> seems MANUAL.html is outdated.
>>
>> Would You prefer a more detailed description? E.g:
>>
>> "replaces two and more blank lines of plain text files with a single one"
>more(1) seems to think that "Squeeze multiple blank lines into one"
>is clear enough; cat(1) is equally brief but completely different with
>"suppress repeated empty output lines"; or if you want a more explicit
>model to copy there are less(1) and most(1).
I copied the explanation given in more(1). I just noticed that we deal
with -s and -S is not accepted anymore.
I passed a bugreport about this.
>> Therefore, I would omit [=TERM]. It just confuses.
>>
>> Trials of Usage:
>>
>> input: Title appears in the terminal window's title bar:
>> w3m -title ~ yes
>> w3m -title=xterm ~ yes
>> w3m -title=lxterm ~ no
>> w3m -title=uxterm ~ no
>Well, "=rxvt" works, but it's exactly the same as =xterm...
I still tend to wipe out [=TERM].
[...]
>>>> height of N pixels per line. Range of 4.0 to 64.0.
>>>
>>> Ditto.
>>
>> I wonder whether it makes sense to mention options with no proof of
>> that they really do what was promised to be done. I found neither
>> effect for the options -ppc and -ppl and neither for the
>> pixel_per_character and pixel_per_line parameter in the panel for
>> setting options within w3m.And this refers to xterm windows and tty
>> terminals.
>>
>> As the output of w3m -version does not indicate that these scaling
>> functions have been excluded from complilation, I would conclude that
>> they are not at all correctly implemented in the source code itself.
>>
>> Shall we ask the maintainer Tatsuya?
>
>They certainly do *something*, for pages containing text in tables -
>mainly "mess things up". This makes no sense to me, since w3m seems
>to cope perfectly adequately if you change the number of pixels per
>character by changing your terminal font's point size. Maybe it has
>something to do with the way CJK characters come in "halfwidth" and
>"fullwidth" variants?
ppc and ppl shall be transferred to the group of options "not tested,
DO NOT USE"
>>>> .TP
>>>> \fB-dump\fP
>>>> dump formatted/rendered page into STDOUT
>>>> .\" bugreport 285251
>>>
>>> Omit.
>>
>> What is Your preference about the verbs to format and to render? I'm
>> inclined to the latter and changed the text respectively.
>
>w3.org's HTML specs talk about "rendering" throughout.
OK
>>>> 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
>>
>> I tried two versions of
>>
>> $ find -name "*.html" | xargs w3m | mail $USER
>>
>> Both led to error messages.
>
>It's only going to work if you've got .html files lying around locally
>and an MTA for mail to be delivered to - it works for me.
Later, I noticed that two mails had been created. Thus, it worked and
yielded error messages too.
>> I think, this is to extreme in the other
>> way, to ambitious.
>
>If we want a *portable* example of w3m usefully taking multiple input
>web pages, rendering them, and sending them to some other program...
>well, the output end is easy enough; just make it " | pager". But on
>the input end the problem is that our reader may not have any HTML
>files lying about locally, whereas if they're remote URLs it would
>make more sense for w3m to fetch them itself rather than depend on an
>external program on STDIN.
We should deliver a couple of examples showing
- pager-like, browser-like, filter-like usage
- using with options that work on character encoding, type of content
Reply to: