Re: texinfo-master-menu and emacs.texi

[Eli Zaretskii <eliz@gnu.org>]

> Date: Wed, 7 Dec 2011 08:08:00 -0600
> From: "Roland Winkler" <winkler@gnu.org>
> Cc: emacs-devel@gnu.org
> 
> On Wed Dec 7 2011 Eli Zaretskii wrote:
> > It would help if you'd show the error messages from the "unhappy"
> > makeinfo.  
> 
> Thanks for your help. I attached the diffs between the original
> emacs.texi and what texinfo-master-menu made out of it
> (diff-emacs.texi.txt). Also, I attached a file makinfo-output.txt
> with the makeinfo output for the modified file emacs.texi

Here's what I see there:

 . texinfo-master-menu indeed does not support multiple-file manuals,
   so it removed all the menu items whose nodes are in files other
   than emacs.texi itself

 . texinfo-master-menu doesn't grok @iftex and @ifnottext conditionals
   (and probably the other @if... conditionals as well), so it
   produced bad Next and Prev pointers, because, e.g., this:

    @ifnottex
    ...
    @node Command Index, Variable Index, Option Index, Top
    @unnumbered Command and Function Index
    @printindex fn
    @end ifnottex

    @iftex
    @node Command Index, Variable Index, Key Index, Top
    @unnumbered Command and Function Index
    @printindex fn
    @end iftex

   looks to it as if the "Command Index" node follows the "Command
   Index" node, and therefore it generates a bogus @node line, where
   the Next pointer for "Command Index" is "Command Index" itself:

    -@node Command Index, Variable Index, Option Index, Top
    +@node Command Index, Command Index, Option Index, Top

> > As things are, I need to guess, and my guess is that
> > texinfo-master-menu does not support multi-file manuals. It only
> > works on a single buffer. At least I don't see in its code any
> > hints that it does have the ability to gather all the multiple
> > files which constitute the ELisp manual, using the @include
> > directives or some such.
> 
> If this was the case it would help if it was documented somewhere.

I agree.  As far as Emacs is concerned, the documentation is in the
doc strings, which should be enriched with a few pointers and
explanations.  But the bulk of the documentation is in the Texinfo
manual, and even if the version on CVS improves this significantly (I
wouldn't hold my breath ;-), it's anybody's guess when it will hit the
FTP site near you, since Texinfo currently undergoes a significant
surgery which I have no idea when will end and culminate in a release.

> > My advice is to use texinfo-update-node and texinfo-make-menu on
> > individual nodes or groups of nodes as you go; that's what I do.
> > Unless your manual is on a single large file, in which case I expect
> > texinfo-master-menu to just work.
> 
> While my info manual is still very short, it contains already three
> files as I am including the files gpl.texi and doclicense.texi. It
> would be unfortunate if the inclusion of these files made it already
> impossible to use texinfo-master-menu.

For manuals spread across several files, you need the following
procedure:

 . In each individual file, run texinfo-update-node and
   texinfo-make-menu as necessary (i.e., only in those nodes which you
   modified or created anew)

 . After doing the above for all the constituent files, including the
   "outer" file (the main one, which includes the other ones), invoke
   "C-u M-x texinfo-multiple-files-update RET", to update the master
   menu in the "outer" file.  (You will see in emacs.texi some
   comments that are evidence of this latter command being used on the
   Emacs manuals.)  Please read carefully the doc string of
   texinfo-multiple-files-update and its documentation in the Texinfo
   manual, before you invoke it, to make sure you understand what it
   will do.

Let me know if the above 2-step procedure does what you want.