Re: FAQ.html and MANUAL.html, was Re: fwd: Re: Re: Please review changed man-file of w3m
markus.hiereth@freenet.de wrote:
> I do not know how much time You want to spend on MANUAL.html.
I should have plenty of time this week.
> 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
> !-->
I notice in the old d-l-e thread that I also raised the possibility
that MANUAL.html should only give function names and leave it to the
README.func file to describe them, reducing the number of separate
versions that need to be kept in sync, but that seems unfriendly.
[...]
>
>>> 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
(What I was doing here was trying to work out how this table
corresponded to the "FUNCTION,FUNCTION,DESCRIPTION,DESCRIPTION"
(etc.) fields. I should probably have taken more time over
explaining myself, even if it did mean I had to leave more entries
for later.)
>>
>> 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)
And apparently there's nothing to stop all these different versions
drifting out of sync.
>> ??? no idea what this is about
>
> Do not care for 0, ???, "", etc.
(I meant that I had no idea what the second field in the CSV file was
for.)
>> 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.
This seems... awkward to maintain.
[...]
>>> ALARM,,Set alarm,,Set alarm,0,0
>> Did we ever find out what this is supposed to do or why it's useful?
> No.
(And looking at the source leaves me none the wiser.)
>>> 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"
That would have to be something more like
"Close current buffer and change to the one below [in the stack]"
Do we know that it does "close" the buffer, as a separate action from
switching away from displaying it? It stays on the buffer list,
doesn't it?
When I say that the keybindings version is clearer, I'm really only
saying that it's more obvious what kind of jargon it's using, and
that taking the term "buffer" for granted might lead to confusion -
"buffer" can mean just "tempfile" or even "protective cushion".
One fix might be to put an explanation in the keymappings table,
saying something like "w3m handles pages as a stack of buffers in
memory, and the following functions allow the user to operate upon
these buffers." Something like that would make a description like
"Back to previous buffer" much less inscrutable to non-Emacs-users.
[...]
>>> 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"
These are plausible as slightly longer phrasings of the same thing; we
might use that longer form for the keymappings table.
>>> 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"
Oh, yes. The HTML standard has usages like <meta charset="UTF-8">,
but we should decode that into the non-confusing terminology; maybe:
"Change the character encoding for the current document"
[...]
>>> 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.
Yes; "Show cookie jar" is what feels to me like the most natural way
to say it in English, but on the other hand it might also make life
slightly harder for non-native-speakers.
>>> 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.
Ah, of course. Could we make this one just:
"Change the default character encoding"
(Mentioning documents seems redundant.)
>>> 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"
Missing word? And do you mean "keystroke combination command"?
> "Set up one keybinding"
> "Set up a keybinding"
That last one, or indeed "Define 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"
I think even if there was an explanation nearby of what it meant by a
buffer, I'd still have to spend some extra mental energy decoding
this. That might be because it's so hard to imagine why you'd want
to do this.
[...]
>>> 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.
In fact I was thinking of REDRAW.
>
> 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.
Do you mean "it is not ^clear"?
> 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"
It doesn't reload the rest of the page - only the images. And come to
think of it... [checks] no, apparently *neither* DISPLAY_IMAGE *nor*
RELOAD re-fetches the images. Even after I've done a VIEW_IMAGE that
shows something completely different, DISPLAY_IMAGE shows the image
I've deleted. So maybe it should be:
"Redraw images"
> versus
>
> RELOAD
> "Reload"
> "Load anew"
Neither of these contain any information that isn't in the function
name. I'll wait until we get to the functions beginning with R.
>>> 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"
Yes, that's okay. Some of these may be getting inconsistent levels of
abbreviated English.
>>> 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")
I think grepping for things like this was how I originally compiled my
aliases list, but I'd deleted my copies of the source since then.
[...]
>>> 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
You were probably confused by the extension claiming that it's in
Polish.
>>> 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."
Nitpick: that construction "FOO, BAR, ..." (with an ellipsis
effectively meaning "or whatever") is one I've never seen used in
non-developerese English prose, and I've never been sure whether
people get it from the C syntax or from foreign languages or whether
it's just an Americanism I hadn't noticed elsewhere. At any rate,
people seem to find it easy enough to understand.
Another nitpick: styleguides would tell you to write out the "nine",
though obviously that doesn't apply if we really mean the <9> key.
Looking for a concise way of saying it:
Pass current document to an alternative browser. Numeric prefixes
select one of up to nine configured browsers - e.g.: 9 M
Pass document to configured alternative browser - one of up to
nine, selectable via numeric prefixes, e.g.: 9 M
Pass document to configured alternative browser, selectable via
prefixes 2-9, e.g.: 9 M
(No, I think this is losing intelligibility)
>>> 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.
When I say "number error" I mean that the one that says "Render frame"
is a grammatical error and should be plural.
>>> 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"
Well, that makes it sound as if it means "come up with some random
text or other and open that". But it is true that the URL doesn't
need to be "new" - it can even be
http://info.cern.ch/hypertext/WWW/TheProject.html
> "Open URL within a new buffer"
Better. Perhaps "Open URL *as* 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.
No problem.
>>> 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.
The trouble with using "anchor" to mean "link" is that <a> tags don't
necessarily contain a link. In the old days, page-internal links used
anchors like <a name="foo"> (which you'd link *to* with an anchor like
<a href="#foo">); these days, those are deprecated but the specs
explicitly allow for an <a> element to be an empty placeholder.
> 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.
Referring to these things as "links" is perfectly normal, but then
again there's also an element <link> that can occur in HTML, which
*doesn't* create the kind of clickable element that a user would
recognise as a link. Some of w3m's functions list links in this sense
rather than the clickable kind (oh, yes, I pointed this out for
LINK_MENU and LIST), so "hyperlink" is a bit pedantic but may
sometimes be justifiable.
[...]
>>> 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.
I was thinking of it as parallel to "commandline history", but fair
enough, that's another good argument for "browsing history".
>>> 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!
Agreed.
[...]
>>> 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"
No, "references" doesn't quite work. Maybe
Show all URLs referenced by this document
Show all referenced URLs
(Except of course that it oddly fails to show script URLs.)
>>> 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
It's redundant to specify that a menu is a "selection menu".
> "Pop up anchor selection menu" would be better
LIST_MENU ignores <a name="x"> anchors (and <a class="placeholder">
anchors); it only shows the ones that are links.
> "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
Oh, so it does. But in fact it's more complicated; it's really
Pop up a link menu with the link that the cursor is currently at
pre-selected (or the first link if the cursor isn't at one), then
follow the selected link.
and that's far too much to bother explaining. I'd be inclined to
stick with
Pop up link menu and follow selected link
and take the "with friendly behavioural defaults" part for granted.
>>> 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
And I learn yet another new thing about w3m.
> GOTO expects an URL that protocol (http), path, place to go to (#place)
Well, that's the difference between local files and URLs. Though if I can
LOAD foo.txt, can I also GOTO file:/home/jbr/foo.txt? [checks] Yes, and
it even tab-completes!
> My suggestion
> "Open local file within a new buffer"
Make it "as a new buffer". (I don't mind talking about buffers when
in effect it's *defining* a buffer in passing.)
[...]
>>> 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.
I'd prefer something like
Treat Message-ID-like strings as links
Turn Message-ID-like strings into links
Presumably they're <a href="news:deadbeef@example.org";> URLs, so if
you wanted to make a joke you might call them "news: anchors", but
unless you're aiming for humour it's a bad idea to say anything like
that.
>>> 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?
Actually on second thoughts the pedantic hyperlink/link distinction
isn't important matter here, but "anchor" is never the right word.
> "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"
The commonest function of an anchor is to stop things going anywhere.
>>> 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.
I was hoping that you might be able to take a plain text list of URLs,
invoke MARK_URL, and then SAVE that version, but apparently marking
things as URLs doesn't involve marking them *up* as URLs - another
reason for not calling them anchors!
[...]
>>> 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.
Well, here it means the difference between paying no attention to the
mouse at all and letting a mouseclick doing the most obvious minor
thing a mouseclick might do, so it seems fair enough.
>>> 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.
I don't understand this reasoning...
> 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."
I'd suggest
"Move the cursor down (with a half-screen scroll at the screen edge)"
The scrolling part is parenthetical because it may or may not happen;
you definitely get a cursor movement, but the scrolling is
conditional.
> 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 the cursor down (with a one-line scroll at the screen edge)"
>>> 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 ?
I meant s/1 columns/1 column/, though where there's room I would also
prefer to expand s/1/one/ for things like this.
[...]
>>> 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"
I'm really not keen on the whole idea of thinking in terms of
clambering up and down the stack of virtual buffers in the program's
memory when all you need to say is "►"!
[...]
>>> 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.
When it's a verb, it can mean that. It can also be an adjective
meaning "brash". And "page" can mean "a message sent to a pager" or
"an apprentice squire to a knight". But these ambiguities wouldn't be
a problem (the adverbial interpretation of "forward" here is
encouraged by all the similar adverbs it's surrounded by -
"downward", "left", and so on). The thing that *is* a problem is that
I was thinking of entirely the wrong button - this isn't "→", it's
"PageDown"!
> 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"
In effect it "switches" to the next complete pageful of content, but I
suppose it's best to represent it as a scrolling action. I like your
first one best.
>>> 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
Yes.
>>> 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/
Yes. This one's worth fixing because it's easy to confuse it with the
one that really does move the tab on the tab bar.
>>> 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.
Oh, okay.
>>> 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.
Sorry, I should have said "a less common variant of NEXT_LINK".
>>> 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.
That sounds reasonable.
>>> 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
Well, it also happens to have a name that's self-explanatory.
>>> 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?)
I've got "display current line number" switched on (I don't remember
if that's the default), so the status bar gets overwritten as soon as
I do anything, but not until then.
>>> 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.
Ah, that's it!
> A possible description would be
> "Apply a shell command on current buffer and display the output"
Or "Pipe current buffer through shell command" might be enough.
> 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"
Yes, that's good.
[...]
>>> 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"
Yes, I like "at once". I wouldn't say "after", though.
>>> 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"
Yes.
> 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>.
Hmmm. Well, at least PIPE_BUF is clear.
>>> 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
Yes, REDRAW is just a "^L".
>>> 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?
Somehow awkward. "Mark regexp matches" might work, though. Oh, and
if we're not sure about the word "regexp", "Mark pattern-matches"
works too.
>>> 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.
Yes. (Sometimes I find myself thinking "but that's obvious from the
function name", but I'm trying to ignore that factor to avoid making
things harder for translators.)
>>> 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"
It's not exactly source *code*; the conventional label in browsers is
"view source" or "view document source". So I'd suggest
SAVE "Save document source"
SAVE_SCREEN "Save rendered document"
("To file" adds nothing much, apart from making the description
artificially longer than the function name it explains.)
>>> 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.
Yes, okay. Again "Save image" (which just restates the function name)
might be enough on its own.
>>> 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"
Or just stack the nouns "link target" with no possessive.
Fetch link target and save to file
Save the link target to file
Save link target
>>> 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.
I hadn't noticed that this is claiming to be a screensaver.
>>> 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
Odd.
>>> 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.
ISEARCH is incremental literal string-matching.
> 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.
And it's also jargon, though the kind of jargon that GNU/Linux users
tend to be expected to understand. We might just say "pattern".
>>> 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"
Makes sense. They do after all require a previously defined search.
>>> 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.
Or I suppose "Switch to", but for panels it should be obvious.
>>> 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"
It works, but all menus are for selection; we can leave that word out
and make it parallel to SELECT.
SELECT Go to buffer-stack panel
SELECT_MENU Pop up buffer-stack menu
[...]
>>> 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.
I was thinking this might be because I've got "display inline images"
set to YES in my config, but turning it off doesn't seem to make
STOP_IMAGE any more useful.
>>> 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.
So maybe "Suspend w3m to background"?
>>> 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"
I don't think we're being consistent, but go ahead.
>>> 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"
No, I mean this is a case where we *should* say "Move", since it moves
something. It shuffles tabs *without* the cursor position or current
URL changing:
TAB_LEFT Move current tab left (on tab bar)
TAB_RIGHT Move current tab right (on tab bar)
>>> 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"
You've got a point there.
Open link target as new tab
Open the target of the current link as a new tab
But as an alternative solution:
Follow current link in 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"
Another menu that's for selecting things, unlike the usual sort where
you're compelled to take the sole available meal of the day... but
this time maybe it *is* useful to say
Pop up tab selection menu
instead of
Pop up tab menu
if a "tab menu" might be one that's implemented in some sort of tabby
way. I don't know, though, I think I'd stick with "tab menu".
[...]
>>> 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.
Oh, so it does. I was just about to say "this is nearly the end, so I
expect I've made some rushed mistakes here".
So maybe it should say
Display image in viewer
Send image to viewer
>>> 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.
It took longer than I expected, but never mind.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: