Re: FAQ.html and MANUAL.html, was Re: fwd: Re: Re: Please review changed man-file of w3m
Hello Justin,
Justin B Rye schrieb am 15. Dec 2014 um 18:32
> > The explanation on new manpage provides more information
> For my work-in-progress version of MANUAL.html (attached) I still
> haven't got round to the stage of importing improvements from the
> manpage; I've got bogged down in the sheer quantity of content that
> needs reworking.
your lines give reason to limit myself. At least I'm going to try.
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.
The advantage would be more consistency more efficiency for our work
on w3m's documentation. In case this leads to an inacceptable amount
of work, forget this suggestion. And, I have to concede that I do not
know the extent or the depth revision that Tatsuya as package
maintainer will appreciate or welcome.
Best regards
Markus
-----------------------------------------------------------------------
> [...]
> >>> g,M-< Go to the first line
> >>> G,M-> Go to the last line
> >>
> >> Why does this represent "meta-foo" as "M-foo" instead of "ESC foo"
> >> like everywhere else?
> >
> > In a comment section on top of the keymap.default file, Meta-key and
> > Escape-key are declared to be equivalent. Even a third key combination
> > "^[" appears
> Yes, control-openbracket; I've needed to use that when I was stuck
> with a keyboard that had no alt or escape keys. Not much fun.
Even less fun on a German keyboard layout, where [ and ] themselves
are tasks for two fingers.
> I've inserted an explanation of the notation at the top.
>
> [...]
> >>> RET Follow hyperlink
> >>> a, ESC RET Save link to file
> >>> u Peek link URL
> >>> i Peek image URL
> >>
> >> How is "Peek" different from "Show"?
> >
> > Probably peek is used to indicate that the target addresse is
> > presented, not used as this reaction is described as "follow
> > hyperlink" or in "View inline image"
>
> I understand what it does, but I don't think there's any need to use
> the more obscure word when it could just say "show". ("View" would
> imply launching a viewer, in this case presumably meaning a
> browser.)
"to peek" was not familiar to me, but acceptable for this special
service of w3m.
> >>> 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.
> Is this a vote for an addition to the notation key?
Yes it is.
> >> 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)
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
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)
> >>> 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'm still a bit baffled by why it lets you backstep through
> page-internal movements, though. Does w3m really switch to a whole
> new buffer with identical contents when you navigate from
> "http://example.org/faq.html#q1"; to "http://example.org/faq.html#q2";?
Yes it does. I tried it with the internal links on top of our
document MANUAL.html
> >>> v View HTML source
> >>
> >> Actually this toggles HTML rendering on and off; you can even use it
> >> to turn *on* the interpret-as-text/html mode for a plain text file.
> >
> > This VIEW command opens an additional buffer that contains code when
> > VIEW was applied to a rendered file and vice versa rendered content
> > when VIEW was applied to source code. In this respect, it is
> > toggling. But more fundamentally, it is creating another buffer and
> > then toggling between the two.
>
> The fact that (like everything else) it's implemented in terms of a
> LIFO stack doesn't make it sensible to expect users to understand it
> that way. Users should be introduced to it in terms of its useful
> effects: it toggles in and out of HTML-rendering mode.
>
> I've currently got it as
>
> v Toggle viewing as text or rendered HTML
perhaps:
v Toggle between HTML and rendered text
> and I've moved it to "Miscellany" for now.
>
> >>> s Select buffer
> >>
> >> This doesn't select a buffer, it offers a menu for you to select from.
> >
> > s "Open the select buffer menu"
> > or
> > s "Show the stack of buffers"
>
> I've got it as
>
> s, C-h Show buffer-stack menu
That's fine
> >>> E Edit buffer source
> >>
> >> You don't edit the *buffer*, you edit the *original file*.
> >
> > E Edit the currently shown, local file
> >
> > Besides the EDIT command, there is as well an EDIT_SCREEN command. It
> > opens rendered content in the editor. But, when closing the editor,
> > the edited version of the text gets lost if it is not explicitly
> > stored.
>
> Yes, M-e just below. These two should obviously be together, but I'm
> not sure where; for now I've left them here as
>
> E Edit local file
> M-e Edit rendered copy of page
That's fine.
> >>> Buffer selection mode
> >>>
> >>> k, C-p Select previous buffer
> >>> j, C-n Select next buffer
> >>> D Delect current buffer
> >>> RET Go to the selected buffer
> >
> >> How do you get into this mode? It doesn't seem to correspond to the
> >> popup menu you get with "s"="select buffer" (where for instance it's
> >> "SPC", not "RET"), so what does it mean?
> >>
> >> s/Delect/Delete/.
> >
> > You get in this buffer selection mode with s. But "next" and
> > "previous" buffer are misleading. The explanations should be
> >
> > k, C-p Go up one position in the stack of buffers
> > j, C-n Go down one position in the stack of buffers
> > D Delete selected buffer from the stack
> > RET Display selected buffer
>
> Except that it *isnt* a buffer selection menu; it's a generic
> selection menu that's also invoked on the tabs-list when you invoke
> M-t. And as well as "k" and "C-p" you can use the up-arrow key;
> pointing that out ought to simplify the description.
>
> I'm moving this mode (along with the line-editing one) to the end,
> with an intro:
>
> 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
> ...
>
> (Then not repeating it under Lynx mode, since it doesn't vary.)
Fine.
> >> And meanwhile there's no mention at all of -N, and no default
> >> keymappings to make it useful.
> > Your comment is astonishing. By default, my w3m uses a stack of
> > buffers and the buffer selection menu is useful.
Now I see your point: You want the document to deal (more) with tabs,
not neglecting option -N and a keymapping that does not ignore tabs.
> It's a relic of the UIs of the eighties, when people worked in text
> consoles and programs could only use one window. These days if I need
> to open three different web pages in w3m I'll open them in tabs. Even
> if I was stuck on a VT, googling for "how do I fix my graphics card",
> I would be running w3m under screen. The "single window with a stack
> of invisible buffers" model is never necessary.
> I mean, imagine what people would think about it if Mozilla declared
> they were switching from a model where Firefox has tabs by default to
> one where there's only one browser window and users are expected to
> keep track of their pages in a LIFO registry of *virtual* windows.
> "It's just like browser tabs, but with the advantage of being
> completely non-discoverable!"
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.
I suspect this is an emerging madness: hiding any textual information.
> >>> Search
> > /,C-s Search forward
> > ?,C-r Search backward
> > C-s Start an incremental regexp seach forward
> > C-r Start an incremental regexp search backward
> > n Next occurence of regexp | regular expression
> > N Previous occurence of regexp | regular expression
> > C-w Toggle wrapping in regexp searches
>
> As far as I can tell, they all use regexps, and SEARCH_NEXT/PREV will
> show the next match for any existing search, so it can afford to be
> simpler:
>
> / 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
Fine.
> >>> Mark operation
> >>>
> >>> C-SPC Set/unset mark
> >>> ESC p Go to previous mark
> >>> ESC n Go to next mark
> >>> " Mark by regular expression
> >
> > " Mark all occurences of a regular expression
>
> You're right, I'd missed that. (But s/occurence/occurrence/.)
It seems that my capacities for spelling word correctly get more and
more limited to German.
> >>> C-k Show cookie jar
> >>> C-c Stop
> >
> > C-c Close an open menu
>
> It seems to do all sorts of other things too, depending on what it is
> that w3m is starting when it gets the SIGINT.
>
> >>> C-z Suspend
> >>
> >> Hitting control-C might be expected to shoot w3m dead, whereas
> >> "Suspend" might just mean "pause download", so say "Stop loading" and
> >> "Suspend w3m".
>
> (I changed my mind - at present it's labelled "Interrupt", but I'm not
> sure it should be listed at all.)
>
> > C-z SUSPEND works the same way as in emacs, the terminal window
> > disappears in X, a shell prompt appears. "fg" makes w3m
> > reappear. Probably C-z is related to a feature of bash.
>
> Well, the shell or terminal or something, yes. It's another feature
> that was really handy in the days when the user only had access to one
> window. But ^Z=SUSPEND is an actual function that you can allocate an
> arbitrary keymapping to, whereas ^C is an external SIGINT that w3m
> just catches.
I would not care for C-z and C-c if they were dropped due to this quite
special background.
Reply to: