Re: Re: Please review changed man-file of w3m
Hello Justin,
Justin B Rye schrieb am 11. Nov 2014 um 11:37
> Markus Hiereth wrote:
> > Justin B Rye schrieb am 10. Nov 2014 um 00:46
> [...]
> >> Sheets. W3M can also serve as a general purpose browser and
> >> pager (like "more" or "less") for text files named as
> >> arguments, passed on standard input, or accessed via the net.
> >
> > Maybe we can renounce the parenthesis with more and less and shorten
> > the last phrase a bit:
> >
> > W3M can also serve as a general purpose browser and pager for
> > text passed in files, on standard input, or accessed via the
> > net.
>
> I'd prefer to avoid talking about "passing" text in a file (which also
> upsets the "Xed via Y" parallelism). Come to think of it you can also
> invoke "w3m ." and navigate to a local file - but maybe we don't need
> to mention that. We could just drop the parenthesis:
>
> W3M can also serve as a general purpose browser and pager for
> text files named as arguments, passed on standard input, or
> accessed via the net.
>
> Or reorganising slightly (we're not really contrasting "browser mode"
> and "pager mode" here - we've done "web browser" already):
>
> W3M can also serve as a general purpose directory browser and
> as a text pager for files named as arguments or passed on
> standard input.
>
> Or even:
>
> W3M can also serve as a pager for text files named as arguments
> or passed on standard input, and as a general purpose directory
> browser.
Each of the three versions is an improvement. The latter is sorted the
best.
> >> When given one or more command line arguments, W3M will
> >> attempt to work out the target's MIME type before deciding how
> >> to handle it. Web URLs provide W3M with content-type headers;
> >> for relative or absolute file system paths, W3M relies on
> >> filenames.
> >
> > instead of "work out" more concrete:
> >
> > When given one or more command line arguments, W3M will handle
> > targets according to content type. For web URLs, this
> > information is delivered as HTTP header value and for relative
> > or absolute file system paths, W3M relies on filenames.
>
> Let's straighten out both phrases to have active verbs:
>
> When given one or more command line arguments, W3M will handle
> targets according to content type. For web URLs, W3M gets
> this information from HTTP headers; for relative or absolute file
> system paths, it relies on filenames.
That's fine.
> >> With no argument, W3M expects data from STDIN and assumes
> >> "text/plain" unless another MIME type is given by the user.
> >
> > Maybe we should use "standard input" instead of "STDIN" in the
> > descriptive first paragraphs of the manpage. We used "standard input"
> > in the first paragraph of section DESCRIPTION.
>
> Yes, fair enough. And although I habitually write STDIN/STDOUT/STDERR
> all-caps it might be more standard to use stdin/stdout/stderr
> throughout.
It's up to you. I just would prefer complete words "standard input" in
the descriptive parts of the manual page.
> >> -cookie, -no-cookie
> >> turn cookie-handling on or off
> >
> > -cookie, -no-cookie
> > turn cookie-handling on or off. Corresponds the pair of
> > boolean variables accept_cookie and use_cookie in
> > configuration files
>
> That should be "Corresponds ^to^ the pair...". We have no particular
> reason to go into this much detail when we don't mention other
> variables like show_lnum or bg_color. And saying it like this still
> fails to hint at the difference between "using" and "accepting"
> cookies. The point of putting it this way:
>
> -cookie, -no-cookie
> use cookies and accept new ones, or do neither
>
> was that it explains that, so if I look at the config file I'll see
> what they do. Maybe even
>
> use stored cookies and accept new ones, or do neither
That's fine
> >> -post file
> >> use POST method to upload data defined in file. The syntax to be
> >> used is var1=value1[&var2=value2]...
> >
> > Maybe we should use the typewriter font for the file's content
> >
> > used is \fCvar1=value1[&var2=value2]...\fP
> Oh, okay. That formatting has no effect in normal manpagers, but I
> assume it affects other kinds of output. It would be easy to end up
> marking a lot of this text as typewriter font...
All the font variations (bold, italics, monospace) appear with
groff -Tps -man file.1 > file.1.ps
The content of this file for data to be posted is the only occurence
where I miss the monospace font. Everywhere else it is used.
> >> -4 IPv4 only (equivalent to -o dns_order=4)
> >>
> >> -6 IPv6 only (equivalent to -o dns_order=6)
> >
> > I think there is more sense in a hint to the items in the
> > configuration files than in providing a second way of setting the
> > value of the configuration variable
> >
> > -4 IPv4 only. Corresponds to dns_order=4 in
> > configuration files
> >
> > -6 IPv6 only. Corresponds to dns_order=6 in
> > configuration files
>
> Good idea,
>
> >> Options for data output (with immediate exit):
> >
> > I personally dislike appended information in parenthesis. Can we use
> > "followed by"
> >
> > Options for data output, followed by immediate exit:
> > Options for data output, immediate exit after operation:
> > Options to request data, immediate exit after delivery
> > data request options, immediate exit after delivery:
>
> Definitely the first one.
OK, let's use it.
> >> Convert a web page to text with appended links
> >> $ w3m -o display_link_number=1 w3m.sourceforge.net > out.txt
> >
> > With retry_http=TRUE, the target is accepted. Otherwise, w3m will
> > complain "Can't load w3m.sourceforge.net"
> Oh, sorry, when did that get set? Of course I was trying to ensure it
> would fit on one line and not trigger justification - there's probably
> a more appropriate nroff markup solution for that. If necessary:
Silly thing, that these seven characters more of http:// cause line
breaking.
Merging this example with the "Start with no imput" would solve the
problem. With -B for bookmarks instead of -v, the content of out.txt
was less boring.
> Sorry about the lack of revised version, I've run out of time; I'll
> get back to it this afternoon.
I just searched for information about the layout commands for manpages
and this page ...
http://www2.research.att.com/sw/download/man/man5U/groff_man.html
contains some valuable hints. I need to go through our manpage file
and check how .SS, .SH, and .TP are used. In addition, .TP accepts a
number as argument that affects indentation.
Therefore I would suggest that you introduce the last language
improvements and I remove still exiting outcommented lines and try make a better use of the layout macros.
Best regards
Markus
Reply to: