Re: Texinfo Mode: node-based movement functions.

[Robert J. Chassell]

   Why do I focus so much on nodes?  

What do you think of `C-c C-s' (texinfo-show-structure), especially
when called with a prefix arg, so it lists the @node lines, too?

   I've never seen a printed form of a Texinfo manual.  

Ah...  Even if you do not print it out, please run

    texi2dvi cc-mode.texi

to create a DVI version of the CC Mode manual, and look at it using 

    xdvi cc-mode.dvi &

Indeed, please put the following at the beginning of cc-mode.texi:

@end ignore

    ## Info output
    makeinfo --no-split --paragraph-indent=0 --verbose cc-mode.texi

    ## DVI output
    texi2dvi cc-mode.texi

    ## HTML output
    makeinfo --html --no-split --verbose cc-mode.texi

    ## Plain text output
    makeinfo --fill-column=70 --no-split --paragraph-indent=0 \
    --verbose --no-headers --output=cc-mode.txt cc-mode.texi

    ## DocBook output
    makeinfo --docbook --no-split --paragraph-indent=0 \
    --verbose cc-mode.texi

    ## XML output
    makeinfo --xml --no-split --paragraph-indent=0 \
    --verbose cc-mode.texi

    #### (You must be in the same directory as the viewed file.)

      ## View DVI output
      xdvi cc-mode.dvi &

      ## View HTML output
      mozilla cc-mode.html

@end ignore

For an example, see 

    emacs/lispintro/emacs-lisp-intro.texi

in the Emacs distribution.

It is a good idea to run the commands to create the Info, HTML, and
DVI outputs frequently and to look at them.  That way, you can catch
errors early on.  (It is also a good idea to listen to the Info using
Emacspeak, as if you were driving a car or permanently blind.  If the
document makes sense when you listen to it, it is well written.  Now
that Emacspeak has good-enough, free software text-to-speech
synthesizers, anyone can do this.)


   What do you mean by "too close" here?  

Woops!  I was being old fashioned.  I had forgot about XML.  I had
meant to push you towards @heading but should direct you instead to
the less good @unnumberedsec.

As for being "too close" -- it is best to start a section within 24 or
so lines of the beginning of a chapter so that the section menu is
visible in Info.  However, in a printed book, that looks bad.  So, in
the old days, we hid that first section line by putting it in
address@hidden'.  But XML has come along, so instead the Texinfo manual
says:

    (texinfo)Menu Location

      In the past, we recommended using a address@hidden' command within an
    address@hidden' conditional instead of the normal sectioning commands
    after a very short node with a menu.  This had the advantage of
    making the printed output look better, because there was no very
    short text between two headings on the page.  But aside from not
    working with `makeinfo''s implicit pointer creation, it also makes
    the XML output incorrect, since it does not reflect the true
    document structure.  So, unfortunately we can no longer recommend
    this.

One modern way to do the job is to use @unnumberedsec in place of
@section for the first subnode of a chapter (or lower level
construct).  This does not always produce the right output, but ....

For example, emacs/lispintro/emacs-lisp-intro.texi has this format
(leaving out the @node lines that a prefix arg to
texinfo-show-structure provides):

   1053:@chapter List Processing
   1083:    @section Lisp Lists
   1115:        @unnumberedsubsec Numbers, Lists inside of Lists
   1144:        @subsection Lisp Atoms
   1225:        @subsection Whitespace in Lists

Please compare the Info output with the DVI output.  That works out
well.

The table of contents for the HTML output, which is in 
    emacs/info/eintr.html
looks like this, which is a problem with this format, but not a big one:

    1.1 Lisp Lists
        * Numbers, Lists inside of Lists
        * 1.1.1 Lisp Atoms
        * 1.1.2 Whitespace in Lists 

Since Info and printed copies are the most efficient forms in which a
Texinfo document appears (and probably the most common, although many
people use the less efficient HTML format), the lack of a number for
the `unnumbered' HTML node is OK.  Someday, I must look at the XML but
since I fear the worst, I have not....

-- 
    Robert J. Chassell                         
    address@hidden                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc