Re: Re: Please review changed man-file of w3m
Hello Justin,
Justin B Rye <justin.byam.rye@gmail.com> schrieb am 2. Nov 2014 um 00:30
> > I'm re-merging some frayed threads here, skimming through and just
> > answering the parts that still seem to be relevant.
> I'm passing the new w3m(1) draft through "col -b". Really to make
> this process work I should be proposing revisions to some _input_
> format like POD or Docbook that then gets converted into a man page.
I would appreciate to write w3m(1) in a modern file format. But I
never wrote a POD (*) or Docbook file.
(*) I just found out that tools like pod2man, pod2html etc. are
already installed here.
> > W3M(1) W3M(1)
> >
> >
> >
> > NAME
> > W3M - a text based web browser and pager
> ^^^
> I think *here* we're meant to be talking about the command, "w3m".
>
> > SYNOPSIS
> > w3m [OPTIONS|... [ file | URL ]...
> ^
> Should that first "|" be a "]"?
Yes, ...
> I suppose if it's "optionS" then you don't need to say "..."...
... and therefore the S needs to disappear.
> > DESCRIPTION
> > W3M has been developed as a text based web client. [...]
>
>
> The "has been developed" is a bit off grammatically, but more
> importantly, it's talking about the development process when the
> reader only cares about the successful result: it *is* a text based
> web client.
OK
> > It displays HTML
> > documents stored local or on remote systems. [...]
>
> "It displays HTML" makes it sound as if it can only "view source".
>
> "Local" would have to be "locally", but really this should say
> something like:
>
> W3M is a text based browser which can display local or remote web pages
> as well as other documents.
>
> (Also avoiding the repetition of "web" and leaving open the possibility
> that it might also be a gopher/NNTP/whatever browser.)
OK
> > It renders HTML tables and
> > frames. W3M ignores JavaScript and Cascading Style Sheets. [...]
>
> Cosmetic surgery:
>
> Its rendering engine can process HTML tables
> and frames, but it ignores JavaScript and Cascading Style Sheets.
Avoided "rendering engine", but modified in Your sense.
> > It accepts
> > plain text from files or from standard input, serving as a "pager" in
> > much the same manner as "more" or "less".
> This idea that it handles either HTML via HTTPS (browser mode) or plain text via
> the commandline (pager mode) is simply wrong - it can also handle "w3m foo.html"
> and browsing to http://example.org/foo.txt. Of course, you're more *likely* to
> hand it random text files on the commandline and web pages via a URL, but that's
> a fact about how users work, not w3m!
> 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.
>
> This still needs work since I'm not sure how close we should get to hinting at
> the existence of "w3m ./" and "w3m gopher://foo";.
I introduced this sentence and I think that these two cases are covered too.
> > W3M organizes content in buffers and tabs, allowing easy navigation
> > between. Having the extra package with w3m-img installed, W3M shows
> > graphics within a page or in a new buffer. Whenever W3M's capabilities
> > to render HTML do no meet your needs, the target URL can be handed over
> > to a graphic browser by a single command.
> You've added a few good ideas, but it needs a bit or reanglicisation.
which is welcome of course.
>
> W3M organizes its content in buffers or tabs, allowing easy navigation
> between. With the w3m-img extension installed, W3M can display inline
> graphics in web pages. And whenever W3M's HTML rendering capabilities
> do not meet your needs, the target URL can be handed over to a graphical
> browser with a single command.
>
> (Talking in terms of the w3m-img "extension" should make this less
> Debian-specific and easier to pass upstream.)
I introduced this paragraph as suggested.
> > For help with runtime options, press "H" while running W3M.
> >
> >
> > ARGUMENTS
> > If given one argument or more arguments, W3M works like a browser. Hav-
> > ing recieved a URL, the respective content is worked out according to
> > the MIME type. With relative or absolute paths as argument, W3M relies
> > on filenames to display the content in an adequate manner.
>
> Several English problems here, but more importantly, the number of command line
> arguments is not what determines whether it acts like a browser.
>
> When given one or more command line arguments, W3M will attempt to work
> out the 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.
> > With no argument, W3M expects data from STDIN. Input given by the user
> > may be necessary the control how these data processed further.
>
> Try:
> With no argument, W3M expects data from STDIN, and unless assisted by
> the user will have to use the default of "text/plain".
Modified in some way.
> > With no explicite targets and no stream of data from STDIN, W3M exits
> > with usage information.
>
> No it doesn't!
>
> If provided with no target (and no fallback target - see for instance
> option -v below), W3M will exit with usage information.
Modified.
> > OPTIONS
> > Options are introduced with a dash and may take an argument
>
> Groff distinguishes between "dash", "hyphen", and "minus", but insists for
> reasons I have never understood that the ASCII "-" glyph used for options is
> "minus". See "http://manpages.debian.org/cgi-bin/man.cgi?query=groff_char";.
> There's even a Lintian error for using the wrong one:
> "https://lintian.debian.org/tags/hyphen-used-as-minus-sign.html";
> It's cruel to expect users to understand this (especially given that in strict
> Unicode terms, 0x2D = "-" is "hyphen-minus" and the true "minus sign" is a
> completely separate glyph, 0x2212 = "???"), so I would suggest:
>
> Options must each be introduced by a single "-" character and may in
> some cases take a parameter.
OK
> >
> > Options to select predefined configurations and resources
>
> That doesn't really work, but the category makes sense. Maybe:
>
> Options overriding W3M resources (normally in ~/.w3m/; see FILES)
>
> And I would be inclined to make it one of the last subsections.
>
> > -config file
> > use file instead of the default config file
>
> (This works if "file" is appropriately highlighted)
>
> > -bookmark file
> > specifies another bookmark file to be used
>
> For consistency:
> use file instead of the default bookmark.html file
>
> >
> > -reqlog
> > log headers of HTTP communication in file ~/.w3m/request.log
>
> use a request.log file to log network connection headers
>
> > -debug DO NOT USE
>
> Why is it in this set? Is it just trailing behind -reqlog? I suppose
> this last one fits, though:
>
> > -o option=value
> > modify one configuration item with an explicitely given value
>
> A reminder: it's "explicit", not "explicite". And why not just say:
> -o option=value
> explicitly set one configuration item
>
> Or if we're being encyclopaedic
> explicitly set one configuration item (per invocation of -o)
> but we're allowed to leave a few details to the MANUAL.html...
>
> Now, alphabeticise them:
>
> Options overriding W3M resources (normally in ~/.w3m/; see FILES)
>
> -bookmark file
> use file instead of the default bookmark.html file
>
> -config file
> use file instead of the default config file
>
> -debug
> DO NOT USE
>
> -o option=value
> explicitly set one configuration item
>
> -reqlog
> use a request.log file to log network connection headers
>
Pulled down and modified
> > Tuning W3M / Options to tune Program-User-Interaction / Man-Machine-Inter-
> > face
>
> Almost anything could be "tuning its interface"; what these have in
> common is that they affect the persistent Textual User Interface.
>
> An alternative approach would be to move this section so that it's
> 1) web-browser-mode options
> 2) text-pager-mode options
> 3) generic textual-UI options
>
> > -title use the buffer name as terminal title string.
> >
> > -title=TERM
> > use the buffer name as terminal title string. TERM style title
> > configuration is used
> > Implementation not verified
>
> I think the "=screen" test verifies that it works as it says; we just happen to
> be short of use cases.
>
> > -no-mouse
> > do not use mouse
>
> Or "deactivate mouse support", since "using the mouse" means pushing
> it around my desk.
>
> >
> > -num display each line's number
>
> Strictly speaking this also affects material sent to STDOUT, but I'll
> ignore that for now.
>
> > -M monochrome display
> >
> > -W toggle wrapping in searches
> >
> > -X do not initialize/deinitilize the terminal
> ^a
> > Implementation not verified
>
> I think this is another one where we've verified it to the limits of
> my curiosity. At least compared to the following two mysteries:
>
> >
> > -ppc N width of N pixels per character. Range of 4.0 to 32.0, default
> > 8.0. Larger values will make tables narrower.
> > Implementation not verified
> >
> > -ppl N height of N pixels per line. Range of 4.0 to 64.0.
> > Implementation not verified
>
> Okay, a whole section I'm mostly happy with. But alpha-sorting (I'm
> going to assume it's aAbBcC):
> Textual User Interface tuning options:
>
> (possibly import "-B" here)
>
> -M
> monochrome display
>
> -no-mouse
> deactivate mouse support
>
> -num
> display each line's number
>
> -N
> distribute multiple command line arguments to tabs.
> By default, a stack of buffers is used.
>
> -ppc N
> width of N pixels per character. The range is 4.0 to 32.0, default
> 8.0 - larger values will make tables narrower.
> (Implementation not verified)
>
> -ppl N
> height of N pixels per line. The range is 4.0 to 64.0.
> (Implementation not verified)
>
> -title, -title=TERM
> use the buffer name as terminal title string. TERM if specified
> sets the title configuration style as for that TERM.
>
> (possibly import "-v" here)
>
> -W
> toggle wrapping in searches
>
> -X
> do not initialize/deinitialize the terminal
>
> (I have imported -N from the following section; I also consider the
> possibility of importing +<N>, .)
OK. And -N and +<N> imported
> > Command line options for a browser-like usage
>
> You mean something like "web browsing behaviour options".
>
> > -F render frames
> >
> > -N distribute the contents passed with multiple command line argu-
> > ments to tabs. By default, a stack of buffers is used.
>
> This isn't specific to HTTP, or web pages... yes, it's a feature that
> first appeared in web browsers, but now in effect it's a basic TUI
> feature and deserves a place in the preceding Section.
>
> >
> > -cookie, -no-cookie
> > accept and use cookies, neither accept nor use cookies
>
> What's the difference between accepting and using cookies, anyway?
I assume we need to care for this paragraph of README.cookies
* You can disable cookie on the Option Setting Panel. In this case
all cookies are rejected, however, cookies which accepted before
disable cookie are used.
I found out that
CLI-option | is equivalent to
------------------|---------------------------------
-cookie | use_cookie=1 AND accept_cookie=1
-no-cookie | use_cookie=0 AND accept_cookie=0
> >
> > -graph, -no-graph
> > use or do not use graphic characters for borders of frames and
> > tables
>
> Almost a TUI feature, but web-specific enough to stay here.
>
> > -no-proxy
> > do not use proxy
> >
> > -4 IPv4 only (equivalent to -o dns_order=4)
> >
> > -6 IPv6 only (equivalent to -o dns_order=6)
> >
> > -m Internet message mode
> > Implementation not verified
>
> If it can't be used on email then maybe we should be more specific and
> call it "USENET message mode", but it's still too hazy to say.
>
> Again these mostly just need to be sorted. Uh, which end do numbers
> go?
>
> Internet browser mode options
>
> (possibly import "-cols N" here?)
>
> -cookie, -no-cookie
> support (or do not support) the use of HTTP cookies
>
> -F
> render HTML frames
>
> -graph, -no-graph
> support (or do not support) the use of graphical characters for
> drawing HTML table and frame borders
>
> (possibly import "-header string" here?)
>
> -m
> Internet message mode, taking message headers into account to
> determine content-type.
> (Implementation not verified)
>
> -no-proxy
> do not use a proxy
>
> (just conceivably import "-post file" here?)
>
> -4
> IPv4 only (equivalent to -o dns_order=4)
>
> -6
> IPv6 only (equivalent to -o dns_order=6)
Modified
> > Command line options for a pager-like usage
>
> These are "text-handling" options, but yes, here treating it as "web
> browser mode" versus "text pager mode" makes sense.
>
> > -r ignore underline or bolding markup constructions that use
> > backspace (e.g. in nroff)
>
> Now I need to look up which way round I eventually decided it was.
>
> > -s squeeze multiple blank lines into one
> >
> > -t N set tab width to N columns. No effect on STDOUT
>
> This raises the issue that "pager-like usage" shouldn't have a STDOUT,
> but -r and -s are general text-processing options that work on
> material sent to STDOUT as well as within the "pager". Oh well.
>
> Text pager mode options
>
> (possibly import "-l N" here?)
>
> -r
> use caret notation to display special escape characters in text
> (such as ANSI escapes or nroff-style backspaces) instead of
> processing them as colored or otherwise highlighted text.
>
> -s
> squeeze multiple blank lines into one
>
> -t N
> set tab width to N columns. No effect on text sent to STDOUT.
Modified
> > Command line options for a special startup
> >
> > -v allow start with no defined input via STDIN, file or URL
>
> That sounds as if it means it's getting undefined input from one of
> those sources.
>
> -v
> with no other target defined, use the built-in W3M
> start-up page
OK
> > -B start with default bookmark file ~/.w3m/bookmark.html
>
> It doesn't necessarily use that one; "-B -bookmark" effectively
> cancels out, so "w3m -B bookmark /etc/fstab" does the same thing as
> "w3m /etc/fstab".
> -B
> with no other target defined, use the bookmark page.
OK
> Those are the two "special targeting" options; the rest are "special
> exit" options.
>
>
> > -show-option
> > show all available config options
> >
> > -help show a summary of compiled-in and runtime options
> >
> > -version
> > show the version of W3M ()
>
> "()"?
>
> Maybe we could put -v and -B in the generic-TUI-options section as
> -B
> special start-up: with no other target defined, use the
> bookmark page.
> [...]
> -v
> special start-up: with no other target defined, use the
> built-in W3M start-up page
I pulled them up to this section
> and then merge the special-exits into the following section.
> > Options for instant data requests
>
> "Non-persistent data output mode options"? That's terrible, but it's
> the best I can think of at the moment.
>
> > -dump dump rendered page into STDOUT
> >
> > -dump_source
> > dump the page's source code into STDOUT
> >
> > -dump_head
> > dump response of a HEAD request for a URL into STDOUT
> >
> > -dump_both
> > dump HEAD, and source code for a URL into STDOUT
> >
> > -dump_extra
> > dump HEAD, source code, and extra information for a URL into
> > STDOUT ()
>
> "()"?
>
> Merging the two sections would add -help, -show-option and -version
> on the end.
>
> > Miscelleneous command line options
> Miscellaneous
>
> > +N go to line N; only effective for N larger than the number of
> > lines in the terminal
>
> Maybe in "generic TUI options"? (Make sure the highlighting is enough
> to let readers distinguist "-N" from "+N" (ie "+<N>".)
>
> > -cols N
> > combined with -dump, HTML input is rendered to lines of N char-
> > acters. Affects only STDOUT
>
> Not necessarily combined with -dump; it also works on any HTML
> rendered into a pipe. Oh, interestingly, even "w3m -v", even though
> that was never HTML. But I think that corner-case is obscure enough
> to ignore!
OK
> If all the others get rehoused, this could live in "web browsing mode"
> (just because it deals with the HTML rendering engine).
>
> > -l N number of lines preserved internally when recieving plain text
> > from STDIN (default 10 000)
>
> (It's "-ceiv-".) Wouldn't this fit nicely in "text pager mode"?
OK
> > -post file
> > use POST method with file content
> > Implementation not verified
>
> Now fully verified! But hard to find a use for. This could just
> about go under "web browsing mode".
OK
> > -header string
> > APPEND string to the HTTP(S) request. Expected to match the
> > header syntax Variable: Value
>
> I think this could go in the "web browsing mode" section.
OK
> > EXAMPLES
> > Pager-like usage of W3M | W3M as a text pager
> > Combine snippets of html code and preview the page
> > $ cat header.html footer.html | w3m -T text/html fP
>
> I think that line-final fP indicates an nroff error.
> So the "text pager" example renders a webpage? That would be less
> obtrusive if you had a second example. Maybe something like
>
> Compare two files using "tabbed pager" mode
> $ w3m -N config.old config
OK
> > Browser-like usage of W3M | W3M as an HTML renderer
> > Display web content in monochromous terminals
>
> Just "in a monochrome terminal" (another kind of hardware I'm glad to
> have finally thrown away).
OK
> > $ w3m -M http://w3m.sourceforge.net
> > Display embedded graphics
> > w3m -o auto_image=TRUE http://w3m.sourceforge.net
> ^
> You're being inconsistent about the leading prompt-style $.
OK
> > Filter-like usage of W3M
>
> Different indent. Another nroff error?
No. Just experimental layout. I still do not know whether there are
more elegant techniques than those used now, including pairs of .br
and forcing indentation manualy with \space.
> > Convert an HTML file to a plain text file with a defined length of
> > lines
>
> Just say "a defined line length".
OK
> > $ w3m -dump -cols 40 foo.html >foo.txt
> >
> > Convert an HTML to plain text and append the contained links
> > w3m -dump -o display_link_number=1 http://w3m.sourceforge.net >
> > index.txt
>
> Useless use of -dump! Nice example, though.
> Convert a web page to text with appended links
> $ w3m -o display_link_number=1 http://w3m.sourceforge.net > index.txt
OK
> > Conversion of file format and character encoding
> > $ cat foo.html | w3m -dump -T text/html -I EUC-JP -O UTF-8 >foo.txt
>
> Ditto (and a UUOC, but I think you can get away with one).
Now less useless use of code
> (And the file should be called "???.html"!)
What name do you propose for the file
> > Special startups
> > Start with no input, suitable as predefined command to configure
> > in window manager menus w3m -v
> > Start with a preferred set of bookmark for special purposes
> > w3m -B -bookmark links-1.html
>
> As I said, "-B -bookmark" effectively cancels out.
Example deleted
>
> Crazy stuff we don't want to have to explain
> Usenet newsreader mode (requires a server)
> $ w3m -m nntp://$NEWSSERVER/debian_curiosa/
> ...
>
> At this point I was idly considering an ERRORS section, and
> considering the fact that
>
> $ w3m http://example.org/nonesuch >/dev/null
>
> exits happily despite getting a 404. But wait, apparently the IETF
> set up a server on example.org so that page gets a 200 response! Now
> it doesn't work as an example - we would have to use something like
> "w3m http://ietf.org/nonesuch >/dev/null".
Do you suggest a section ERRORS to characterize error codes?
I got echo $? with value 0 for both http://example.org/nonesuch and
http://ietf.org/nonesuch and
I got echo $? with value 1 for mistakes like w3m -vM
> ENVIRONMENT
>
> If it finds a variable WWW_HOME in the environment, W3M will use its contents
> as a last fallback target, so that
>
> $ WWW_HOME=http://localhost/index.html
> $ w3m
>
> goes to the local web server instead of exiting with a usage message.
Such a section was introduced
> > FILES
> > ~/.w3m/config
> > user defined configuration file, overrides $/etc/w3m/config
> ;
> > ~/.w3m/keymap
> > user defined key bindings; overrides default key bindings
> >
> > ~/.w3m/menu
> > user defined menu, overrides default menu
> ;
> > ~/.w3m/mouse
> > user defined mouse settings
> >
> > ~/.w3m/cookie
> > cookie jar; written on exit, read on launch
> >
> > ~/.w3m/history
> > browser history - visited files and URLs
> >
> > ~/.w3m/passwd
> > password and username file
> >
> > ~/.w3m/pre_form
> > contains predefined values to fill recurrent HTML forms
> >
> > ~/.w3m/mailcap
> > external viewer configuration file
> >
> > ~/.w3m/mime.types
> > MIME types file
> >
> > NOTES
> > This is the W3M 0.5.3 Release.
> >
> > SEE ALSO
> > README and example files are to be found in the doc directory of your
> > W3M installation. Recent information about W3M may be found on the
> > project's web pages at http://w3m.sourceforge.net
> >
> > ACKNOWLEDGMENTS
> > W3M has incorporated code from several sources. Users have contributed
> > patches and suggestions over time.
> >
> > AUTHOR
> > Akinori ITO <aito@fw.ipsj.or.jp>
> >
> >
> >
> > 4th Berkeley Distribution 2014-10-31 W3M(1)
Hope we get ahead. I attached file the man-file, a groff-rendered file and a diff (although I doubt whether I is of great use.)
Best regards
Markus
.nr N -1
.nr D 5
.TH W3M 1 "2014-11-09"
.UC 4
.SH NAME
w3m \- a text based web browser and pager
.SH SYNOPSIS
w3m [OPTION]... [ \fIfile\fP | \fIURL\fP ]...
.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
\fIW3M\fP is as a text based browser which can display local or remote
web pages as well as other documents. It is able to process HTML
tables and frames but it ignores JavaScript and Cascading Style
Sheets. \fIW3M\fP 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.
\fIW3M\fP organizes its content in buffers or tabs, allowing easy
navigation between. With the w3m-img extension installed, W3M can
display inline graphics in web pages. And whenever \fIW3M's\fP HTML
rendering capabilities do not meet your needs, the target URL can be
handed over to a graphical browser with a single command.
For help with runtime options, press "H" while running \fIW3M\fP.
.SH ARGUMENTS
When given one or more command line arguments, \fIW3M\fP will attempt
to work out the MIME type before deciding how to handle it. Web URLs
provide \fIW3M\fP with content-type headers; for relative or absolute
file system paths, \fIW3M\fP relies on filenames.
With no argument, \fIW3M\fP expects data from STDIN and assumes
"text/plain" unless another MIME type is given by the user.
If provided with no target and no fallback target (see for instance
option -v below), \fIW3M\fP will exit with usage information.
.SH OPTIONS
Command line options are introduced with a single "-" character and
may take an argument.
.SS
to tune \fIW3M\fP
.\"generic textual-UI options
.TP
\fB-B\fP
with no other target defined, \fIW3M\fP uses the bookmark page for startup
.TP
\fB-M\fP
monochrome display
.TP
\fB-no-mouse\fP
deactivate mouse support
.TP
\fB-num\fP
display each line's number
.TP
\fB-N\fP
distribute multiple command line arguments to tabs. By default, a
stack of buffers is used.
.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. (Implementation not verified)
.TP
\fB-ppl \fIN\fR
height of N pixels per line. Range of 4.0 to 64.0. (Implementation not verified)
.TP
\fB-title\fP, \fB-title=TERM\fP
use the buffer name as terminal title string. With specified TERM,
this sets the title configuration style accordingly
.TP
\fB-v\fP
with no other target defined, \fIW3M\fP welcomes users with a built-in page
.TP
\fB-W\fP
toggle wrapping in searches
.TP
\fB-X\fP
do not initialize/deinitilize the terminal
.TP
\fB+\fIN\fR
go to line N; only effective for N larger than the number of lines in the terminal
.SS
to tune W3M's behaviour as browser
.\"to tune browser-like usage
.\"Internet browser mode options
.TP
\fB-cols \fIN\fR
with STDOUT as destination; HTML is rendered to lines of N characters
.TP
\fB-cookie\fP, \fB-no-cookie\fP
accept and use cookies, neither accept nor use cookies
.TP
\fB-header \fIstring\fR
Append string to the HTTP(S) request. Expected to match the header syntax \fC Variable: Value\fP
.TP
\fB-F\fP
render frames
.TP
\fB-graph\fP, \fB-no-graph\fP
use or do not use graphic characters for drawing HTML table and frame borders
.TP
\fB-m\fP
Internet message mode, taking message headers into account to
determine content-type (Implementation not verified)
.TP
\fB-no-proxy\fP
do not use proxy
.TP
\fB-post \fIfile\fR
use POST method to upload data defined in file. The syntax to be used is var1=value1[&var2=value2]...
.TP
\fB-4\fP
IPv4 only (equivalent to -o dns_order=4)
.TP
\fB-6\fP
IPv6 only (equivalent to -o dns_order=6)
.SS
to tune W3M's behaviour as pager
.TP
\fB-l \fIN\fR
number of lines preserved internally when receiving plain text from
STDIN (default 10 000)
.TP
\fB-r\fP
use caret notation to display special escape characters (such
as ANSI escapes or nroff-style backspaces for bold and underlined
characters) instead of processing them
.TP
\fB-s\fP
squeeze multiple blank lines into one
.TP
\fB-t\fP \fIN\fP
set tab width to N columns. No effect on STDOUT
.SS
to control the treatment of input and the generation of output data
.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
explicit characterization of input data by MIME type
.\".SS
.\"to address special targets / Command line options for a special startup
.\".TP
.\"\fB-B\fP
.\"with no other target defined, use the bookmark page
.\"to process or to request for data; immediate termination thereafter
.\".TP
.\"\fB-v\fP
.\"with no other target defined, use the built-in W3M startup-page
.SS to process or to request for data; immediate exit thereafter
.TP
\fB-dump\fP
dump rendered page into STDOUT. "|" for pipe and ">" for
redirection of output set this option implicitly
.TP
\fB-dump_source\fP
dump the page's source code into STDOUT
.TP
\fB-dump_head\fP
dump response of a HEAD request for a URL into STDOUT
.TP
\fB-dump_both\fP
dump HEAD, and source code for a URL into STDOUT
.TP
\fB-dump_extra\fP
dump HEAD, source code, and extra information for a URL into STDOUT
.TP
\fB-help\fP
show a summary of compiled-in and runtime options
.TP
\fB-show-option\fP
show all available config options
.TP
\fB-version\fP
show the version of \fIW3M\fP
.\".SS
.\"miscelleneous options
.SS
to override default settings and resources
.\" in \fC~/.w3m/\fP, see FILES
.TP
\fB-bookmark \fIfile\fR
use file instead of the default bookmark.html file
.TP
\fB-config \fIfile\fR
use file instead of the default config file
.TP
\fB-debug\fP
DO NOT USE
.TP
\fB-o \fIoption=value\fR
modify one configuration item with an explicitely given value
.TP
\fB-reqlog\fP
log headers of HTTP communication in file \fC~/.w3m/request.log\fP
.SH EXAMPLES
.TP
Pager-like usage
.\" of \fIW3M\fP
.\" \fBW3M\fP as a text pager
.br
Combine snippets of html code and preview the page
.br
\ \fC$ cat header.html footer.html | w3m -T text/html \fP
.br
Compare two files using tabs
.br
\ \fC$ w3m -N config.old config \fP
.TP
Browser-like usage
.\" of \fIW3M\fP
.\" \fBW3M\fP as an HTML renderer
.br
Display web content in monochrome terminal
.br
\ \fC$ w3m -M http://w3m.sourceforge.net\fP
.br
Display embedded graphics
.br
\ \fC$ w3m -o auto_image=TRUE http://w3m.sourceforge.net\fP
.br
Display content from usenet
.br
\ \fC$ w3m -m nntp://$NEWSSERVER/debian_curiosa/\fP
.br
Upload data for a URL using the POST method
.\".br
.\"\fC$ echo 'text=abc&count=123' > file.txt
.\".br
.\"w3m -post file.txt http://data.com/pit.php\fP
.\".br
.br
\ \fC$ w3m -post - http://data.com/pit.php <<< 'text=abc&count=123'\fP
.TP
Filter-like usage
.\" of \fIW3M\fP
.br
Convert an HTML file to a plain text file with a defined line length
.br
\ \fC$ w3m -dump -cols 40 foo.html >foo.txt\fP
.br
Convert a web page to text with appended links
.br
\ \fC$ w3m -o display_link_number=1 http://w3m.sourceforge.net > index.txt\fP
.br
Conversion of file format and character encoding
.br
\ \fC$ w3m -T text/html -I EUC-JP -O UTF-8 < foo.html > foo.txt\fP
.TP
Start with no input
.\", suitable as predefined command to configure in window manager menus
.br
\ \fC$ w3m -v\fP
.\".SH Errors
.SH ENVIRONMENT
.TP
LANG
Localize to language and country
.\"MAILER
.\"NNTPSERVER
.\"PAGER
.TP
SHELL
Shell
.TP
TERM
Terminal
.TP
TMPDIR
Temporary data file
.TP
WWW_HOME
Defines a fallback target if W3M is invoked with no data to process
.SH FILES
.TP
\fC~/.w3m/config\fP
user defined configuration file, overrides \fC$/etc/w3m/config\fP
.TP
\fC~/.w3m/keymap\fP
user defined key bindings; overrides default key bindings
.TP
\fC~/.w3m/menu\fP
user defined menu, overrides default menu
.TP
\fC~/.w3m/mouse\fP
user defined mouse settings
.TP
\fC~/.w3m/mailcap\fP
external viewer configuration file
.TP
\fC~/.w3m/mime.types\fP
MIME types file
.TP
\fC~/.w3m/cookie\fP
cookie jar; written on exit, read on launch
.TP
\fC~/.w3m/history\fP
browser history - visited files and URLs
.TP
\fC~/.w3m/passwd\fP
password and username file
.TP
\fC~/.w3m/pre_form\fP
contains predefined values to fill recurrent HTML forms
.TP
\fC~/.w3m/bookmark.html\fP
default bookmark file
.\" .TP
.\" .I $~/.w3m/urimethodmap
.\" ???
.SH NOTES
This is the \fIW3M\fP 0.5.3 Release.
.SH "SEE ALSO"
README and example files are to be found in the doc directory of your \fIW3M\fP installation. Recent information about \fIW3M\fP may be found on the project's web pages at http://w3m.sourceforge.net
.SH ACKNOWLEDGMENTS
\fIW3M\fP has incorporated code from several sources.
Users have contributed patches and suggestions over time.
.SH AUTHOR
Akinori ITO <aito@fw.ipsj.or.jp>
W3M(1) W3M(1)
NAME
w3m - a text based web browser and pager
SYNOPSIS
w3m [OPTION]... [ file | URL ]...
DESCRIPTION
W3M is as a text based browser which can display local or remote web
pages as well as other documents. It is able to process HTML tables and
frames but it ignores JavaScript and Cascading Style 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.
W3M organizes its content in buffers or tabs, allowing easy navigation
between. With the w3m-img extension installed, W3M can display inline
graphics in web pages. And whenever W3M's HTML rendering capabilities
do not meet your needs, the target URL can be handed over to a graphi-
cal browser with a single command.
For help with runtime options, press "H" while running W3M.
ARGUMENTS
When given one or more command line arguments, W3M will attempt to work
out the 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.
With no argument, W3M expects data from STDIN and assumes "text/plain"
unless another MIME type is given by the user.
If provided with no target and no fallback target (see for instance
option -v below), W3M will exit with usage information.
OPTIONS
Command line options are introduced with a single "-" character and may
take an argument.
to tune W3M
-B with no other target defined, W3M uses the bookmark page for
startup
-M monochrome display
-no-mouse
deactivate mouse support
-num display each line's number
-N distribute multiple command line arguments to tabs. By default,
a stack of buffers is used.
-ppc N width of N pixels per character. Range of 4.0 to 32.0, default
8.0. Larger values will make tables narrower. (Implementation
not verified)
-ppl N height of N pixels per line. Range of 4.0 to 64.0. (Implementa-
tion not verified)
-title, -title=TERM
use the buffer name as terminal title string. With specified
TERM, this sets the title configuration style accordingly
-v with no other target defined, W3M welcomes users with a built-in
page
-W toggle wrapping in searches
-X do not initialize/deinitilize the terminal
+N go to line N; only effective for N larger than the number of
lines in the terminal
to tune W3M's behaviour as browser
-cols N
with STDOUT as destination; HTML is rendered to lines of N char-
acters
-cookie, -no-cookie
accept and use cookies, neither accept nor use cookies
-header string
Append string to the HTTP(S) request. Expected to match the
header syntax Variable: Value
-F render frames
-graph, -no-graph
use or do not use graphic characters for drawing HTML table and
frame borders
-m Internet message mode, taking message headers into account to
determine content-type (Implementation not verified)
-no-proxy
do not use proxy
-post file
use POST method to upload data defined in file. The syntax to be
used is var1=value1[&var2=value2]...
-4 IPv4 only (equivalent to -o dns_order=4)
-6 IPv6 only (equivalent to -o dns_order=6)
to tune W3M's behaviour as pager
-l N number of lines preserved internally when receiving plain text
from STDIN (default 10 000)
-r use caret notation to display special escape characters (such as
ANSI escapes or nroff-style backspaces for bold and underlined
characters) instead of processing them
-s squeeze multiple blank lines into one
-t N set tab width to N columns. No effect on STDOUT
to control the treatment of input and the generation of output data
-I charset
user defined character encoding of input data
-O charset
user defined character encoding of output data
-T type
explicit characterization of input data by MIME type
to process or to request for data; immediate exit thereafter
-dump dump rendered page into STDOUT. "|" for pipe and ">" for redi-
rection of output set this option implicitly
-dump_source
dump the page's source code into STDOUT
-dump_head
dump response of a HEAD request for a URL into STDOUT
-dump_both
dump HEAD, and source code for a URL into STDOUT
-dump_extra
dump HEAD, source code, and extra information for a URL into
STDOUT
-help show a summary of compiled-in and runtime options
-show-option
show all available config options
-version
show the version of W3M
to override default settings and resources
-bookmark file
use file instead of the default bookmark.html file
-config file
use file instead of the default config file
-debug DO NOT USE
-o option=value
modify one configuration item with an explicitely given value
-reqlog
log headers of HTTP communication in file ~/.w3m/request.log
EXAMPLES
Pager-like usage
Combine snippets of html code and preview the page
$ cat header.html footer.html | w3m -T text/html
Compare two files using tabs
$ w3m -N config.old config
Browser-like usage
Display web content in monochrome terminal
$ w3m -M http://w3m.sourceforge.net
Display embedded graphics
$ w3m -o auto_image=TRUE http://w3m.sourceforge.net
Display content from usenet
$ w3m -m nntp://$NEWSSERVER/debian_curiosa/
Upload data for a URL using the POST method
$ w3m -post - http://data.com/pit.php <<< 'text=abc&count=123'
Filter-like usage
Convert an HTML file to a plain text file with a defined line
length
$ w3m -dump -cols 40 foo.html >foo.txt
Convert a web page to text with appended links
$ w3m -o display_link_number=1 http://w3m.sourceforge.net >
index.txt
Conversion of file format and character encoding
$ w3m -T text/html -I EUC-JP -O UTF-8 < foo.html > foo.txt
Start with no input
$ w3m -v
ENVIRONMENT
LANG Localize to language and country
SHELL Shell
TERM Terminal
TMPDIR Temporary data file
WWW_HOME
Defines a fallback target if W3M is invoked with no data to
process
FILES
~/.w3m/config
user defined configuration file, overrides $/etc/w3m/config
~/.w3m/keymap
user defined key bindings; overrides default key bindings
~/.w3m/menu
user defined menu, overrides default menu
~/.w3m/mouse
user defined mouse settings
~/.w3m/mailcap
external viewer configuration file
~/.w3m/mime.types
MIME types file
~/.w3m/cookie
cookie jar; written on exit, read on launch
~/.w3m/history
browser history - visited files and URLs
~/.w3m/passwd
password and username file
~/.w3m/pre_form
contains predefined values to fill recurrent HTML forms
~/.w3m/bookmark.html
default bookmark file
NOTES
This is the W3M 0.5.3 Release.
SEE ALSO
README and example files are to be found in the doc directory of your
W3M installation. Recent information about W3M may be found on the
project's web pages at http://w3m.sourceforge.net
ACKNOWLEDGMENTS
W3M has incorporated code from several sources. Users have contributed
patches and suggestions over time.
AUTHOR
Akinori ITO <aito@fw.ipsj.or.jp>
4th Berkeley Distribution 2014-11-09 W3M(1)
--- w3m_3.1.txt 2014-11-09 20:38:59.000000000 +0100
+++ w3m_4.1.txt 2014-11-09 20:38:52.000000000 +0100
@@ -3,126 +3,124 @@
NAME
- W3M - a text based web browser and pager
+ w3m - a text based web browser and pager
SYNOPSIS
- w3m [OPTIONS|... [ file | URL ]...
+ w3m [OPTION]... [ file | URL ]...
DESCRIPTION
- W3M has been developed as a text based web client. It displays HTML
- documents stored local or on remote systems. It renders HTML tables and
- frames. W3M ignores JavaScript and Cascading Style Sheets. It accepts
- plain text from files or from standard input, serving as a "pager" in
- much the same manner as "more" or "less".
-
-
- W3M organizes content in buffers and tabs, allowing easy navigation
- between. Having the extra package with w3m-img installed, W3M shows
- graphics within a page or in a new buffer. Whenever W3M's capabilities
- to render HTML do no meet your needs, the target URL can be handed over
- to a graphic browser by a single command.
-
+ W3M is as a text based browser which can display local or remote web
+ pages as well as other documents. It is able to process HTML tables and
+ frames but it ignores JavaScript and Cascading Style 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.
+
+ W3M organizes its content in buffers or tabs, allowing easy navigation
+ between. With the w3m-img extension installed, W3M can display inline
+ graphics in web pages. And whenever W3M's HTML rendering capabilities
+ do not meet your needs, the target URL can be handed over to a graphi-
+ cal browser with a single command.
For help with runtime options, press "H" while running W3M.
ARGUMENTS
- If given one argument or more arguments, W3M works like a browser. Hav-
- ing recieved a URL, the respective content is worked out according to
- the MIME type. With relative or absolute paths as argument, W3M relies
- on filenames to display the content in an adequate manner.
-
-
- With no argument, W3M expects data from STDIN. Input given by the user
- may be necessary the control how these data processed further.
-
-
- With no explicite targets and no stream of data from STDIN, W3M exits
- with usage information.
+ When given one or more command line arguments, W3M will attempt to work
+ out the 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.
+ With no argument, W3M expects data from STDIN and assumes "text/plain"
+ unless another MIME type is given by the user.
+ If provided with no target and no fallback target (see for instance
+ option -v below), W3M will exit with usage information.
OPTIONS
- Options are introduced with a dash and may take an argument
+ Command line options are introduced with a single "-" character and may
+ take an argument.
- Options to select predefined configurations and resources
- -config file
- use file instead of the default configuration file ~/.w3m/config
+ to tune W3M
+ -B with no other target defined, W3M uses the bookmark page for
+ startup
- -bookmark file
- specifies another bookmark file to be used
-
- -reqlog
- log headers of HTTP communication in file ~/.w3m/request.log
+ -M monochrome display
- -debug DO NOT USE
+ -no-mouse
+ deactivate mouse support
- -o option=value
- modify one configuration item with an explicitely given value
+ -num display each line's number
+ -N distribute multiple command line arguments to tabs. By default,
+ a stack of buffers is used.
- Tuning W3M / Options to tune Program-User-Interaction / Man-Machine-Inter-
- face
- -title use the buffer name as terminal title string.
-
- -title=TERM
- use the buffer name as terminal title string. TERM style title
- configuration is used
- Implementation not verified
+ -ppc N width of N pixels per character. Range of 4.0 to 32.0, default
+ 8.0. Larger values will make tables narrower. (Implementation
+ not verified)
- -no-mouse
- do not use mouse
+ -ppl N height of N pixels per line. Range of 4.0 to 64.0. (Implementa-
+ tion not verified)
- -num display each line's number
+ -title, -title=TERM
+ use the buffer name as terminal title string. With specified
+ TERM, this sets the title configuration style accordingly
- -M monochrome display
+ -v with no other target defined, W3M welcomes users with a built-in
+ page
-W toggle wrapping in searches
-X do not initialize/deinitilize the terminal
- Implementation not verified
- -ppc N width of N pixels per character. Range of 4.0 to 32.0, default
- 8.0. Larger values will make tables narrower.
- Implementation not verified
-
- -ppl N height of N pixels per line. Range of 4.0 to 64.0.
- Implementation not verified
-
-
- Command line options for a browser-like usage
- -F render frames
+ +N go to line N; only effective for N larger than the number of
+ lines in the terminal
- -N distribute the contents passed with multiple command line argu-
- ments to tabs. By default, a stack of buffers is used.
+ to tune W3M's behaviour as browser
+ -cols N
+ with STDOUT as destination; HTML is rendered to lines of N char-
+ acters
-cookie, -no-cookie
accept and use cookies, neither accept nor use cookies
+ -header string
+ Append string to the HTTP(S) request. Expected to match the
+ header syntax Variable: Value
+
+ -F render frames
+
-graph, -no-graph
- use or do not use graphic characters for borders of frames and
- tables
+ use or do not use graphic characters for drawing HTML table and
+ frame borders
+
+ -m Internet message mode, taking message headers into account to
+ determine content-type (Implementation not verified)
-no-proxy
do not use proxy
+ -post file
+ use POST method to upload data defined in file. The syntax to be
+ used is var1=value1[&var2=value2]...
+
-4 IPv4 only (equivalent to -o dns_order=4)
-6 IPv6 only (equivalent to -o dns_order=6)
- -m Internet message mode
- Implementation not verified
+ to tune W3M's behaviour as pager
+ -l N number of lines preserved internally when receiving plain text
+ from STDIN (default 10 000)
- Command line options for a pager-like usage
- -r ignore underline or bolding markup constructions that use
- backspace (e.g. in nroff)
+ -r use caret notation to display special escape characters (such as
+ ANSI escapes or nroff-style backspaces for bold and underlined
+ characters) instead of processing them
-s squeeze multiple blank lines into one
-t N set tab width to N columns. No effect on STDOUT
-
- Options to control treatment of data input and output
+ to control the treatment of input and the generation of output data
-I charset
user defined character encoding of input data
@@ -132,22 +130,9 @@
-T type
explicit characterization of input data by MIME type
-
- Command line options for a special startup
- -v allow start with no defined input via STDIN, file or URL
-
- -B start with default bookmark file ~/.w3m/bookmark.html
-
- -show-option
- show all available config options
-
- -help show a summary of compiled-in and runtime options
-
- -version
- show the version of W3M ()
-
- Options for instant data requests
- -dump dump rendered page into STDOUT
+ to process or to request for data; immediate exit thereafter
+ -dump dump rendered page into STDOUT. "|" for pipe and ">" for redi-
+ rection of output set this option implicitly
-dump_source
dump the page's source code into STDOUT
@@ -159,59 +144,76 @@
dump HEAD, and source code for a URL into STDOUT
-dump_extra
- dump HEAD, source code, and extra information for a URL into
- STDOUT ()
+ dump HEAD, source code, and extra information for a URL into
+ STDOUT
+ -help show a summary of compiled-in and runtime options
- Miscelleneous command line options
- +N go to line N; only effective for N larger than the number of
- lines in the terminal
+ -show-option
+ show all available config options
- -cols N
- combined with -dump, HTML input is rendered to lines of N char-
- acters. Affects only STDOUT
+ -version
+ show the version of W3M
- -l N number of lines preserved internally when recieving plain text
- from STDIN (default 10 000)
+ to override default settings and resources
+ -bookmark file
+ use file instead of the default bookmark.html file
- -post file
- use POST method with file content
- Implementation not verified
+ -config file
+ use file instead of the default config file
- -header string
- APPEND string to the HTTP(S) request. Expected to match the
- header syntax Variable: Value
+ -debug DO NOT USE
+
+ -o option=value
+ modify one configuration item with an explicitely given value
+
+ -reqlog
+ log headers of HTTP communication in file ~/.w3m/request.log
EXAMPLES
- Pager-like usage of W3M | W3M as a text pager
+ Pager-like usage
Combine snippets of html code and preview the page
- $ cat header.html footer.html | w3m -T text/html fP
-
- Browser-like usage of W3M | W3M as an HTML renderer
- Display web content in monochromous terminals
- $ w3m -M http://w3m.sourceforge.net
+ $ cat header.html footer.html | w3m -T text/html
+ Compare two files using tabs
+ $ w3m -N config.old config
+
+ Browser-like usage
+ Display web content in monochrome terminal
+ $ w3m -M http://w3m.sourceforge.net
Display embedded graphics
- w3m -o auto_image=TRUE http://w3m.sourceforge.net
+ $ w3m -o auto_image=TRUE http://w3m.sourceforge.net
+ Display content from usenet
+ $ w3m -m nntp://$NEWSSERVER/debian_curiosa/
+ Upload data for a URL using the POST method
+ $ w3m -post - http://data.com/pit.php <<< 'text=abc&count=123'
+
+ Filter-like usage
+ Convert an HTML file to a plain text file with a defined line
+ length
+ $ w3m -dump -cols 40 foo.html >foo.txt
+ Convert a web page to text with appended links
+ $ w3m -o display_link_number=1 http://w3m.sourceforge.net >
+ index.txt
+ Conversion of file format and character encoding
+ $ w3m -T text/html -I EUC-JP -O UTF-8 < foo.html > foo.txt
+
+ Start with no input
+ $ w3m -v
+
+
+
+ENVIRONMENT
+ LANG Localize to language and country
+
+ SHELL Shell
- Filter-like usage of W3M
+ TERM Terminal
- Convert an HTML file to a plain text file with a defined length of
- lines
- $ w3m -dump -cols 40 foo.html >foo.txt
-
- Convert an HTML to plain text and append the contained links
- w3m -dump -o display_link_number=1 http://w3m.sourceforge.net >
- index.txt
-
- Conversion of file format and character encoding
- $ cat foo.html | w3m -dump -T text/html -I EUC-JP -O UTF-8 >foo.txt
-
- Special startups
- Start with no input, suitable as predefined command to configure
- in window manager menus w3m -v
- Start with a preferred set of bookmark for special purposes
- w3m -B -bookmark links-1.html
+ TMPDIR Temporary data file
+ WWW_HOME
+ Defines a fallback target if W3M is invoked with no data to
+ process
FILES
@@ -227,6 +229,12 @@
~/.w3m/mouse
user defined mouse settings
+ ~/.w3m/mailcap
+ external viewer configuration file
+
+ ~/.w3m/mime.types
+ MIME types file
+
~/.w3m/cookie
cookie jar; written on exit, read on launch
@@ -239,18 +247,15 @@
~/.w3m/pre_form
contains predefined values to fill recurrent HTML forms
- ~/.w3m/mailcap
- external viewer configuration file
-
- ~/.w3m/mime.types
- MIME types file
+ ~/.w3m/bookmark.html
+ default bookmark file
NOTES
This is the W3M 0.5.3 Release.
SEE ALSO
- README and example files are to be found in the doc directory of your
- W3M installation. Recent information about W3M may be found on the
+ README and example files are to be found in the doc directory of your
+ W3M installation. Recent information about W3M may be found on the
project's web pages at http://w3m.sourceforge.net
ACKNOWLEDGMENTS
@@ -262,4 +267,4 @@
-4th Berkeley Distribution 2014-10-31 W3M(1)
+4th Berkeley Distribution 2014-11-09 W3M(1)
Reply to: