Re: FAQ.html and MANUAL.html, was Re: fwd: Re: Re: Please review changed man-file of w3m
Hello Justin,
Justin B Rye schrieb am 8. Dec 2014 um 23:21
>>> Then since this already made a huge diff against the original I also
>>> went crazy with my indenting to keep the translatable content
>>> separate from the formatting.
>> I hope you recovered from crazyness :-) and indulge one finding of
>> html2po: The tool found in line 640 one slash to miss. It transforms
>> an paragraph tag into an end of paragraph tag.
>Okay, revised FAQ.html attached. I also have a revised and
>re-HTMLified MANUAL.html, but it still has a few points I'm not sure
>about. Going through the original in rendered form:
I wonder whether I am able to support You. I suppose the technical
questions were answered when we had been working on the manual
page. And I am not the one to judge English language and
style.
Though, I am able to indicate phrases where the documentation fails to
explain something. One of the foremost motivations for revising at
least the selected three files in the doc-directory was all the
redundancy. E.g. in MANUAL.html, "visual startup mode" as explanation
for option -v survived.
>From my point of view, by the use of links and references, whole
sections of MANUAL.html could be dropped. I am just afraid that
changes of this depth are as well beyond the business of a language
team as the are not within the scope of Debian and Tatsuya as package
maintainer.
>> ??? Key binding
>
>That's "colors", "key bindings"... the file needs a lot of trivial
>number and definiteness fixes.
>
>> ??? Lynx-like key binding
>> ??? Mouse operation
>> ??? Key customization
>> ??? Local CGI
>>
>> ?????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????
>>
>> Introduction
>>
>> w3m is a pager/text-based WWW browser. You can browse local documents and/or
>> documents on the WWW using a terminal emulator.
>
>That's a bit awkward, but not bad enough to need surgery.
>
>> ?????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????
>>
>> Options
>>
>> Command line usage is
>>
>> w3m [options] [file|URL]
>>
>> If you specify filenames/URLs on command line, these documents are displayed.
>> If you specify nothing, w3m reads a document from standard input and display
>> it. If no filename and/or URLs are specified and standard input is tty, w3m
>> terminates without displaying anything.
>
>That needs a bit of rephrasing: "If you specify nothing, w3m will read
>a document from standard input and display it. If it doesn't find a
>document there either then (normally) w3m will terminate without
>displaying anything."
I would prefer a reference to manual page than providing the
explanantions to w3m's option a second time.
>> Options are as follows:
>
>Some are missing (e.g. -N and -6), so let's say "Options include".
>They're also in a random order, but I haven't tried to fix that.
>
>> +<line number>
>> Move to the specified line.
>
>Standardise <i>parameters</i>.
>
>> -t width
>> Specify tab width. Default is 8.
>> -r
>> When displaying text/plain document, prohibit emphasis using backspace. If
>> you don't specify this option, ``A^H_'' is interpreted as underlined
>> character and ``A^HA'' as a bold character.
>Standardise <q>quoted text</q>, and say that those examples are
>specifically an underlined "A" and a bold "A".
We should introduce the manpage explanation here. This explanation to
-r is simply confusing. Additionally, -r is none of the options
important and worth being mentioned several times. Could be dropped in
a "Options include" section.
>> -l number
>> Specify line number preserved internally when reading text/plain document
>> fron standard input. Default is 10000.
>
>"Specify the number of lines that should be cached while reading a
>text/plain document from standard input. Default is 10,000."
-l is none of the options important and worth being mentioned several
times. Could be dropped in a "Options include" section.
>(Oops, nearly missed s/from/fron/.)
>
>> -O charset
>> Specify display/output charset.
Just an annotation: "Display charset" is astonishing. Does it really
make sense here? The word charset here is used in the sense of
"character encoding", i.e. the mapping of binary information on one
side and a certain character and/or a glyph. Therefor, I imaging
paging a file as a one-step process, completely controlled by one
setting, the -I.
>> -I charset
>> Specify document charset.
>> -T type
>> Specify document type. Without this option, document type is determined
>> from extension of a file. If the determination fails, the document is
>> regarded as text/plain.
>>
>> Example:
>> Read HTML document from standard input and display it
>>
>> cat hoge.html | w3m -T text/html
>>
>> Display HTML source
>>
>> w3m -T text/plain hoge.html
>
>I don't know what if anything a "hoge" is, but I've replaced it with
>"example.html".
I do not know hoge.html either.
>> -m
>> Display document with Internet message mode. With this option, w3m
>> determines document type from header information. It is useful when reading
>> E-mail or NetNews messages.
>
>Say "e-mail or Usenet news posts".
Manpage explanation is much better, the option itself is not important.
>> -v
>> visual startup mode.
>
>Is its normal startup mode "olfactory mode"? I blame vi users for
>this sort of insane terminology. Make it "Show w3m's startup page."
Manpage explanation is much better, the option itself is not important.
>> -B
>> Show the bookmark.
>
>Confusingly wrong. "Show w3m's bookmarks page."
Manpage explanation is better, the option itself is not important.
>
>> -bookmark file
>> Specify bookmark file.
Manpage explanation is better, the option itself is not important.
>Insert "a custom".
>
>> -M
>> Monochrome display mode.
I cannot regard this option as important.
>> -F
>> Automatically render frame.
>
>Make that "HTML frames".
Make that "render HTML frames"
>> -s
>> Squeeze blank lines.
I cannot regard this option as important.
>> -X
>> Upon exit, do not display preserved screen.
>
>If anything that's the reverse of the effect I get; make it "do not
>reinitialize the terminal."
This option -X is worth being dropped here
>
>> -W
>> Toggle wrap search mode.
>
>Nearly: "search wrap mode", or to spell it out "wrapping mode in
>searches".
Spell it out "Toggle wrapping mode in searches".
>> -o option=value
>> Specify option. The option names and values are same as that appears in ~
>> /.w3m/config.
>
>Just "are the same as in".
Yes, "are the same as in", and, moreover, without "option=value" as
argument, the complete list of option and explanations is put out.
>> -cookie
>> Process cookies.
>> -no-cookie
>> Don't process cookies.
Manpage explanation is better, the option itself is not important.
>>>>>> To be continued tomorrow.
It's getting too late
Markus
Reply to: