Subject: Improve English documents
Author: Markus Hiereth <post@hiereth.de>, Justin B Rye <justin.byam.rye@gmail.com>
Origin: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=766550
Origin: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=771003
diff --git a/doc/w3m.1 b/doc/w3m.1
index 58a8965..0762f51 100644
--- a/doc/w3m.1
+++ b/doc/w3m.1
@@ -1,13 +1,11 @@
.nr N -1
.nr D 5
-.TH W3M 1 Local
+.TH W3M 1 "2014-11-29"
.UC 4
.SH NAME
-w3m \- a text based Web browser and pager
+w3m \- a text based web browser and pager
.SH SYNOPSIS
-.B w3m
-[options] [URL or filename]
-.PP
+w3m [OPTION]... [ \fIfile\fP | \fIURL\fP ]...
.SH DESCRIPTION
.\" This defines appropriate quote strings for nroff and troff
.ds lq \&"
@@ -17,234 +15,285 @@ w3m \- a text based Web browser and pager
.\" Just in case these number registers aren't set yet...
.if \nN==0 .nr N 10
.if \nD==0 .nr D 5
-.I
-w3m
-is a World Wide Web (WWW) text based client. It has English and
-Japanese help files and an option menu and can be configured to
-use either language. It will display hypertext markup language
-(HTML) documents containing links to files residing on the local
-system, as well as files residing on remote systems. It can
-display HTML tables and frames.
-In addition, it can be used as a "pager" in much the same manner
-as "more" or "less".
-Current versions of
-.I
-w3m
-run on
-Unix (Solaris, SunOS, HP-UX, Linux, FreeBSD, and EWS4800)
-and on
-Microsoft Windows 9x/NT.
-.PP
+
+\fIw3m\fP is 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 pager for text files named as
+arguments or passed on standard input, and as a general purpose
+directory browser.
+
+\fIw3m\fP organizes its content in buffers or tabs, allowing easy
+navigation between them. With the w3m-img extension installed, \fIw3m\fP can
+display inline graphics in web pages. And whenever \fIw3m\fP's 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 \(lqH\(rq while running \fIw3m\fP.
+
+.SH ARGUMENTS
+
+When given one or more command line arguments, \fIw3m\fP will handle
+targets according to content type. For web, \fIw3m\fP gets this
+information from HTTP headers; for relative or absolute file system
+paths, it relies on filenames.
+
+With no argument, \fIw3m\fP expects data from standard input and
+assumes \(lqtext/plain\(rq unless another MIME type is given by the user.
+
+If provided with no target and no fallback target (see for instance
+option \fB\-v\fP below), \fIw3m\fP will exit with usage information.
.SH OPTIONS
-At start up, \fIw3m\fR will load any local
-file or remote URL specified at the command
-line. For help with runtime options, press \fB"H"\fR
-while running \fIw3m\fR.
-Command line options are:
-.PP
+Command line options are introduced with a single \(lq\-\(rq character and
+may take an argument.
+.SS General options:
.TP
-.B -t tab
-set tab width
+\fB\-B\fP
+with no other target defined, use the bookmark page for startup
.TP
-.B -r
-ignore backspace effect
-.TP
-.B -l line
-# of preserved line (default 10000)
-.TP
-.B -I charset
-document charset
-.TP
-.B -O charset
-display/output charset
+\fB\-M\fP
+monochrome display
.TP
-.B -B
-load bookmark
+\fB\-no-mouse\fP
+deactivate mouse support
.TP
-.B -bookmark file
-specify bookmark file
+\fB\-num\fP
+display each line's number
.TP
-.B -T type
-specify content-type
+\fB\-N\fP
+distribute multiple command line arguments to tabs. By default, a
+stack of buffers is used
+.TP
+\fB\-ppc \fInum\fR
+width of \fInum\fR pixels per character. Range of 4.0 to 32.0, default 8.0.
+Larger values will make tables narrower. (Implementation not verified)
.TP
-.B -m
-internet message mode
+\fB\-ppl \fInum\fR
+height of \fInum\fR pixels per line. Range of 4.0 to 64.0. (Implementation not verified)
.TP
-.B -v
-visual startup mode
+\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
-.B -M
-monochrome display
+\fB\-v\fP
+with no other target defined, welcome users with a built-in page
.TP
-.B -N
-open URL of command line on each new tab
+\fB\-W\fP
+toggle wrapping in searches
.TP
-.B -F
-automatically render frame
+\fB\-X\fP
+do not initialize/deinitialize the terminal
.TP
-.B -dump
-dump formatted page into stdout
+\fB+\fInum\fR
+go to line \fInum\fR; only effective for \fInum\fR larger than the number of lines in the terminal
+.SS Browser options:
.TP
-.B -cols width
-specify column width (used with -dump)
+\fB\-cols \fInum\fR
+with stdout as destination; HTML is rendered to lines of \fInum\fR characters
.TP
-.B -ppc count
-specify the number of pixels per character (4.0...32.0).
-Larger values will make tables narrower. [default 8.0]
+\fB\-cookie\fP, \fB\-no-cookie\fP
+use stored cookies and accept new ones, or do neither
.TP
-.B -ppl count
-specify the number of pixels per line (4.0...64.0)
+\fB\-F\fP
+render frames
.TP
-.B -dump_source
-dump page source into stdout
+\fB\-graph\fP, \fB\-no-graph\fP
+use or do not use graphic characters for drawing HTML table and frame borders
.TP
-.B -dump_head
-dump response of HEAD request into stdout
+\fB\-header \fIstring\fR
+append \fIstring\fR to the HTTP(S) request. Expected to match the header syntax \f(CW Variable: Value\fP
.TP
-.B -dump_both
-dump HEAD and source into stdout
+\fB\-m\fP
+Render the body of Usenet messages according to the header \(lqContent-type\(rq
.TP
-.B -dump_extra
-dump HEAD, source, and extra information into stdout
+\fB\-no-proxy\fP
+do not use proxy
.TP
-.B -post file
-use POST method with file content
+\fB\-post \fIfile\fR
+use POST method to upload data defined in \fIfile\fR. The syntax to be used
+is \f(CWvar1=value1[&var2=value2]...\fP
.TP
-.B -header string
-insert string as a header
+\fB\-4\fP
+IPv4 only. Corresponds to dns_order=4 in configuration files
.TP
-.B +<num>
-goto <num> line
+\fB\-6\fP
+IPv6 only. Corresponds to dns_order=6 in configuration files
+.SS Text pager options:
.TP
-.B -num
-show line number
+\fB\-l \fInum\fR
+number of lines preserved internally when receiving plain text from
+stdin (default 10,000)
.TP
-.B -no-proxy
-don't use proxy
+\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
-.B -4
-IPv4 only (-o dns_order=4)
+\fB\-s\fP
+squeeze multiple blank lines into one
.TP
-.B -6
-IPv6 only (-o dns_order=6)
+\fB\-t\fP \fInum\fP
+set tab width to \fInum\fR columns. No effect on stdout
+.SS Data type/encoding options:
.TP
-.B -no-mouse
-don't use mouse
+\fB\-I \fIcharset\fR
+user defined character encoding of input data
.TP
-.B -cookie
-use cookie.
+\fB\-O \fIcharset\fR
+user defined character encoding of output data
.TP
-.B -no-cookie
-don't use cookie
+\fB\-T \fItype\fR
+explicit characterization of input data by MIME type
+.SS Options for data output, followed by immediate exit:
.TP
-.B -graph
-use graphic character
+\fB\-dump\fP
+dump rendered page into stdout. Set implicitly when output is directed
+to a file or pipe
.TP
-.B -no-graph
-don't use graphic character
+\fB\-dump_source\fP
+dump the page's source code into stdout
.TP
-.B -s
-squeeze multiple blank lines
+\fB\-dump_head\fP
+dump response of a HEAD request for a URL into stdout
.TP
-.B -W
-toggle wrap search mode
+\fB\-dump_both\fP
+dump HEAD, and source code for a URL into stdout
.TP
-.B -X
-don't use termcap init/deinit
+\fB\-dump_extra\fP
+dump HEAD, source code, and extra information for a URL into stdout
.TP
-.B -title [=TERM]
-set buffer name to terminal title string.
-If TERM is specified, use the TERM style title configuration.
+\fB\-help\fP
+show a summary of compiled-in features and command line options
.TP
-.B -o opt=value
-assign value to config option
+\fB\-show-option\fP
+show all available config options
.TP
-.B -show-option
-show all available config option
+\fB\-version\fP
+show the version of \fIw3m\fP
+.SS Options for overriding default settings and resources:
.TP
-.B -config file
-specify config file
+\fB\-bookmark \fIfile\fR
+use \fIfile\fR instead of the default bookmark.html file
.TP
-.B -help
-show usage
+\fB\-config \fIfile\fR
+use \fIfile\fR instead of the default config file
.TP
-.B -version
-show w3m version
+\fB\-debug\fP
+DO NOT USE
.TP
-.B -reqlog
-write request logfile
+\fB\-o \fIoption=value\fR
+modify one configuration item with an explicitly given value; without \fIoption=value\fR, equivalent to -show-option
.TP
-.B -debug
-DO NOT USE
+\fB\-reqlog\fP
+log headers of HTTP communication in file \f(CW~/.w3m/request.log\fP
.SH EXAMPLES
+.SS Pager-like usage
+.TP
+Combine snippets of HTML code and preview the page
+.EX
+$ cat header.html footer.html | w3m -T text/html
+.EE
+.TP
+Compare two files using tabs
+.EX
+$ w3m -N config.old config
+.EE
+.SS Browser-like usage
+.TP
+Display web content in monochrome terminal
+.EX
+$ w3m -M http://w3m.sourceforge.net
+.EE
+.TP
+Display embedded graphics
+.EX
+$ w3m -o auto_image=TRUE http://w3m.sourceforge.net
+.EE
+.TP
+Display content from Usenet
+.EX
+$ w3m -m nntp://news.aioe.org/comp.os.linux.networking
+.EE
+.TP
+Upload data for a URL using the POST method
+.EX
+$ w3m -post - http://example.com/form.php <<<'a=0&b=1'
+.EE
+.SS Filter-like usage
+.TP
+Convert an HTML file to plain text with a defined line length
+.EX
+$ w3m -cols 40 foo.html > foo.txt
+.EE
+.TP
+Output the bookmarks page as text with an appended list of links
+.EX
+$ w3m -B -o display_link_number=1 > out.txt
+.EE
+.TP
+Conversion of file format and character encoding
+.EX
+$ w3m -T text/html -I EUC-JP -O UTF-8 < foo.html > foo.txt
+.EE
+.SS Start with no input
+.TP
+Welcome users with a built-in page
+.EX
+$ w3m -v
+.EE
+.\".SH Errors
+.SH ENVIRONMENT
+\fIw3m\fP recognises the environment variable WWW_HOME as defining a
+fallback target for use if it is invoked without one.
+.SH FILES
.TP
-To use w3m as a pager:
-.br
-$ ls | w3m
-.br
-.TP
-To use w3m to translate HTML files:
-.br
-$ cat foo.html | w3m -T text/html
+\f(CW~/.w3m/bookmark.html\fP
+default bookmark file
.TP
-or
-.br
-$ cat foo.html | w3m -dump -T text/html >foo.txt
-.SH FILES
+\f(CW~/.w3m/config\fP
+user defined configuration file; overrides \f(CW/etc/w3m/config\fP
.TP
-.I ${HOME}/.w3m/config
-configuration file
+\f(CW~/.w3m/cookie\fP
+cookie jar; written on exit, read on launch
.TP
-.I ${HOME}/.w3m/keymap
-key binding configuration file
-.\" .TP
-.\" .I ${HOME}/.w3m/menu
-.\" ???
+\f(CW~/.w3m/history\fP
+browser history - visited files and URLs
.TP
-.I ${HOME}/.w3m/mouse
-mouse configuration file
+\f(CW~/.w3m/keymap\fP
+user defined key bindings; overrides default key bindings
.TP
-.I ${HOME}/.w3m/cookie
-cookie file
+\f(CW~/.w3m/mailcap\fP
+external viewer configuration file
.TP
-.I ${HOME}/.w3m/history
-history file
+\f(CW~/.w3m/menu\fP
+user defined menu; overrides default menu
.TP
-.I ${HOME}/.w3m/passwd
-passowrd and username file
+\f(CW~/.w3m/mime.types\fP
+MIME types file
.TP
-.I ${HOME}/.w3m/pre_form
-form parameters file
+\f(CW~/.w3m/mouse\fP
+user defined mouse settings
.TP
-.I ${HOME}/.w3m/mailcap
-external viewer configuration file
+\f(CW~/.w3m/passwd\fP
+password and username file
.TP
-.I ${HOME}/.w3m/mime.types
-MIME types file
+\f(CW~/.w3m/pre_form\fP
+contains predefined values to fill recurrent HTML forms
.\" .TP
-.\" .I ${HOME}/.w3m/urimethodmap
+.\" .I $~/.w3m/urimethodmap
.\" ???
.SH NOTES
-This is the
-.I
-w3m
-0.5.3 Release.
-.PP
-Please see the MANUAL.html file distributed with w3m for
-more detailed documentation.
-
-Additional information about
-.I
-w3m
-may be found on its Japanese language Web site located at:
- http://w3m.sourceforge.net/index.ja.html
-.br
-or on its English version of the site at:
- http://w3m.sourceforge.net/index.en.html
+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
+.UR http://w3m.sourceforge.net
+the project's web pages at
+.UE
.SH ACKNOWLEDGMENTS
-.I
-w3m
-has incorporated code from several sources.
+\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>
+.UR aito@fw.ipsj.or.jp
+Akinori ITO
+.UE
+
diff --git a/scripts/w3mman/w3mman.1.in b/scripts/w3mman/w3mman.1.in
index 1c0361d..1b1d990 100644
--- a/scripts/w3mman/w3mman.1.in
+++ b/scripts/w3mman/w3mman.1.in
@@ -1,4 +1,4 @@
-.TH W3MMAN 1 "Nov 5, 2005"
+.TH W3MMAN 1 "Nov 23, 2014"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
@@ -12,19 +12,19 @@
.\" .sp <n> insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
-w3mman \- an interface to the on-line reference manuals by w3m(1)
+w3mman \- an interface to the on-line reference manuals via w3m(1)
.SH SYNOPSIS
.B w3mman
-.RI "[-M " path ] " " [ section ] " page"
+.RI "[\-M " path ] " " [ section ] " page"
.br
.B w3mman
-.RI "[-M " path "] -k " keyword
+.RI "[\-M " path "] \-k " keyword
.br
.B w3mman
-.RI -l " file
+.RI \-l " file
.SH DESCRIPTION
.B w3mman
-is the system's manual pager by
+is a pager for manual pages, using
.BR w3m (1).
.SH OPTIONS
A summary of options is included below.
@@ -42,6 +42,7 @@ Specify
Specify a
.I file.
.SH ENVIRONMENT
+Two variables are available for debugging.
.TP
.B W3MMAN_W3M
If W3MMAN_W3M is set, its value is used instead of @W3M@.
@@ -51,7 +52,7 @@ If W3MMAN_MAN is set, its value is used instead of @MAN@.
.SH FILES
.TP
.I @libexecdir@/@PACKAGE@/cgi-bin/w3mman2html.cgi
-convert manual page to html.
+manual page to HTML convertor.
.SH SEE ALSO
.BR man (1),
.BR w3m (1).
