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

[markus.hiereth@freenet.de]

Hello Justin,

Justin B Rye schrieb am  7. April 2016 um 20:18

> > I made preliminary translations of the manual pages and of FAQ.html,
> > MANUAL.html and README.func.
> >
> > In MANUAL.html, You remarked in a TODO-line that default- and
> > lynx-like keybinding and function description shall become one single
> > section.
 
> Ah, yes... after some digging I see my last MANUAL.html attached here
> "https://lists.debian.org/debian-l10n-english/2014/12/msg00030.html";;
> contained an invisible comment:
> <!--
>  TODO: reorganise this whole thing into one big table of
>     FUNCTIONNAME | description | default-binding | Lynxlike-binding
> !-->
> That still sounds like a good idea, but I can understand why it never
> got implemented.

I sent a link (the respective URL) to the maintainer Tatsuya and
meanwhile your revised versions are in the repository of w3m 0.5.3-27.

I do not know how much time You want to spend on MANUAL.html. For now,
I would suffice to decide, which of the descriptions of a function is
best. Or, in case all of them are bad, to suggest an alternative.

With my LibreOffice spreadsheet file, I am already prepared to do this
TODO:
<!--
 TODO: reorganise this whole thing into one big table of
    FUNCTIONNAME | description | default-binding | Lynxlike-binding
!-->



> > When preparing the translations (internationalisation) with the po4a
> > and translation-toolkit, I discovered differences in the descriptions
> > for one single function. To get consistent descriptions, I created a
> > spreadsheet file. Where we have a choice of descriptions, perpaps you
> > would like decide which description is the best. See attached csv-file
 
> I'm unlikely to get all the way through this before I run out of
> time today, but here's a start:
 
> > FUNCTION,FUNCTION,DESCRIPTION,DESCRIPTION,DESCRIPTION,DESCRIPTION,DESCRIPTION
> > ,from w3mfunc-desc,from README.func,from w3mfunc-desc,from help_1,from manual_defaultkeybinding,from manual_lynxkeybinding
> >
> > Example for reading the table
> >
> > ADD_BOOKMARK                   the function's name
> > Add current page to bookmarks  description in README.func
> > Add current page to bookmark   description in w3m's help panel
> > Bookmark current page          description in MANUAL.html, Section default keybindings
> > Bookmark current page          description in MANUAL.html, Section default keybindings
> 
> You mean
> 
>   ADD_BOOKMARK          the function's name as given in w3mfunc-desc

The capitalized strings are the names of functions as they appear in
the C-files and in Perl-Skripts (e.g. w3mhelp-funcdesc.en.pl.in and
w3mhelp-funcdesc.de.pl.in)

>   ???               no idea what this is about

Do not care for 0, ???, "", etc.  


>   Add current page to bookmarks description in README.func
>   ???               description in w3mfunc-desc

Yes, w3mhelp-funcdesc.en.pl.in matches perl-programmed functions with
English descriptions and w3mhelp-funcdesc.de.pl.in will do the same
for German descriptions.

>   Add current page to bookmark  description in w3m's help panel
>   Bookmark current page     description in MANUAL.html, section default keybindings
>   Bookmark current page     description in MANUAL.html, section Lynx-like keybindings
 

> In the attachment:
> 
> > FUNCTION,FUNCTION,DESCRIPTION,DESCRIPTION,DESCRIPTION,DESCRIPTION,DESCRIPTION
> > ,from w3mfunc-desc,from README.func,from w3mfunc-desc,from help_1,from manual_defaultkeybinding,from manual_lynxkeybinding
> > ,,,,,,
> > ABORT,,Quit w3m without confirmation,,0,0,0
> 
> (What's the difference between "" and "0"?)

There is no difference. I could not keep LibreOffice from inserting
zeros in fields that contain references to other cells within the file.


> The ABORT function is an alias for the EXIT function.

Yes.



> > ACCESSKEY,,Pop up accesskey menu,,0,0,0
 
> An undocumented feature that was obviously never used (given that
> nobody had spotted the bug) supporting a vaguely deprecated HTML
> attribute.  It's not mentioned in the keybindings sections because
> it doesn't have a keybinding.

Yes. Even the HELP panel ignores is. (No entry in the "from help_1"
column of the csv file.


> > ADD_BOOKMARK,,Add current page to bookmarks,,Add current page to bookmark,Bookmark current page,Bookmark current page
 
> "Add current page to bookmarks" is grammatical, "Add current page to
> bookmark" is ungrammatical, "Bookmark current page" is idiomatic.

Let's use "Add current page to bookmarks"


> > ALARM,,Set alarm,,Set alarm,0,0

> Did we ever find out what this is supposed to do or why it's useful?

No.

 
> > BACK,,Back to previous buffer,,Back to previous buffer,"Go back, `popping' the buffer stack","Go back, `popping' the buffer stack"
> 
> Keybindings version is clearer for people who don't happen to be
> running w3m under Emacs.

I would prefer something like
  "Close current and change to the buffer below"
  "Close current buffer and one step down in the buffer stack"
  "Close current buffer, enter the buffer below in stack"

> > BEGIN,,Go to the first line,,Go to the first line,Go to the first line,Go to the first line
> > BOOKMARK,,View bookmarks,,0,Go to the bookmarks page,Go to the bookmarks page
> 
> Alias for VIEW_BOOKMARK, which has a built-in grammar error.
> 
> Actually "View bookmarks" would work in the keybindings sections too.

Let's use "View bookmarks" throughout for BOOKMARK and VIEW_BOOKMARK.

 
> > CENTER_H,,Move to the center line,,Move to the center line,Center on cursor column,Center on cursor column
> > CENTER_V,,Move to the center column,,Move to the center column,Center on cursor line,Center on cursor line
> 
> The "move to" version is confusing, and doesn't seem to describe what
> happens (for a start, usually nothing detectably moves).

Yes. "Center on ..." is short and fits to this function which moves
the displayed area of a page.

or

"Center screen above and below cursor line"
"Center screen left and right of cursor column"

 
> > CHARSET,,Change the current document charset,,Change the current document charset,0,0

> No standard bindings, but okay.

I regret, but it just came to my mind that we should use throughout
the word "character encoding" where the old documentation speaks of
charsets! This setting does not affect the set of characters, but the
way binary information is decoded into characters and signs.

When revising manual page w3m (1), we shifted as well to "character
encoding"


 
> > CLOSE_TAB,,Close current tab,,Close current tab,Close current tab,Close current tab
> 
> Universal agreement!
> > CLOSE_TAB_MOUSE,,Close tab on mouse cursor (for mouse action),,0,0,0
> 
> Not very common.
> 
> > COMMAND,,Execute w3m command(s),,Execute w3m command(s),Invoke w3m function,Invoke w3m function
 
> Aha!  I hadn't realised it's possible to invoke more than one - they
> need to be separated by semicolons.  So maybe it should standardise on
> "Invoke w3m function(s)".

Again something new about our buddy w3m. OK. 

 
> > COOKIE,,View cookie list,,View cookie list,Show cookie jar,Show cookie jar
> 
> Keybindings version is idiomatic.

So I assume it is up to me which one to use.


> > DEFAULT_CHARSET,,Change the default document charset,,Change the default document charset,0,0
 
> Alias for CHARSET, or maybe it was vice-versa.  But why didn't I have
> it on my list of synonyms?

My interpretation of the following two lines of the source file main.c

  main.c:DEFUN(docCSet, CHARSET, "Change the current document charset")
  main.c:DEFUN(defCSet, DEFAULT_CHARSET, "Change the default document charset")

does not fit with an assumption the two are synonyms.


 
> > DEFINE_KEY,,Define a binding between a keystroke and a user command,,Define a binding between a key stroke and a user command,0,0
 
> What's a "user" command?  One that isn't in /sbin?  Surely the mapping
> is between a *set* of keystrokes (such as shift-1 or ctrl-a) and a w3m
> *function*, like the things you can define using "keymap" in your
> config-file?
> 
> If so then I would suggest calling this something simple like "Set key
> binding".

You are right. But a single binding is defined with it. This
definition won't be stored in the respective file ~/.w3m/keymap.

It seems that "keystroke" is preferred to "key stroke" for version 0.5.3-27.

What do you think of

  "Define a of keystroke command combination" 
  "Set up one keybinding"
  "Set up a keybinding"


> > DELETE_PREVBUF,,Delete previous buffer (mainly for local-CGI),,0,0,0
> 
> Not very common.

As already suggested in earlier communications: I would prefer regard
the stack as vertically ordered, thus talking about "up"/"down",
"above"/"below". What do you think of

  "Delete buffer below in stack"
and
  "Delete buffer below in stack. Mainly useful for local-CGI"


 
> > DICT_WORD,,Execute dictionary command (see README.dict),,Execute dictionary command (see README.dict),0,0
> > DICT_WORD_AT,,Execute dictionary command for word at cursor,,Execute dictionary command for word at cursor,0,0
> 
> As far as I can see these only work if you first set up some custom
> CGI thing that's not included in the Debian package.

Then we leave this description as it is.


> > DISPLAY_IMAGE,,Restart loading and drawing of images,,Restart loading and drawing of images,0,0
> 
> Very similar to RELOAD, but apparently not an alias for it.

DISPLAY_IMAGE seems to correspond STOP_IMAGE

DISPLAY_IMAGE is sometimes inherited when another buffer/page is opened.

It is not whether or in which way DISPLAY_IMAGE is revoked by STOP_IMAGE.

STOP_IMAGE does not terminate an instance of an image-viewer started with VIEW_IMAGE.

DISPLAY_IMAGE causes the page to be loaded with pictures.
When another terminal window get in the front and hides parts of w3m's window and gets again in the back, the loaded pictures have disappeared.
Upon movements of the cursor the pictures are displayed again.


What do you think of

DISPLAY_IMAGE
               "Reload with images included"
               "Load anew with images included"
versus

RELOAD
               "Reload"
               "Load anew"


> > DOWN,,Scroll down one line,,Scroll down one line,Scroll screen down one line,Scroll screen down one line
> 
> The keymap version makes it clearer that it "moves" the whole display,
> not the cursor position.


What do you think of inserting the defined article?

  "Scroll the screen down one line"

> > DOWNLOAD,,Save document (source) to file,,0,0,0
 
> Alias for SAVE.

Yes. See
main.c:DEFUN(svSrc, DOWNLOAD SAVE, "Save document (source) to file")



 
> > DOWNLOAD_LIST,,Display download list panel,,Display download list panel,0,0
> 
> Seems clear enough.
> 
> > EDIT,,Edit current document,,Edit current document,Edit local source,Edit local source
> 
> The keymap version makes it clear that even if you're looking at
> https://wiki.debian.org, this function will claim "Can't edit other
> than local file".

Yes.

 
> > EDIT_SCREEN,,Edit currently rendered document,,Edit currently rendered document,Edit rendered copy of page,Edit rendered copy of page
> 
> The keymap version is clearer... though I'm still a bit baffled by
> what it's useful for.
> 
> > END,,Go to the last line,,Go to the last line,Go to the last line,Go to the last line
> 
> Universal agreement!
> 
> > EXEC_SHELL,,Execute shell command,,Execute shell command,0,0
 
> Alias for SHELL.

Yes.

 
> > EXIT,,Quit w3m without confirmation,,Verlasse w3m ohne Rueckfrage,Quit without confirmation,Quit without confirmation
                                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Oops.

Oops. The German description came from my personal poison kitchen,
i.e. an edited file /usr/share/w3m/w3mhelp-funcdesc.en.pl


> > EXTERN,,Execute external browser,,Execute external browser,"Browse current document using external browser (prefix 2, 3,..., or 9 to invoke alternate configured browsers, e.g. 3 M)","Browse current document using external browser (prefix 2, 3,..., or 9 to invoke alternate configured browsers, e.g. 3 M)"
> 
> Keymap version incorporates longwinded example.

What do You think of

  "Pass current document to an alternative browser. Prefixes 2,
  3,... select one of up to 9 configured browsers."


> > EXTERN_LINK,,View current link using external browser,,View current link using external browser,"Browse link using external browser (prefixed as above, e.g. 3 M-M)","Browse link using external browser (prefixed as above, e.g. 3 M-M)"
> 
> Ditto.
 
> > FRAME,,Render frames,,Render frame,Toggle rendering HTML frames,Toggle rendering HTML frames
> 
> Another number error; and the keymap versions include the fact that it
> can also mean "stop rendering frames".

What is the result? "Render frames"! As you have at least two frames
when using this feature of HTML.

 
> > GOTO,,Go to URL,,Go to URL,Open new URL,Open new URL
 
> Keymap version makes it clearer that it doesn't mean "follow link".

OK.

As this underlines the difference to following; what do you think of

"Open some document within a new buffer"
"Open URL within a new buffer"


> > GOTO_LINE,,Go to specified line,,Go to specified line,Go to the specified line,Go to the specified line
> 
> Keymap version is just less abbreviated.

I would prefer having the defined article "the" here and in similar
descriptions.

 
> > GOTO_LINK,,Follow current link,,Go to current link,Follow hyperlink,Follow hyperlink
 
> "Follow" is better, but either of "current link/hyperlink" works.

OK. On the other hand, GOTO_LINK differs from GOTO only in the fact
that it does not expect an URL to go to as it takes the address within
the hyperlink. Therefore your criticism on "to follow" applies as well
here.

But what do you think of the word "anchor" that appears as well?
Replacing it all over? Use it once combined with "link", for historic
reasons as it still lives in the HTML element <a>? Or keeping it alive
by using it frequently because it helps to express the difference
between the HTML element and the file it points to? Maybe it helps as
well avoiding the ugly abbreviation URL.

For Germans, "hyperlink" sounds already a bit antique. We usually say
"der Link". But, from your hints on links / references in the
head-section of HTML documents, I imagine that "hyperlink" is still of
value.


> > GOTO_RELATIVE,,Go to relative URL,,Go to relative URL,0,0
 
> No standard bindings, but okay.


> > HELP,,View help,,View help,Show help panel,Show help panel
 
> Mentioning that it's a "panel" is useful.

OK


> > HISTORY,,View browser history,,View history of URL,Show browsing history,Show browsing history
> 
> That's odd; Google claims that "browser history" gets twice as many
> hits as "browsing history", but when I ask for the former the top hits
> it shows me are for the latter.

I think "browsing history" is more accurate as we do not deal with
history of the browser itself.

 
> > INFO,,View info of current document,,View info of current document,Show information about current document,Show information about current document
 
> Keybindings version is less abbreviated.
 
> > INTERRUPT,,Suspend w3m,,0,Interrupt,Interrupt
> 
> Alias for SUSPEND.

Yes it is. Therefore, I prefer just a single description for all of
them!



> > INIT_MAILCAP,,Reread mailcap (mainly for local-CGI),,0,0,0
> 
> Not very common.
> 
> > ISEARCH,,Incremental search forward,,Incremental search forward,Incremental search forward,0
> 
> Near-universal agreement.
> 
> > ISEARCH_BACK,,Incremental search backward,,Incremental search backward,Incremental search backward,0
 
> Near-universal agreement.
> 
> > LEFT,,Shift screen one column,,Shift screen one column,Shift screen one column left,Shift screen one column left
> 
> Keymap version includes an obvious detail.
> 
> > LINE_BEGIN,,Go to the beginning of line,,Go to the beginning of line,Go to the beginning of line,Go to the beginning of line
> > LINE_END,,Go to the end of line,,Go to the end of line,Go to the end of line,Go to the end of line
> 
> Universal agreement.

> > LINE_INFO,,Show current line number,,Show current line number,Show current position in page,Show current position in page
 
> Keymap version is more accurate: it shows the line number, the total
> number of lines, that position as a percentage, the column number,
> the total number of (occupied) columns, and charset information.

Yes, the MANUAL.html version is much more informative.


> > LINK_BEGIN,,Go to the first link,,Go to the first link,Move to the first hyperlink,Move to the first hyperlink
> > LINK_END,,Go to the last link,,Go to the last link,Move to the last hyperlink,Move to the last hyperlink
 
> With all this ambiguous use of "Go to", the keymap's version makes
> it clearer that it's just the cursor position that changes.

You're right.


> > LINK_MENU,,Pop up link element menu,,Popup link element menu,0,0
 
> Part of the point of my use of "hyperlink" elsewhere is that here,
> "link element" doesn't mean hyperlinks; it means source URLs for
> images/stylesheet and <link> elements, *not* hyperlinks.

Your point is important.

 
> > LIST,,Show all links and images,,Show all links and images,0,0
 
> In fact this generates a page listing three categories of things:
> "Links" (meaning <link>s and source URLs in the <head>), "Anchors"
> (by which it means not <a> elements but hyperlinks), and "Images"
> (meaning image source URLs).  Oddly, it leaves out script source
> URLs.

What do you think of
  "Show the document's references"

 
> > LIST_MENU,,Pop up link list menu and go to selected link,,Popup link list menu and go to selected link,0,0
 
> The noun is "(a) popup", but the verb is "(to) pop up".

> This generates a list of hyperlinks and follows the one you select.
> So it should say something more like:
>     Pop up hyperlink menu and follow selected link

OK. Then the description in README.func could to be used.
but
  "Pop up hyperlink selection menu" would be an alternative
  "Pop up anchor selection menu" would be better
  "List all anchors for selection within a menu"
And
  "Pop up anchor menu and pre-select the current one" would be good as long version for MANUAL.html


> > LOAD,,Load local file,,Load local file,Open new file,Open new file
> 
> Ideally this should include both points: that it loads a local file
> rather than a remote URL and that it opens it as a new file rather
> than inserting it into the current one.  Probably the best answer is
> Open local file

LOAD and GOTO seem to differ in these two aspects:

  LOAD is able to complete addresses in the local directory structure

  GOTO expects an URL that protocol  (http), path, place to go to (#place)

My suggestion
  "Open local file within a new buffer"


 
> > MAIN_MENU,,Pop up menu,,Popup menu,0,0
> 
> The verb is two words: "Pop up menu".

OK


> > MARK,,Set/unset mark,,Set/unset mark,Set/unset mark,Set/unset mark
> 
> Universal agreement.
 
> > MARK_MID,,Mark Message-ID-like strings as links,,Mark Message-ID-like strings as anchors,Mark Message-ID-like strings as links,Mark Message-ID-like strings as news anchors
> 
> Oops, one of them has still got the confusing reference to "news
> anchors" (which are a kind of celebrity, not a kind of link).

You're joking, but seriously: How to explain MARK_MID?

MARK, MARK_MID and MARK_URL do not only mark strings but provide them
with the function of an anchor. Perhaps something

  "Mark Message-ID-like strings and prepare to follow them"
  "Prepare Message-ID-like strings to be followed"
 
shall be used for this group of functions.

> > MARK_URL,,Mark URL-like strings as links,,Mark URL-like strings as anchors,Mark URL-like strings as hyperlinks,Mark URL-like strings as hyperlinks
 
> As hyperlinks, not links, and definitely not as anchors.

Why? What is the criterion to separate anchors and hyperlinks in files or pages?


  "Provide URL-like string with anchor function"
would be a scheme for describing this trio of function, i.e.
  "Provide URL-like string with anchor function"
  "Provide Message-ID-like string with anchor function"
  "Provide URL-like string with anchor function"

> > MARK_WORD,,Mark current word as link,,Mark current word as anchor,0,0

> This should be "Mark current word as hyperlink".  It works, I just
> can't remember why on earth you'd want it.

Perhaps MARK_WORD is used by scripts.

 
> > MENU,,Pop up menu,,0,0,0
> 
> Uh, is this an alias for MAIN_MENU?

Yes, it is:
  0.5.3-27/menu.c:DEFUN(mainMn, MAIN_MENU MENU, "Pop up menu")

 
> > MENU_MOUSE,,Pop up menu at mouse cursor (for mouse action),,0,0,0
> 
> Not very common.

I ask myself what kind of menu is meant. Certainly no important function.

 
> > MOUSE_TOGGLE,,Toggle mouse support,,Toggle activity of mouse,0,0
> 
> "Toggle mouse support".

OK. Though I hate the words "support" and the respective German
"Unterstützung" as they always appear in cases where authors want to
remain fuzzy.

 
> > MOVE_DOWN,,Move cursor down (a half screen scroll at the end of screen),,Move cursor down (a half screen scroll at the end of screen),Cursor down,Cursor down
> 
> Oh, the parenthesised bit is to clarify how the near-identical
> functions differ, I get it.  And since the other functions don't
> have keymappings the keymap version can afford to be concise.

> > MOVE_DOWN1,,Move cursor down (1 line scroll at the end of screen),,Move cursor down (1 line scroll at the end of screen),0,0
> (No default keymap)
> 

I think the description of the functions could be improved by avoiding
the parenthesis, because their content does not paraphrase the text
ahead. In fact, it deals with a second point, a shift of the sreen. As
two things happen, "and" is the appropriate conjungtion.

What do You think of

  MOVE_DOWN "Move the cursor down, and, at the end of screen, scroll a half screen up."

or

  MOVE_DOWN "Move the cursor down, and, having reached the screen's borders, scroll a half screen."


  MOVE_DOWN1 "Move the cursor down, and, at the end of screen, scroll the screen on line up."

or

  MOVE_DOWN1 "Move the cursor down, and, having reached the screen's borders, scroll one line"


> > MOVE_LEFT,,Move cursor left (a half screen shift at the left edge),,Move cursor left (a half screen shift at the left edge),Cursor left,Cursor left
> 
> As for _DOWN.
> 
> > MOVE_LEFT1,,Move cursor left (1 column shift at the left edge),,Move cursor left (1 columns shift at the left edge),0,0
> 
> Ditto, but with a bonus number-error.

Do you mean s/1 column/one column ? 


> > MOVE_LIST_MENU,,Pop up link list menu and move cursor to selected link,,Popup link list menu and move cursor to selected link,0,0
> 
> Twin to LIST_MENU, which followed the link;
>     Pop up hyperlink menu and move cursor to selected link
> 
> > MOVE_MOUSE,,Move cursor to mouse cursor (for mouse action),,0,0,0
> 
> This doesn't seem to work for me, but maybe it's just that
> "unclutter" has vanished my mouse cursor while I'm busy invoking the
> command.  Uncommon, anyway.

I do not see any effect of MOVE_MOUSE as well.


> > MOVE_RIGHT,,Move cursor right (a half screen shift at the right edge),,Move cursor right (a half screen shift at the right edge),Cursor right,Cursor right
> > MOVE_RIGHT1,,Move cursor right (1 column shift at the right edge),,Move cursor right (1 columns shift at the right edge),0,0
> 
> As for _LEFT.
> 
> > MOVE_UP,,Move cursor up (a half screen scroll at the top of screen),,Move cursor up (a half screen scroll at the top of screen),Cursor up,Cursor up
> > MOVE_UP1,,Move cursor up (1 line scroll at the top of screen),,Move cursor up (1 line scrol at the top of screen),0,0
> 
> As for _DOWN with a bonus typo.

in main.c s/scrol at the top/scroll at the top/

> > MSGS,,Display error messages,,Display error messages,0,0
> 
> Okay.
> 
> > NEW_TAB,,Open new tab,,Open new tab,Open current page as new tab,Open current page as new tab
> 
> Keymap version gives extra detail.


> > NEXT,,Move to next buffer,,Move to next buffer,0,0
> 
> "Move" seems wrong... perhaps it should be "switch", as with tabs.

I agree.

  "Switch to next buffer"
or
  "Move up one buffer in stack"
or
  "One position up in buffer stack"

> > NEXT_DOWN,,Move downward to next link,,Move to next downward link,0,0
> 
> It's not a downward link.
 
> > NEXT_LEFT,,Move left to next link,,Move to next left link,0,0
> > NEXT_LEFT_UP,,Move left (or upward) to next link,,Move to next left (or upward) link,0,0
 
> Likewise.
 
> > NEXT_LINK,,Move to next link,,Move to next link,Move to the next hyperlink,Move to the next hyperlink
 
> As usual the keymapping version makes it clearer.
 
> > NEXT_MARK,,Move to next word,,Move to next word,Go to the next mark,Go to the next mark
 
> This seems like a thinko in first two versions.

In main.c and README.func
s/Move to next word/Move to next mark

 
> > NEXT_PAGE,,Move to next page,,Move to next page,Forward page,Forward page
> 
> This is effectively the equivalent of a graphical web browser's
> "forward" button.

I' not content with "Forward page". I read that the verb "forward" is
used in the sense of forwarding something to another recipient.

What do you think of
  "Scroll one page downwards"
  "Scroll one page forward"
  "Scroll to the next page"
  "Move one page forward"
  "Move cursor and screen one page forward"


> > NEXT_RIGHT,,Move right to next link,,Move to next right link,0,0
> > NEXT_RIGHT_DOWN,,Move right (or downward) to next link,,Move to next right (or downward) link,0,0
 
> It's not a rightward or downward link.

I.e. the README.func versions are correct, the help_1 versions are wrong

 
> > NEXT_TAB,,Move to next tab,,Move to next tab,Switch to next tab,Switch to next tab

 
> Again saying "switch" instead of "move" when it doesn't move the
> cursor, scroll the displayed page, or anything like that.
> 

therefore in main.c/ README.func and help_1:
s/Move to next tab/Switch to next tab/ 


> > NEXT_UP,,Move upward to next link,,Move to next upward link,0,0
> 
> It's not an upward link.

Therefore version in help_1 needs do be replaced. But help_1 has been
produced locally by my w3m installation with version 0.5.3-19. It
seems the correction has been already done.


> > NEXT_VISITED,,Move to next visited link,,0,0,0
 
> A less common version of NEXT_LINK.

No. It makes the cursor jump to the next anchor with an already
visited addresse.

 
> > NEXT_WORD,,Move to next word,,Move to next word,Go to the next word,Go to the next word
> 
> This is the one NEXT_MARK was confused with.

In case "go to" and "move to" are almost synonyms, we could use "to
move" for all commands that move the cursor visible and in a simple
way (one word, one line, one column)

"go to" and "jump" were alternatives, especially for movements with a
defined destination, without regard of how near or far it is.


 
> > NOTHING,,Do nothing,,0,0,0
> 
> An alias for NULL.
> 
> > NULL,,Do nothing,,0,0,0
 
> This is in fact the function-name I use most often in my own config,
> just because I start by overriding most of the existing keymappings.

If you think of it as important, this hint is to be introduced in
section "Key costumization" of MANUAL.html

> > OPTIONS,,Display option setting panel,,Option setting panel,Show options panel,Show options panel
> 
> Keymappings version is just more concise.
> 
> > PEEK,,Peek at current URL,,Peek current URL,Show current URL,Show current URL
> 
> "Peek" implies that it's only barely visible (or that it's doing
> some sort of Sinclair-BASIC memory hack).  Since the URL is just
> displayed in the status line, say "Show".

Alright. (Though the URL is only shown for some time?) 

> > PEEK_IMG,,Peek at image URL,,Peek image URL,Show image URL,Show image URL
> > PEEK_LINK,,Peek at link URL,,Peek link URL,Show link URL,Show link URL
> 
> Likewise.
 
> > PIPE_BUF,,Send rendered document to pipe,,Send rendered document to pipe,0,0
> > PIPE_SHELL,,Execute shell command and browse,,Execute shell command and browse,Execute shell command and browse output,Execute shell command and browse output
 
> We never did work out what these were all about.

I just tried out the two again and found out something:

PIPE_BUF sends the content of a buffer to a linux command that works
like a filter (e.g. sed s/a/A/g) and accepts the output in new buffer.

A possible description would be
  "Apply a shell command on current buffer and display the output"

PIPE_SHELL expects a linux command and accepts its output in a new buffer.

A possible description would be
  "Execute shell command and display the output"

> > PREV,,Move to previous buffer,,Move to previous buffer,0,0
> 
> Compare NEXT.
 
> > PREV_LINK,,Move to previous link,,Move to previous link,Move to the previous hyperlink,Move to the previous link
> > PREV_MARK,,Move to previous mark,,Move to previous mark,Go to the previous mark,Go to the previous mark
> > PREV_PAGE,,Move to previous page,,Move to previous page,Backward page,Backward page
> > PREV_TAB,,Move to previous tab,,Move to previous tab,Switch to previous tab,Switch to previous tab
> > PREV_VISITED,,Move to previous visited link,,0,0,0
> > PREV_WORD,,Move to previous word,,Move to previous word,Go to the previous word,Go to the previous word
> 
> Likewise.
 
> > PRINT,,Save buffer to file,,0,0,0
> 
> An oddly named alias for SAVE_SCREEN.

Yes. Really worth to remain hidden within the c files.


> > QUIT,,Quit w3m,,Quit w3m,Quit (with confirmation dialog),Quit (with confirmation dialog)
> 
> Compare ABORT/EXIT.

Short and precise descriptions were "Quit w3m at once" versus "Quit w3m w3m after confirmation" 

 
> > READ_SHELL,,Execute shell command and load,,Execute shell command and load,Execute shell command and view output,Execute shell command and view output
> 
> "Load" is unclear.

I would prefer "Execute shell command and display output"

I do not find differences worth being regarded between
PIPE_SHELL and READ_SHELL. The output of both appears in a new buffer. In the buffer stack, one is titled <"stream" command> the other <"Shellout" command>.



> > REDO,,Cancel the last undo,,Cancel the last undo,0,0 Intelligible
> enough, but since UNDO itself has no default mapping it's rather
> uncommon.

The reference to README.func that represents a the complete list of
functions should appear really prominent in section 'Key
Customization' of MANUAL.html

> > REDRAW,,Redraw screen,,Redraw screen,Redraw screen,Redraw screen

> Universal agreement.

I ask myself about the differences to RELOAD. For a test, I changed the content of a local file. This leads to the conclusion that

  REDRAW renders the document as it has been loaded and
  RELOAD loads the document anew and then renders it 

 
> > REG_MARK,,Set mark using regexp,,Set mark using regexp,Mark all occurrences of a regular expression,Mark all occurrences of a regular expression


> Keymap version is longer but clearer.
 

What do you think of 
  "Mark matches to regexp"
as short description for README.func and help page?

> > REINIT,,Reload configuration files,,Reload configuration files,0,0
> 
> That's clear enough.

> > RELOAD,,Reload buffer,,Reload buffer,Reload,Reload
> 
> Mentioning buffers seems pointless.

I agree.

> > RESHAPE ,,Re-render buffer,,Re-render buffer,0,0
> 
> This sounds as if it's meant as a special RELOAD/REDRAW for when
> you've maximised the window, except that as far as I can see that's
> completely unnecessary.  No idea.

Me too.


> > RIGHT,,Shift screen one column right,,Shift screen one column right,Shift screen one column right,Shift screen one column right
 
> Unlike the LEFT version this one already consistently mentions the
> direction.

I would prefer LEFT would do this too.

> > SAVE,,Save document (source) to file,,Save document source to file,Save source,Save source
 
> The keymapping version may be designed to be clear when listed
> alongside SAVE_SCREEN...

What do you think of

  SAVE         "Save source code to file"
  versus
  SAVE_SCREEN  "Save rendered code to file"?

or

  SAVE        "Save document / source code to file"
  versus
  SAVE_SCREEN "Save rendered document / page to file"


 
> > SAVE_IMAGE,,Save image to file,,Save image to file,Save inline image to file,Save inline image to file
> 
> The keymapping version adds a detail (not that modern web users
> expect to have to click to a separate URL to view an image!)

I really asked myself why the authors of w3m's documentation used
"inline images" instead of "images". I' inclined to the short
expression.

>
> > SAVE_LINK,,Save link to file,,Save link to file,Save link to file,Save link to file

> I suppose for consistency this could be "hyperlink"...

For me, it is the target of link/hyperlink/anchor which is saved to a file.

Therefore

 "Save target to file"
or
 "Save target of anchor to file"
or
 "Save the anchor's target to file"
or
 "Save the hyperlink's target to file"


> > SAVE_SCREEN,,Save buffer to file,,Save rendered document to file,Save rendered copy of page,Save rendered copy of page
> 
> "Save buffer" is a thoroughly unclear way to put it.
> 
> > SEARCH,,Search forward,,0,Search forward,Search forward
 
> Why is that middle version missing?

w3m's help panel does not mention neither this command nor WHEREIS, it
only mentions the alias SEARCH_FORE

> > SEARCH_BACK,,Search backward,,Search backward,Search backward,0
> 
> Reverse of SEARCH.
> 
> > SEARCH_FORE,,Search forward,,Search forward,0,0
> 
> Alias for SEARCH.

By the way: I found that

  SEARCH with regular expression [aeiu][aeiu] finds double vowels. 

  ISEARCH with strings l{2} or l\{2\}, which is a regular expression too, does not find double ll.

In consquence, searches for regular expressions in w3m are limited. We
should use the word "regular expression" with care, make it rare as
expections would not be met.


> > SEARCH_NEXT,,Search next regexp,,Search next regexp,Next match,Next match
> > SEARCH_PREV,,Search previous regexp,,Search previous regexp,Previous match,0
> 
> "Next/previous regexp" makes it sound as if it's looking for strings
> like "_[a-z]{3}_" instead of things that match them.

What do you think of

  "Continue search forward"
  and
  "Continue search backward"

 
> > SELECT,,Go to buffer selection panel,,Go to buffer selection panel,0,0
> 
> For consistency with the following it might be better to say
> something like "Go to buffer-stack panel"

I agree.


> > SELECT_MENU,,Pop up buffer selection menu,,Popup buffer selection menu,Show buffer-stack menu,Show buffer-stack menu
> 
> The keymapping version is again intended to be clearer for people
> who don't happen to be running w3m under Emacs.

OK.

Alternative:
 "Pop up  menu for buffer selection"



> > SETENV,,Set environment variable,,Set environment variable,0,0
> > SET_OPTION,,Set option,,Set option,0,0
> > SHELL,,Execute shell command,,0,Execute shell command,Execute shell command
> 
> Clear enough.
> 
> > SHIFT_LEFT,,Shift screen left,,Shift screen left,Shift screen left,Shift screen left
> > SHIFT_RIGHT,,Shift screen right,,Shift screen right,Shift screen right,Shift screen right
> 
> Universal agreement.
> 
> > SOURCE,,View HTML source,,0,0,0
> 
> An alias for VIEW.
 
> > STOP_IMAGE,,Stop loading and drawing of images,,Stop loading and drawing of images,0,0

I wonder about the relation between STOP_IMAGE and DISPLAY_IMAGE. When
browsing, DISPLAY_IMAGE reloads a current document with images and
shows following documents with images from the beginning on. But it
seems that STOP_IMAGES does not revoke this behavior.


> > SUBMIT,,Submit form,,Submit form,0,0
> 
> Clear enough.
> 
> > SUSPEND ,,Suspend w3m,,Stop loading document,Suspend w3m,Suspend w3m
 
> The middle one there is just wrong.

Yes.

I would prefer "Suspend w3m" or, even better, something like "Make w3m
a background process" as it relates the w3m command with the linux
commands bg and fg. fg is necessary to get w3m afterwards work again.


> > TAB_GOTO,,Open URL on new tab,,Open URL on new tab,0,0
> > TAB_GOTO_RELATIVE,,Open relative URL on new tab,,Open relative URL on new tab,0,0
> 
> TAB_FOO versions of the plain FOO functions.

I tend to prefer "Open something on _a_ new tab"


> > TAB_LEFT,,Move current tab left,,Move current tab left,0,0
> 
> This actually moves the tab along the tab bar, which is one of the
> reasons for avoiding the word "move" for other meanings.

What do you think of

TAB_LEFT
  "Go to next tab"
  "Shift to next tab"
TAB_RIGHT
  "Go to previous tab"
  "Shift previous tab"


> > TAB_LINK,,Open current link on new tab,,Open current link on new tab,Open link as new tab,Open link as new tab
> 
> Oh, there isn't a plain LINK function; it's like GOTO_LINK.

What do you think of

  "Open target within a new tab"
  "Open current target on a new tab"
  "Open target of current hyperlink on a new tab"


> > TAB_MENU,,Pop up tab selection menu,,Popup tab selection menu,Show tab menu,Show tab menu
> 
> "Pop up" works as well as "Show"; just don't make it "popup".

What do you think of
 "Pop up  menu for tab selection"


> > TAB_MOUSE,,Move to tab on mouse cursor (for mouse action),,0,0,0
 
> A rare one.

I do not know how this function is meant to work. But maybe it is not
worth being investigated.

 
> > TAB_RIGHT,,Move current tab right,,Move current tab right,0,0
> 
> Like _LEFT.
 
> > UNDO,,Cancel the last cursor movement,,Cancel the last cursor movement,0,0
> 
> Clear enough.
 
> > UP,,Scroll up one line,,Scroll up one line,Scroll screen up one line,Scroll screen up one line
> 
> Compare DOWN.
 
> > VERSION,,Display version of w3m,,Display version of w3m,0,0
> 
> Clear enough.
 
> > VIEW,,View HTML source,,View HTML source,Toggle viewing as text or rendered HTML,Toggle viewing as text or rendered HTML
> 
> You can use this while you're looking at some sort of obscure XML to
> get it turned into a quasi-HTML page, so the "toggle" version is
> more accurate.

OK. 

> > VIEW_BOOKMARK,,View bookmarks,,0,0,0
> 
> Built-in number agreement error.

Therefore, keep this alias of BOOKMARK hidden within the C sources.

 
> > VIEW_IMAGE,,View image,,View image,View inline image,View inline image
 
> The keymapping version makes it clear that it doesn't mean "spawn an
> image-viewer".

But this is what happens. With the curser above an image, the function
starts xv to display the image.

 
> > WHEREIS,,Search forward,,0,0,0
> 
> A third alias for SEARCH.
> 
> > WRAP_TOGGLE,,Toggle search wrap mode,,Toggle wrap search mode,Toggle wrapping mode in searches,Toggle wrapping mode in searches
> 
> "Search wrap mode" is hard to follow.

I agree. There is no short description.


> Sorry, out of time!

I hope You find the time to go through the questions and suggestions above.

Best regards
Markus