Bug 76322

Created attachment 81144 [details]
Open Office document detailing errors

Assinging to texinfo. Note that we generally prefer plain text for bug reports.

The document reads:

Dear Red Hat Support,

I am a Linux/Unix nubie, but I have been working in computers since before the
microprocessor was a twinkle in Intel's eye.  I have been struggling to gain
familiarity with Linux, having now downloaded and installed all releases and
betas since 7.2, if not before.  It is disconcerting, then, to find fundamental
flaws in help text and documentation provided with your recent Psyche (8.0)
release, especially with all the furor over it being a desktop version of
Linux, not just a server for the technically inclined.

Pretend you're a nubie; go to a terminal session, and type info info.  Follow
the instructions  type 'h' for nubie help, and follow each of the
recommendations.  By the way, no mouse-clicks work to navigate thru 'info.' 
(Maybe that help is for emacs only, but the help text doesn't make that clear.)
Then, when you get to the part where it says press '?' for command-level help ... 

>> Type a <?> now.  Press <SPC> to see consecutive screenfuls of
   the list until finished.  Then type <SPC> several times, until
   it goes away.

   (If you are using the stand-alone Info reader, type `C-x 0' to
   return here, that is--press and hold <CTRL>, type an `x', then release
   <CTRL> and `x', and press `0'--a zero, not the letter "o".)

Repeated SPC s never gets you out of the '?' help. Ctrl-x 0 kills the window in
which the '?' help was displayed, which is also the original info window,
leaving you with nothing but a footnote window!  Instead, the lowercase 'ell'
key works to get you back to the original window, as is indicated by the 1st
line in the '?' help, but still, a poor nubie trying to follow step-by-step
instructions will get confused, and MAY become discouraged.

The '?' help itself is not without errors, for example ...

	Moving within a node:
	---------------------
	SPC	Scroll forward a page.			Note the multiple-
	DEL	Scroll backward a page.			Uses of SPC and DEL
	b	Go to the beginning of this node.	In this '?' help table.
	e	Go to the end of this node.
	SPC	Scroll forward 1 line.
	DEL	Scroll backward 1 line.

In fact, to nit-pick, NO scroll forward/back one line consistently works like
that ... Ctrl-n and Ctrl-P, (or downarrow, uparrow) scrolls 1 line until you hit
a window margin, at which point it jumps a half-screen or so to center the line
in the window.  True, the cursor is still on the hot line, but the screen jump
is disconcerting, to say the least.

Menu operations  after activating a menu subtopic, the tutorial says to use 'u'
to return to the topic, but that takes you all the way to the beginning of the
topic ... nowhere did I see mention that 'ell' in this case takes you right back
to the line from which you launched the subtopic!  Also, help says Alt-Tab takes
you to the previous menu selection, but at least in the graphical versions,
Alt-Tab switches out of the 'info' pane to another active pane, while Shift-Tab
performs the previous menu selection function.
The 8.0 Getting Started Guide, on the documentation CD, also has a gaffe in the
examples for using 'cat.'  The final example purports to show that the two
sample files created in the previous examples are identical, then lists contents
that are NOT identical.  Again, confusing to nubies, if they actually try to
learn the fundamentals.

Please don't take these observations as denigration or even complaint!  I want
Linux on my desktop.  I want it to succeed and provide an alternative to the
monopolistic behemoth I hope to replace.  I simply fear that overlooking the
details in fundamental help text and documentation may slow its acceptance. 

I will continue to strive toward my goal, but I fear it will not happen as fast
as I would like

So, to summarise:

1. 'info' is in general hard to use for people new to Linux
2. 'info' help contains incorrect descriptions of keybindings
3. GSG has an error, presumably in figure 11-17.

It is expected that new users would use the graphical help browser, available
from the main menu->Help (a link to info pages is at the bottom).  Putting
effort into making 'info' (a console-only program) easier to use given that we
already have at least two graphical help browsers seems a waste of resources
that could be better spent making the graphical help browser easier to use, IMHO.

Indeed, 'info' has incorrect keybinding descriptions.  Thanks for letting us
know.  I'll change the summary of this bug report to reflect that.

As for the GSG, you have sharper eyes than I do.  Please explain exactly what
you think is wrong, along with exactly where it is, and file it as a bug against
the 'rhl-gsg' component.  Thanks.

Status with texinfo-4.8:
- The help text does say that mouse works only in Emacs
- The help text does say that window will go away automatically only in emacs
- But it still says that C-x 0 will close the window
- The '?' page says to use 'l' at the end, not only at the beginning
- C-p, C-n are accurately described as "move up/down to the next/previous line"
- 'l' is described a few pages after menus (it works also on cross-references)
- M-tab is handled outside of info, info can't really predict in which environment
  it will run; M-tab works fine on the console.

I have filed a patch for the remaining bug (C-x 0) upstream.

Thanks for your report.