[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: texinfo-master-menu and emacs.texi
From: |
Eli Zaretskii |
Subject: |
Re: texinfo-master-menu and emacs.texi |
Date: |
Thu, 08 Dec 2011 01:46:17 -0500 |
> Date: Wed, 7 Dec 2011 08:08:00 -0600
> From: "Roland Winkler" <address@hidden>
> Cc: address@hidden
>
> 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:
address@hidden Command Index, Variable Index, Option Index, Top
address@hidden 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.