[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: FAQ.html and MANUAL.html, was Re: fwd: Re: Re: Please review changed man-file of w3m

(Another omnibus reply.)

markus.hiereth@freenet.de wrote:
>>> C-g              Show current page position
[...]
> C-g for default and C-g for Lynx-like key binding produce the same
> LINE_INFO command. With it, I get the current vertical (line) and
> horizontal (column) position of the cursor and a character encoding
> set is mentioned.

It seems odd that it would include that encoding part instead of, say,
the file's size in bytes, but I'm just going to ignore that.

[...]
>>> Mouse operation
[...]
       
I checked, and it is still true that rxvt needs TERM=xterm, but I've
rephrased it a bit more anyway.
   
[...]
>> Trickier: on Debian those keymap files aren't
>> sitting in the same directory, so the links fail.
> 
> There are three sections of the MANUAL.html closely related: "Key
> customization", "Key Binding" and "Lynx-like key binding". From my
> point of view, "Key customization" should be the heading. The role of
> the keymap file and its syntax should be explained. Then, one table
> could explain a function in one column and one column gives the
> defauld key combination, another column the Lynx-like key
> combinantion.

You're right, that would be a far better approach, but I'm not going
to consider starting on that sort of major surgery just yet (there's a
risk I'll be offline over Christmas).
 
> Maybe HELP and README.functions would deserve being a section of
> MANUAL.html

Possibly, though all the functions that aren't used by default would
bloat it out a lot.  You could even argue for keeping *all* the
function descriptions in the separate file and limiting the table in
MANUAL.html to the function name and corresponding bindings.
  
>>> Local CGI
[...]
>>> of the script and display it. The bookmark registration and helper-app editor
>> 
>> I'm not sure what it means by "helper-app editor".
> 
> I'm not sure, too. But w3mhelp.cgi loads a file like
> /usr/share/w3m/w3mhelp-funcdesc.en.pl that contains the strings that
> appear as explanations.

Hmmm, there's a change here between the versions in Wheezy and Sid.
In the *older* MANUAL.html, the HTML source has links to
"file:///$LIB/w3mbookmark?mode=panel&bmark=~/.w3m/bookmark.html&url=MANUAL.html&title=w3m+manual"
and "file:///$LIB/w3mhelperpanel?mode=panel".  That second one must
mean /usr/lib/w3m/cgi-bin/w3mhelperpanel, which (judging from its
name) must be some sort of panel for setting up MIME-type
associations.  But in fact w3m refuses to follow either of those
links: it just says "Incomplete Request: (null)" for either of them.
Maybe that's why they were taken out in the latest version of
MANUAL.html.

I can see in w3m's main.c there's an ADD_BOOKMARK function which calls
adBmark() which calls W3MBOOKMARK_CMDNAME (which holds the location of
the w3mbookmark executable).  And I see similar routines to invoke the
options panel and so on.  But I don't see any way of getting to
w3mhelperpanel...

I'll change the manual to refer to the default directory browser
instead.
 
[...]
> This explanations on how to write cgi-scripts are quite
> superficial. But I do not know whether it is worth to improve the
> matter. Curious users will explore this field on their own.

With this many cobwebs they should probably be warned to watch out for
giant spiders.

------------------------------- suture -------------------------------

Looping back round to halfway through again:

> About the structure of MANUAL.html. You certainly noticed that the
> explanantions on the key bindings and respective functions are
> identical to those in source file scripts/w3mhelp-funcdesc.en.pl. And
> a look in file scripts/w3mhelp.cgi.in reveals that this file sorts the
> the way you do not feel comfortable with it in MANUAL.html. Therefore,
> consider revising these two files or, leaving the sorting unchanged,
> only scripts/w3mhelp-funcdesc.en.pl.

I'm considering it, but it won't happen yet.

>>>>> M                Browse current document using external browser (use 2M and 3M
>>>>>                  to invoke second and third browser)
> 
>>> I do not have the phantasy to imagine what is "2M" and "3M" Second
>>> and third browser do not appear as functions in Help They only
>>> appear as configuration variables extbrowser2 and extbrowser3.
>  
>> It works for me.  I've got extbrowser2 set to "x-www-browser %s" and
>> extbrowser3 set to "x-terminal-emulator -e w3m %s &"; as a result,
>> hitting "2 M" (okay, in my keybindings it's "2 TAB") gives me the
>> same page in my currently configured graphical browser.
> 
> You are right. The interpretation of "2M" was the problem. With a
> space between number and letter, I would have interpreted is as
> sequentially pressing "2" and "Shift-m". This proves the necessity of
> your remarks on the notation.

(Do you mean "simultaneously"?  Pressing 2 and then M "sequentially"
does work, at least when extbrowser2 is defined.)
  
>> Is this a vote for an addition to the notation key?
> 
> Yes it is.

Added.
 
>>>> This whole buffer-centric viewpoint seems pointless to me, but I'll
>>>> just complain about it here instead of trying to completely rewrite
>>>> the section.
>  
>> I'm finding that difficult, since the manual needs a whole new
>> parallel section for browser-tabs (C-t, C-q and so on), but once that
>> exists it becomes more obvious that a lot of the stuff in the "Buffer
>> operation" section doesn't really belong there...
> 
> Would 
> "Content Operations",               (A)
> "Buffer navigation" and             (B)
> "Tab navigation" be an option?      (C)

Oh, "navigation", I should be using that word a lot more, yes.  But
there's almost nothing left to go in "Buffer navigation".  Maybe merge
them back in with the new Tabs section?  Or maybe even pull in
RET=GOTO as well and call it an "inter-page navigation" section?

> B	Back to the previous buffer  B
> v	View HTML source             A
> s	Select buffer                B
> E	Edit buffer source           A
> C-l	Redraw screen                A
> R	Reload buffer                A
> S	Save buffer                  A
> ESC s	Save source                  A
> ESC e	Edit buffer image            A

We could also import F = "Toggle frames" to the A list, immediately
after v = "Toggle HTML rendering".
 
> tab functions from README.functions
> 
> NEW_TAB		Open new tab
> TAB_GOTO	Open URL on new tab
> TAB_GOTO_RELATIVE	Open relative URL on new tab
> TAB_LINK	Open current link on new tab
> NEXT_TAB	Move to next tab
> PREV_TAB	Move to previous tab
> TAB_LEFT	Move current tab left
> TAB_RIGHT	Move current tab right
> TAB_MENU	Popup tab selection menu
> TAB_MOUSE	Move to tab on mouse cursor (for mouse action)
> CLOSE_TAB	Close current tab
> CLOSE_TAB_MOUSE	Close tab on mouse cursor (for mouse action)

No point mentioning the ones that don't have bindings in
keymap.default.

>>>>> B                Back to the previous buffer
>>> 
>>> The command not only brings the next buffer below in the stack of
>>> buffers onto the w3m window, it also shuts the buffer that has been
>>> left. So it is the complete reversion of the GOTO command
>>>
>>> The explanation should be "Close current buffer and go down one position in the stack of buffers.
>> 
>> That's too long, though... could we get away with
>> 
>>     B                Back to the previous buffer, closing this one
> 
> That's fine. But I'm afraid that we need the expression "stack of
> buffers" sooner or later.

I do have the expression "buffer-stack menu".  Then again maybe it
might even be clearer just to start from FIFO stack terminology:

       B                Go back, <q>popping</q> the buffer stack
  
[...]
>> I've currently got it as 
>> 
>>     v               Toggle viewing as text or rendered HTML
> 
> perhaps:
> 
>   v    Toggle between HTML and rendered text

You mean "between (plain) text and rendered HTML"?  But I want to keep
the word "view" for mnemonic value.
  
[...]
>> I mean, imagine what people would think about it if Mozilla declared
>> they were switching [...]
> 
> Being updated to Iceweasel/Firefox 31 (with Debian 7.7) my first job
> with this "miscreant" (jbr) was, to discover and apply how the menu
> bar would be brought back to the top of window.

(A couple of months ago I had a lovely Iceweasel configuration where
all the controls I ever needed were on one menu bar, and the tabs bar
was where I wanted it, but now that setup's no longer supported.
Still, at least w3m's improving.)

------------------------------- suture -------------------------------

>> If you specify filenames/URLs on the command line, these documents
>> are displayed. 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.
> 
> s/If it doesn't find a document there either then (normally) w3m will terminate without displaying anything./
>   If it doesn't find a document there either then w3m will normally terminate.
> 
> as usage information is displayed normally in such a situation.

Oh yes!  I've had WWW_HOME set to http://$HOSTNAME since last century,
so I keep forgetting what it's like without it.

> 382,395c452,453
> < Line-edit mode
> < 
> < C-p            Fetch the previous string from the history list
> < C-n            Fetch the next string from the history list
> 
> C-p, UP            Fetch the previous string from the history list
> C-n, DOWN          Fetch the next string from the history list

Oh, they do work, don't they.  And BKSPC, LEFT, RIGHT do the same as
C-h, C-b, C-f; but DEL, HOME, and END won't work for C-d, C-a, and
C-e.

>> The bookmark registration system and helper-app
>> editor are realized as local CGI scripts. Local CGI scripts allow w3m to be
>> used as a general purpose form interface.
> 
> For example, the bookmark registration system and the help function
> are realized as local CGI scripts. Moreover, such scripts are a means
> to use w3m as a form interface to acquire all kinds of data.

Yes, I'll use most of that.
-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package
Title: w3m manual

w3m MANUAL

Akinori Ito
aito@fw.ipsj.or.jp

Index

Introduction

w3m is a pager/text-based WWW browser. You can browse local documents and/or documents on the WWW using a terminal emulator.

Options

Command line usage is 

    w3m [options] [file|URL]

If you specify filenames/URLs on the command line, these documents are displayed. 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.

Options include:

+number

Move to the specified line-number.

-t width

Specify tab width. Default is 8.

-r

When displaying text/plain documents, prohibit emphasis using backspace. If you don't specify this option, A^H_ is interpreted as an underlined A and A^HA as a bold A.

-l number

Specify the number of lines that should be cached while reading a text/plain document from standard input. Default is 10,000.

-O charset

Specify display/output charset.

-I charset

Specify document charset.

-T type

Specify document type. Without this option, document type is determined from the extension of a file. If the determination fails, the document is regarded as text/plain. For example:

Read HTML document from standard input and display it 

   cat example.html | w3m -T text/html

Display HTML source 

   w3m -T text/plain example.html
-m

Display document using Internet message mode. With this option, w3m determines document type from header information. This is useful when reading e-mail or Usenet news posts.

-v

Show w3m's startup page.

-B

Show w3m's bookmarks page.

-bookmark file

Specify a custom bookmarks file.

-M

Monochrome display mode.

-F

Automatically render HTML frames.

-s

Squeeze blank lines.

-X

Upon exit, do not reinitialize the terminal.

-W

Toggle wrapping mode in searches.

-o option=value

Specify option. The available option names and values are the same as in ~/.w3m/config.

-cookie

Process cookies.

-no-cookie

Don't process cookies.

-num

Show line-numbers.

-dump

Read document specified by URL and dump page rendered as text into standard output. An 80 column width is used unless set with the -cols option.

-cols width

Specify document width. Used with -dump option.

-ppc count

Specify the number of pixels per character (default 8.0). Larger values will make tables narrower.

-dump_source

Read document specified by URL and dump the source.

-dump_head

Read document specified by URL and dump headers.

-dump_both

Read document specified by URL and dump headers and the source.

-dump_extra

Read document specified by URL and dump extra informations, headers, and the source.

-post file

Use POST method with file content.

-header string

Insert string as a header.

-no-proxy

Don't use proxy server.

-no-graph

Use ASCII characters to draw frames rather than graphical ones.

-no-mouse

Deactivate mouse support.

-config file

Specify config file.

Document colors

Links and images are displayed as follows.

  Color mode Monochrome mode
links blue underline
inline images green reverse
form input red reverse

These colors can be customized using the option setting command o.

Key bindings

After invoking w3m, you can control it with keyboard commands.

Here's the original key-binding table. If you are using Lynx-like key bindings, see the Lynx-like key bindings. Throughout, the C- and M- notations indicate the modifiers control and meta (which can be replaced with alt or ESC); on the other hand 2 M simply means 2 followed by M.

In-page navigation

SPC, C-v, +, PGDN Forward page
b, M-v, -, PGUP Backward page
l, C-f, RIGHT Cursor right
h, C-b, LEFT Cursor left
j, C-n, DOWN Cursor down
k, C-p, UP Cursor up
J Scroll screen up one line
K Scroll screen down one line
^, C-a Go to the beginning of line
$, C-e Go to the end of line
w Go to next word
W Go to previous word
> Shift screen right
< Shift screen left
. Shift screen one column right
, Shift screen one column left
g, M-<, HOME Go to the first line
G, M->, END Go to the last line
M-g Go to specified line
Z Center on cursor column
z Center on cursor line
TAB Move to next hyperlink
C-u, M-TAB Move to previous hyperlink
[ Move to the first hyperlink
] Move to the last hyperlink

Hyperlink operation

C-j, C-m, RET Follow hyperlink
a, M-RET Save link to file
u Show link URL
i Show image URL
I View inline image
M-I Save inline image to file
: Mark URL-like strings as hyperlinks
M-: Mark Message-ID-like strings as links
c Show current URL
= Show information about current document
C-g Show current position in page
C-h Show browsing history
M Browse current document using external browser (prefix 2 or 3 to invoke alternate configured browsers, e.g. 3 M)
M-M Browse link using external browser (prefixed as above, e.g. 3 M-M)

Bookmark management

M-b Go to bookmarks page
M-a Bookmark current page

File/stream operation

U Open new URL
V Open new file
@ Execute shell command and view output
# Execute shell command and browse output

Content operations

v Toggle viewing as text or rendered HTML
F Toggle rendering HTML frames
C-l Redraw screen
R Reload
E Edit local source
M-e Edit rendered copy of page
M-s Save source
S Save rendered copy of page

Buffer/tab navigation

B Go back, popping the buffer stack
s Show buffer-stack menu
M-t Show tab menu
T Open current page as new tab
C-t Open link as new tab
} Switch to next tab
{ Switch to previous tab
C-q Close current tab

Search

/ Search forward
? Search backward
C-s Incremental search forward
C-r Incremental search backward
n Next match
N Previous match
C-w Toggle wrapping mode in searches

Mark management

C-SPC Set/unset mark
M-p Go to previous mark
M-n Go to next mark
" Mark all occurrences of a regular _expression_

Miscellany

! Execute shell command
M-c Invoke w3m function
H Show help panel
o Show options panel
C-k Show cookie jar
C-c Interrupt
C-z Suspend w3m
q Quit (with confirmation dialog)
Q Quit without confirmation

Two special operational modes exist which have built-in (not redefinable) keymappings:

Menu selection mode

k, C-p, UP Select previous item
j, C-n, DOWN Select next item
D Delete current item
SPC, RET Go to the selected item

Line-editing mode

C-f, RIGHT Move cursor forward
C-b, LEFT Move cursor backward
C-h, BKSPC Delete previous character
C-d Delete current character
C-k Kill everything after cursor
C-u Kill everything before cursor
C-a Move to the beginning of line
C-e Move to the end of line
C-p, UP Fetch the previous string from the history list
C-n, DOWN Fetch the next string from the history list
TAB, SPC Try to complete filename
RET Accept

Lynx-like key bindings

If w3m was compiled with Lynx-like key bindings, you can use the following key bindings.

In-page navigation

SPC, C-v, + Forward page
b, M-v, - Backward page
l Cursor right
h Cursor left
j Cursor down
k Cursor up
J Scroll screen up one line
K Scroll screen down one line
^ Go to the beginning of line
$ Go to the end of line
> Shift screen right
< Shift screen left
. Shift screen one column right
, Shift screen one column left
C-a, M-< Go to the first line
C-e, M-> Go to the last line
G Go to the specified line
w Go to next word
W Go to previous word
Z Center on cursor line
z Center on cursor column
TAB, C-n, DOWN Move to next hyperlink
M-TAB, C-p, C-u, UP Move to previous link
C-g Show current position in page
[ Move to the first hyperlink
] Move to the last hyperlink

Hyperlink operation

C-f, C-j, C-m, RET, RIGHT Follow hyperlink
d, M-RET Save link to file
u Show link URL
i Show image URL
I View inline image
M-I Save inline image to file
: Mark URL-like strings as hyperlinks
M-: Mark Message-ID-like strings as news anchors
c Show current URL
= Show information about current document
C-h Show browsing history
M Browse current document using external browser (prefix 2 or 3 to invoke alternate configured browsers, e.g. 3 M)
M-M Browse link using external browser (prefixed as above, e.g. 3 M-M)

Bookmark management

v, M-b Go to bookmarks page
a, M-a Bookmark current page

File/stream operation

g, U Open new URL
V Open new file
@ Execute shell command and view output
# Execute shell command and browse output

Content operations

\ Toggle viewing as text or rendered HTML
F Toggle rendering HTML frames
C-l, C-w Redraw screen
R, C-r Reload
E Edit local source
M-e Edit rendered copy of page
M-s Save source
S, p Save rendered copy of page

Buffer/tab navigation

B, C-b, LEFT Go back, popping the buffer stack
s, C-h Show buffer-stack menu
M-t Show tab menu
T Open current page as new tab
C-t Open link as new tab
} Switch to next tab
{ Switch to previous tab
C-q Close current tab

Search

/, C-s Search forward
n Next match
w Toggle wrapping mode in searches

Mark management

C-SPC Set/unset mark
P Go to previous mark
N Go to next mark
" Mark all occurrences of a regular _expression_

Miscellany

! Execute shell command
M-c Invoke w3m function
H, ? Show help panel
o Show options panel
C-k Show cookie jar
C-c Interrupt
C-z Suspend w3m
q Quit (with confirmation dialog)
Q Quit without confirmation

The Lynx-like configuration leaves keymappings unchanged in the menu-selection and line-editing modes.

Mouse operation

If w3m is compiled with mouse support and you are invoking w3m either from a console with GPM or from an X terminal emulator, you can use the mouse for navigation (in the case of rxvt, you need to set the TERM environment variable to xterm or kterm).

left click Move the cursor to the place indicated by the mouse cursor. If you click the cursor and it is on a hyperlink, follow the link.
middle click Back to the previous buffer.
right click Open pop-up menu. You can choose an item by clicking it.
left drag Scroll document. The default behavior is to grab the document and drag it. You can reverse the behavior (grab the window and drag it) with the option setting panel.

Key customization

You can customize the key bindings (except the line-editing keymap) in a ~/.w3m/keymap file. For example, 


   keymap C-o NEXT_PAGE

binds the NEXT_PAGE function (normally bound to SPC and C-v) to control-o. See README.func for a list of available functions. Original and Lynx-like keymap definitions are provided (keymap.default and keymap.lynx) as examples.

Local CGI

You can run CGI scripts using w3m, without any HTTP server. This means that w3m behaves like an HTTP server and runs the CGI script, then reads the output of the script and displays it. For example, the bookmark registration system and default directory browser are realized as local CGI scripts. Moreover, such scripts allow w3m to be used as a form interface to acquire all kinds of data.

For security reason, CGI scripts invoked by w3m must be in one of the following directories:

The CGI script can use the special header w3m-control: to control w3m. This field can take any function (see README.func), and the specified function is invoked after the document is displayed. For example, the CGI output 


Content-Type: text/plain
W3m-control: BACK

will display a blank page and delete that buffer immediately. This is useful when you don't want to display any page after the script is invoked. The next example 


Content-Type: text/plain
W3m-control: DELETE_PREVBUF

contents.....

will override the current buffer.

Each w3m-control: header can contain only one function, but you can include more than one w3m-control: line in the HTTP header. In addition, you can specify an argument to the GOTO function: 


Content-Type: text/plain
W3m-control: GOTO http://www.example.org/

This example works exactly the same way as the Location header: 


Content-Type: text/plain
Location: http://www.example.org/

Note that this header has no effect when the CGI script is invoked through an HTTP server.

Reply to: