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 > .SH NAME > w3m \- a text based Web browser and pager > .SH SYNOPSIS > .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 file. > \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 accepted. > 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 ] > .SH DESCRIPTION > .\".\" 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 - 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 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? > .SH OPTIONS > > 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 against? > .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 or 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. Ditto. > .TP > \fB-dump\fP > dump formatted/rendered page into STDOUT > .\" bugreport 285251 Omit. > .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 Etc. > .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 options (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 Repetition. > .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 > DO NOT USE > .SH EXAMPLES > .\"fixes Bug report 380560 Use simplest example Omit. > .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 Omit. > .SH FILES > .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 $XDG_CONFIG_HOME.) > .TP > \fC${HOME}/.w3m/keymap\fP > user defined key binding, overrides default key binding bindings; 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. > .SH NOTES 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/ > .SH ACKNOWLEDGMENTS > \fBw3m\fP has incorporated code from several sources. > Users have contributed patches and suggestions over time. > .SH AUTHOR > Akinori ITO <[email protected]> (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 -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected] Archive: https://lists.debian.org/[email protected]
