bug#2975: `texinfo-master-menu' doesn't work.

bug#2975: `texinfo-master-menu' doesn't work.

[Alan Mackenzie]

In Emacs, either 22.3 or a recent CVS version ...
emacs -Q

1.

(i) C-c C-f .../path/to/emacs/doc/misc/cc-mode.texi
(ii) M-g M-g 238          ; the second line of the menu,
                          ; contents "* Overview::"
(ii) C-k C-k              ; Kill this line

(v) Now do C-c C-u m.  This flashes the screen and reports
"Done...completed making master menu.  You may save the buffer.".
However, it hasn't made the master menu - the "* Overview::" line is
still missing.

########################################################################

2.

(i) Kill (remove) the entire master menu from the buffer (between the
  lines "@menu" and "@end menu").
  
(ii) Try to regenerate the master menu with C-c C-u m.  This signals the
puzzling error "Buffer lacks ordinary `Top' menu in which to insert
master".  It is not clear what a "`Top' menu" is, in what respect it is
"ordinary", and in what regard the new master menu is inserted into it.
The existing master menu was not contained within any menu.

#########################################################################

3.

(i) C-c C-f .../path/to/emacs/doc/lispref/elisp.texi
(ii) M-g M-g 108       ; the second line of the menu,
                       ; "* Lisp Data Types:: ...."
(iii) C-k C-k          ; Kill this line

(iv) Now do C-c C-u m.  This doesn't regenerate the master menu.
Instead, it deletes the @detailmenu without restoring the "* Lisp Data
Types::" line.

#########################################################################

Comments:

Neither the doc string for `texinfo-master-menu' nor the texinfo manual
(page "Updating Nodes and Menus") describe other than vaguely what this
command is supposed to do.

The doc string states, accurately, that

    The function removes the detailed part of an already existing master
    menu.

, which though accurate, is puzzling in the extreme; what one wants from
this command is for the detailed bit to be inserted, not deleted.

There is no verb in "texinfo master menu", so one is led by intelligent
guessing to believe that the command does whatever necessary to insert
or update the master menu.  This doesn't happen.

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#2975: `texinfo-master-menu' doesn't work.

[Eli Zaretskii]

> Date: Sun, 12 Apr 2009 21:33:40 +0000
> From: Alan Mackenzie <acm@muc.de>
> 
> In Emacs, either 22.3 or a recent CVS version ...
> emacs -Q
> 
> 1.
> 
> (i) C-c C-f .../path/to/emacs/doc/misc/cc-mode.texi
> (ii) M-g M-g 238          ; the second line of the menu,
>                           ; contents "* Overview::"
> (ii) C-k C-k              ; Kill this line
> 
> (v) Now do C-c C-u m.  This flashes the screen and reports
> "Done...completed making master menu.  You may save the buffer.".
> However, it hasn't made the master menu - the "* Overview::" line is
> still missing.

"C-c C-u m" (texinfo-master-menu) is not supposed to update the menus
in the buffer, including the menu in the Top node, unless you invoke
it with a prefix argument.  If you don't invoke it with a prefix arg,
you need to update the menus yourself, either manually or by running
texinfo-make-menu or texinfo-all-menus-update.  This is because this
command only looks at the _existing_ menus; it does NOT look at the
@node lines to recreate or update any missing/outdated entries in
those menus.

I made this clear in the doc string of texinfo-master-menu.

> 2.
> 
> (i) Kill (remove) the entire master menu from the buffer (between the
>   lines "@menu" and "@end menu").
>   
> (ii) Try to regenerate the master menu with C-c C-u m.  This signals the
> puzzling error "Buffer lacks ordinary `Top' menu in which to insert
> master".  It is not clear what a "`Top' menu" is, in what respect it is
> "ordinary", and in what regard the new master menu is inserted into it.
> The existing master menu was not contained within any menu.

The error is signaled because texinfo-master-menu does not update or
create any menus, see above.  By deleting the menu in the Top node,
you removed the part of the buffer on which texinfo-master-menu
depends for doing its job.  So it barfed.

I changed the error message text so it is hopefully more clear.  It
now says:

  Buffer lacks a menu in its first node; create it, then run me again

> 3.
> 
> (i) C-c C-f .../path/to/emacs/doc/lispref/elisp.texi
> (ii) M-g M-g 108       ; the second line of the menu,
>                        ; "* Lisp Data Types:: ...."
> (iii) C-k C-k          ; Kill this line
> 
> (iv) Now do C-c C-u m.  This doesn't regenerate the master menu.
> Instead, it deletes the @detailmenu without restoring the "* Lisp Data
> Types::" line.

texinfo-master-menu does not support multi-file manuals (which is what
elisp.texi is).  For that, one should use
texinfo-multiple-files-update.  I made that clear in the doc string.

> Neither the doc string for `texinfo-master-menu' nor the texinfo manual
> (page "Updating Nodes and Menus") describe other than vaguely what this
> command is supposed to do.

I made that more clear in the commentary at the beginning of
texnfo-upd.el and in the doc string of texinfo-master-menu.

> The doc string states, accurately, that
> 
>     The function removes the detailed part of an already existing master
>     menu.
> 
> , which though accurate, is puzzling in the extreme; what one wants from
> this command is for the detailed bit to be inserted, not deleted.
> 
> There is no verb in "texinfo master menu", so one is led by intelligent
> guessing to believe that the command does whatever necessary to insert
> or update the master menu.  This doesn't happen.

The crucial part of the doc string was this:

  The master menu includes every entry from all the other menus.

IOW, it only collects entries from existing menus, it does NOT update
the menus.  Admittedly, this crucial piece of information was buried
deep in the doc string.  Hopefully, now it is more clear.

All of the above changes are in revision 106651 on the trunk.

I'm closing this bug report.  Sorry for the long delay in handling it.

bug#2975: `texinfo-master-menu' doesn't work.

[Eli Zaretskii]

> Date: Sun, 11 Dec 2011 17:38:59 +0000
> Cc: bug-texinfo@gnu.org, 2975-done@debbugs.gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > "C-c C-u m" (texinfo-master-menu) is not supposed to update the menus
> > in the buffer, including the menu in the Top node, unless you invoke
> > it with a prefix argument.  If you don't invoke it with a prefix arg,
> > you need to update the menus yourself, either manually or by running
> > texinfo-make-menu or texinfo-all-menus-update.  This is because this
> > command only looks at the _existing_ menus; it does NOT look at the
> > @node lines to recreate or update any missing/outdated entries in
> > those menus.
> 
> > I made this clear in the doc string of texinfo-master-menu.
> 
> Sorry, I find it anything but clear.  I think I've finally twigged what
> C-c C-u m does.  It creates or updates the @detailmenu part of the master
> menu.  Please correct me if I'm wrong about this.  However, it doesn't
> create/update the first part of the master menu, and nor does it create
> the @detailmenu if @menu is missing.

Correct.  And now the current doc string:

    "Make a master menu for a whole Texinfo file.
  Remove pre-existing master menu, if there is one.

  This function supports only single-file manuals.  For multi-file
  manuals, use `texinfo-multiple-files-update'.

  This function creates or updates the @detailmenu section of a
  master menu that follows the Top node.  It replaces any existing
  detailed menu that follows the top node.  The detailed menu
  includes every entry from all the other menus.  By default, the
  existing menus, including the menu in the Top node, are not
  updated according to the buffer contents, so all the menus should
  be updated first using `texinfo-make-menu' or
  `texinfo-all-menus-update', which see.  Alternatively, invoke
  this function with a prefix argument, see below.

  Non-nil, non-numeric argument (C-u prefix, if interactive) means
  first update all existing menus in the buffer (incorporating
  descriptions from pre-existing menus) before it constructs the
  master menu.  If the argument is numeric (e.g., \"C-u 2\"),
  update all existing nodes as well, by calling
  \`texinfo-update-node' on the entire file.  Warning: do NOT
  invoke with a numeric argument if your Texinfo file uses @node
  lines without the `Next', `Previous', `Up' pointers, as the
  result could be an invalid Texinfo file!

  The function removes and recreates the detailed part of an already
  existing master menu.  This action assumes that the pre-existing
  master menu uses the standard `texinfo-master-menu-header' for the
  detailed menu.

  The master menu has the following format, which is adapted from the
  recommendation in the Texinfo Manual:

     * The first part contains the major nodes in the Texinfo file: the
       nodes for the chapters, chapter-like sections, and the major
       appendices.  This includes the indices, so long as they are in
       chapter-like sections, such as unnumbered sections.

     * The second and subsequent parts contain a listing of the other,
       lower level menus, in order.  This way, an inquirer can go
       directly to a particular node if he or she is searching for
       specific information.

  Each of the menus in the detailed node listing is introduced by the
  title of the section containing the menu.

> @dfn{master menu} is on page "Master Menu Parts" in the Texinfo manual.
> In particular,
> 
>     A master menu is enclosed in `@menu' and `@end menu' commands ...

I didn't do anything with the Texinfo manual, mind you.  This bug
report is about Emacs.

> Why doesn't C-c C-u m update the entire master menu?  I mean, what use is
> the current command, as opposed to the one I want?

I'm just guessing here, but my guess is that you sometimes may wish to
create or update only the @detailmenu.  After all, texinfo-make-menu
is the way to create/update any menu, including the top-level menu, if
you don't have one or if it is outdated.

> > > 2.
> 
> > > (i) Kill (remove) the entire master menu from the buffer (between the
> > >   lines "@menu" and "@end menu").
> 
> > > (ii) Try to regenerate the master menu with C-c C-u m.  This signals the
> > > puzzling error "Buffer lacks ordinary `Top' menu in which to insert
> > > master".  It is not clear what a "`Top' menu" is, in what respect it is
> > > "ordinary", and in what regard the new master menu is inserted into it.
> > > The existing master menu was not contained within any menu.
> 
> > The error is signaled because texinfo-master-menu does not update or
> > create any menus, see above.
> 
> t-m-m's doc string states explicitly that it DOES make a master menu.

It sounds like your notion of "master menu" is different from what the
command means, see above.

> > IOW, it only collects entries from existing menus, it does NOT update
> > the menus.  Admittedly, this crucial piece of information was buried
> > deep in the doc string.  Hopefully, now it is more clear.
> 
> I think I've understood now, but I don't think it's at all clear.

Feel free to suggest specific improvements or point out specific
parts of the doc string that need improvement.

bug#2975: `texinfo-master-menu' doesn't work.

[Alan Mackenzie]

Hello again, Eli.

On Sun, Dec 11, 2011 at 08:18:06PM +0200, Eli Zaretskii wrote:
> > Date: Sun, 11 Dec 2011 17:38:59 +0000
> > Cc: bug-texinfo@gnu.org, 2975-done@debbugs.gnu.org
> > From: Alan Mackenzie <acm@muc.de>

> > > "C-c C-u m" (texinfo-master-menu) is not supposed to update the menus
> > > in the buffer, including the menu in the Top node, unless you invoke
> > > it with a prefix argument.  If you don't invoke it with a prefix arg,
> > > you need to update the menus yourself, either manually or by running
> > > texinfo-make-menu or texinfo-all-menus-update.  This is because this
> > > command only looks at the _existing_ menus; it does NOT look at the
> > > @node lines to recreate or update any missing/outdated entries in
> > > those menus.

> > > I made this clear in the doc string of texinfo-master-menu.

Although I updated and rebuilt Emacs yesterday, I got the old doc string,
so please forgive my reply.  The way I got this doc string was:

    emacs -Q
    M-x load-library texinfo
    C-h f texinfo-master-menu

.  It turns out that the doc string is duplicated in texinfo.el in an
autoload form.  ;-(

[ .... ]

> And now the current doc string:

>     "Make a master menu for a whole Texinfo file.
>   Remove pre-existing master menu, if there is one.

>   This function supports only single-file manuals.  For multi-file
>   manuals, use `texinfo-multiple-files-update'.

>   This function creates or updates the @detailmenu section of a
>   master menu that follows the Top node.  It replaces any existing
>   detailed menu that follows the top node.  The detailed menu
>   includes every entry from all the other menus.  By default, the
>   existing menus, including the menu in the Top node, are not
>   updated according to the buffer contents, so all the menus should
>   be updated first using `texinfo-make-menu' or
>   `texinfo-all-menus-update', which see.  Alternatively, invoke
>   this function with a prefix argument, see below.

>   Non-nil, non-numeric argument (C-u prefix, if interactive) means
>   first update all existing menus in the buffer (incorporating
>   descriptions from pre-existing menus) before it constructs the

Correction: "before CONSTRUCTING the master menu."

>   master menu.  If the argument is numeric (e.g., \"C-u 2\"),
>   update all existing nodes as well, by calling
>   \`texinfo-update-node' on the entire file.  Warning: do NOT
>   invoke with a numeric argument if your Texinfo file uses @node
>   lines without the `Next', `Previous', `Up' pointers, as the
>   result could be an invalid Texinfo file!

>   The function removes and recreates the detailed part of an already
>   existing master menu.  This action assumes that the pre-existing
>   master menu uses the standard `texinfo-master-menu-header' for the
>   detailed menu.

>   The master menu has the following format, which is adapted from the
>   recommendation in the Texinfo Manual:

>      * The first part contains the major nodes in the Texinfo file: the
>        nodes for the chapters, chapter-like sections, and the major
>        appendices.  This includes the indices, so long as they are in
>        chapter-like sections, such as unnumbered sections.

>      * The second and subsequent parts contain a listing of the other,
>        lower level menus, in order.  This way, an inquirer can go
>        directly to a particular node if he or she is searching for
>        specific information.

>   Each of the menus in the detailed node listing is introduced by the
>   title of the section containing the menu.

> > @dfn{master menu} is on page "Master Menu Parts" in the Texinfo manual.
> > In particular,

> >     A master menu is enclosed in `@menu' and `@end menu' commands ...

> I didn't do anything with the Texinfo manual, mind you.  This bug
> report is about Emacs.

:-)  There's an inconsistency there.  The manual is Karl B's thing, isn't
it?

> > Why doesn't C-c C-u m update the entire master menu?  I mean, what use is
> > the current command, as opposed to the one I want?

> I'm just guessing here, but my guess is that you sometimes may wish to
> create or update only the @detailmenu.  After all, texinfo-make-menu
> is the way to create/update any menu, including the top-level menu, if
> you don't have one or if it is outdated.

[ .... ]

> > t-m-m's doc string states explicitly that it DOES make a master menu.

> It sounds like your notion of "master menu" is different from what the
> command means, see above.

THAT is the thing that's caused this discussion.  I have conceptualised
"master menu" as the entire hierarchical thing starting at Top.  You have
seen a separate menu in each node (including Top) and then @detailedmenu
as a summary, a distinct entity.  Now everything is clear.

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#2975: `texinfo-master-menu' doesn't work.

[Eli Zaretskii]

> Date: Mon, 12 Dec 2011 12:25:44 +0000
> Cc: 2975@debbugs.gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > It sounds like your notion of "master menu" is different from what the
> > command means, see above.
> 
> THAT is the thing that's caused this discussion.  I have conceptualised
> "master menu" as the entire hierarchical thing starting at Top.  You have
> seen a separate menu in each node (including Top) and then @detailedmenu
> as a summary, a distinct entity.  Now everything is clear.

Does the new doc string make this clear, or do you still see place for
improvement?

Thanks.

bug#2975: texinfo-master-menu and emacs.texi

[Stefan Monnier]

> Thanks...Now I am yet more confused. I thought I look into
> emacs.texi because I assumed that this info manual has been updated
> continuously in recent years and this updating has been done with
> the editor of my choice which is emacs. So what have people done who
> contributed to the emacs info manual to work around these
> difficulties? Which parts of emacs' texinfo support do what they are
> supposed to do and which parts seem to be malfunctioning?

I'm pretty sure texinfo-master-menu is not used for that, indeed.
I think "update all menus" is the more common helper command.

IIRC it also suffered from problems where it adds data to "Node"s which
should better not be added at all, so makeinfo can auto-fill it for you
(and makeinfo actually complains about what texinfo-master-menu puts
there).

Maybe the better course here is to deprecate it, seeing how noone seems
interested in fixing it (if it can be fixed).


        Stefan

bug#2975: texinfo-master-menu and emacs.texi

[Roland Winkler]

On Wed Dec 7 2011 Stefan Monnier wrote:
> I'm pretty sure texinfo-master-menu is not used for that, indeed.
> I think "update all menus" is the more common helper command.
> 
> IIRC it also suffered from problems where it adds data to "Node"s which
> should better not be added at all, so makeinfo can auto-fill it for you
> (and makeinfo actually complains about what texinfo-master-menu puts
> there).

I am not sure I understand what you say about nodes. I started this
thread because

> The texinfo manual says about "Updating Nodes and Menus"
> 
>   If you do not use the updating commands, you need to write menus
>   and node pointers by hand, which is a tedious task.

Is there any emacs command that can help reliably for updating the nodes?
(Nodes appear to get screwed up by texinfo-master-menu.)

Of course, I believe that makeinfo can add the info about the node
pointers. But what about output formats not supported by makeinfo?
I believe that something like TeX needs them.

> Maybe the better course here is to deprecate it, seeing how noone seems
> interested in fixing it (if it can be fixed).

This would certainly help at least somewhat to clarify the
situation.

Roland

bug#2975: texinfo-master-menu and emacs.texi

[Eli Zaretskii]

> Date: Wed, 7 Dec 2011 15:19:59 -0600
> From: "Roland Winkler" <winkler@gnu.org>
> Cc: 2975@debbugs.gnu.org
> 
> On Wed Dec 7 2011 Stefan Monnier wrote:
> > I'm pretty sure texinfo-master-menu is not used for that, indeed.
> > I think "update all menus" is the more common helper command.
> > 
> > IIRC it also suffered from problems where it adds data to "Node"s which
> > should better not be added at all, so makeinfo can auto-fill it for you
> > (and makeinfo actually complains about what texinfo-master-menu puts
> > there).
> 
> I am not sure I understand what you say about nodes.

What Stefan says is that the form of @node produced by
texinfo-master-menu (when it is invoked on a region and/or with a
prefix argument) includes the Next, Prev, and Up pointers, even if the
original file didn't have those pointers.  Worse, due to incomplete
support of the more advanced Texinfo features, the produced pointers
can cause makeinfo barf.  IOW, the command could potentially take a
perfectly valid Texinfo file and produce an invalid one.

The node pointers thingy is particularly baaad because makeinfo
doesn't actually need these pointers, if your Texinfo files are
structured using a few simple rules, documented in the Texinfo manual,
see "texinfo(makeinfo Pointer Creation)".

If you keep your Texinfo structured according to these rules, there's
no need for Next, Prev, and Up pointers on the @node lines; makeinfo
will compute them automatically.

By forcibly inserting these pointers, texinfo-master-menu prevents you
from using this very convenient feature: you are forced to maintain
these pointers whenever you insert or delete nodes.

> I started this thread because
> 
> > The texinfo manual says about "Updating Nodes and Menus"
> > 
> >   If you do not use the updating commands, you need to write menus
> >   and node pointers by hand, which is a tedious task.
> 
> Is there any emacs command that can help reliably for updating the nodes?
> (Nodes appear to get screwed up by texinfo-master-menu.)

Well, see above: you don't need to be bothered by that, if you adhere
to the rules explained in the Texinfo manual.

> Of course, I believe that makeinfo can add the info about the node
> pointers. But what about output formats not supported by makeinfo?
> I believe that something like TeX needs them.

TeX doesn't need them.  These pointers are there to allow traversing
the on-line manual, and are not needed for non on-line versions.

> > Maybe the better course here is to deprecate it, seeing how noone seems
> > interested in fixing it (if it can be fixed).

Define "fixed".  Which of the current misfeatures are urgent to fix?

> This would certainly help at least somewhat to clarify the
> situation.

See my other mail (which I didn't write yet ;-) about "the situation".

bug#2975: texinfo-master-menu and emacs.texi

[Štěpán Němec]

On Thu, 08 Dec 2011 07:17:40 +0100
Eli Zaretskii wrote:

>> > Maybe the better course here is to deprecate it, seeing how noone seems
>> > interested in fixing it (if it can be fixed).
>
> Define "fixed".  Which of the current misfeatures are urgent to fix?

I'd say the fact that OT1H `texinfo-master-menu' is recommended as "the
primary command" in the Texinfo manual (info "(texinfo)Updating Commands"),
and OTOH it (sometimes?) breaks things, is a rather urgent-to-be-fixed
misfeature. I've had this problem in the past, too, and had no idea
what's going on until this came up now.

I think it's very important that there is a clear recipe for maintaining
Texinfo documentation which people not interested in the details or
implementation of Texinfo (== the vast majority of Texinfo writers) can
easily find and go by.

-- 
Štěpán

bug#2975: texinfo-master-menu and emacs.texi

[Eli Zaretskii]

> From: Štěpán Němec <stepnem@gmail.com>
> Cc: "Roland Winkler" <winkler@gnu.org>,  2975@debbugs.gnu.org
> Date: Thu, 08 Dec 2011 11:38:01 +0100
> 
> On Thu, 08 Dec 2011 07:17:40 +0100
> Eli Zaretskii wrote:
> 
> >> > Maybe the better course here is to deprecate it, seeing how noone seems
> >> > interested in fixing it (if it can be fixed).
> >
> > Define "fixed".  Which of the current misfeatures are urgent to fix?
> 
> I'd say the fact that OT1H `texinfo-master-menu' is recommended as "the
> primary command" in the Texinfo manual (info "(texinfo)Updating Commands"),
> and OTOH it (sometimes?) breaks things, is a rather urgent-to-be-fixed
> misfeature.

The simplest fix would be to remove the updating of the @node lines.
Would anyone object?  Karl?

> I think it's very important that there is a clear recipe for maintaining
> Texinfo documentation which people not interested in the details or
> implementation of Texinfo (== the vast majority of Texinfo writers) can
> easily find and go by.

That is a separate and non-trivial project.  Texinfo Mode has a lot of
commands, some of which cater to specific workflows and organizations
of manuals.  Making a coherent set of instructions for people who are
"not interested in the details" is not an easy task.  It certainly
doesn't affect only Emacs.

However, since this discussion _is_ in the context of Emacs, let me
say this: FWIW, most changes I do in the Emacs docs do not justify
using any of the commands discussed in this bug report and in the
parallel thread on emacs-devel.  I just make the changes by hand.  I
believe others do that as well.  There are rare situations when I use
the commands discussed here, typically close to a release when there's
a need to make sure every menu is up to date.  E.g., I didn't even
remember the existence of texinfo-multiple-files-update until I bumped
into a comment in emacs.texi, although I myself added that comment
several years ago.

I guess I'm saying that the importance of these commands in the
context of maintaining Emacs documentation is somewhat exaggerated in
this thread, to say the least ;-)

bug#2975: texinfo-master-menu and emacs.texi

[Stefan Monnier]

Karl writes:
> Perhaps the description of texinfo-mode would be better off in the Emacs
> manual, instead of the Texinfo manual.  (Since it is not maintained as
> part of Texinfo.)  I'd be fine with that.  Whatever you want to do.

Sounds like a good idea, yes.

Eli writes:
> The simplest fix would be to remove the updating of the @node lines.
> Would anyone object?  Karl?

That would be great.

Eli writes:
> I guess I'm saying that the importance of these commands in the
> context of maintaining Emacs documentation is somewhat exaggerated in
> this thread, to say the least ;-)

IIUC the OP is not directly interested in maintaining Emacs
documentation but rather is trying to write a manual for another project
(BBDB, which happens to be an Emacs package).

Eli writes:
> 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

A good fix here would be for texinfo-master-menu to detect the problem
and signal a warning/error.

>  . 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:

If leaving Node pointers alone fixes this problem, then there's nothing
else to do, but otherwise texinfo-master-menu should try and detect
these problematic cases and signal an error/warning.


        Stefan

bug#2975: texinfo-master-menu and emacs.texi

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Cc: Štěpán Němec <stepnem@gmail.com>,
>         2975@debbugs.gnu.org, winkler@gnu.org,
>         Karl Berry
>  <karl@freefriends.org>
> Date: Thu, 08 Dec 2011 09:46:49 -0500
> 
> Eli writes:
> > The simplest fix would be to remove the updating of the @node lines.
> > Would anyone object?  Karl?
> 
> That would be great.

I made it extremely optional instead: only "C-u N" where N is a number
would cause @node lines to be updated with next/prev/up pointers.

> Eli writes:
> > I guess I'm saying that the importance of these commands in the
> > context of maintaining Emacs documentation is somewhat exaggerated in
> > this thread, to say the least ;-)
> 
> IIUC the OP is not directly interested in maintaining Emacs
> documentation but rather is trying to write a manual for another project
> (BBDB, which happens to be an Emacs package).

He was asking about the effects of invoking these commands on
emacs.texi.

> Eli writes:
> > 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
> 
> A good fix here would be for texinfo-master-menu to detect the problem
> and signal a warning/error.
> 
> >  . 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:
> 
> If leaving Node pointers alone fixes this problem, then there's nothing
> else to do, but otherwise texinfo-master-menu should try and detect
> these problematic cases and signal an error/warning.

The detection and error signaling are left as an exercise for the
interested readers ;-)

bug#2975: texinfo-master-menu and emacs.texi

[Roland Winkler]

On Thu Dec 8 2011 Eli Zaretskii wrote:
> The simplest fix would be to remove the updating of the @node lines.
> Would anyone object?  Karl?

A TeXnical question: what about using TeX to generate the output? 
To the best of my knowledge makinfo doesn't care about @node lines
being up to date or not, it can fix them itself. Does the same hold
for TeX?

Roland

bug#2975: texinfo-master-menu and emacs.texi

[Roland Winkler]

On Thu Dec 8 2011 Roland Winkler wrote:
> On Thu Dec 8 2011 Eli Zaretskii wrote:
> > The simplest fix would be to remove the updating of the @node lines.
> > Would anyone object?  Karl?
> 
> A TeXnical question: what about using TeX to generate the output? 
> To the best of my knowledge makinfo doesn't care about @node lines
> being up to date or not, it can fix them itself. Does the same hold
> for TeX?

I am sorry, I overlooked you clarified this point in a previous
post.

Roland

bug#2975: texinfo-master-menu and emacs.texi

[Štěpán Němec]

On Thu, 08 Dec 2011 19:52:17 +0100
Roland Winkler wrote:

> On Thu Dec 8 2011 Eli Zaretskii wrote:
>> The simplest fix would be to remove the updating of the @node lines.
>> Would anyone object?  Karl?
>
> A TeXnical question: what about using TeX to generate the output? 
> To the best of my knowledge makinfo doesn't care about @node lines
> being up to date or not, it can fix them itself. Does the same hold
> for TeX?

Unless I'm missing something, you already got an answer to this question
in Eli's first reply in this thread:

---
[Roland]
> Of course, I believe that makeinfo can add the info about the node
> pointers. But what about output formats not supported by makeinfo?
> I believe that something like TeX needs them.

[Eli]
TeX doesn't need them.  These pointers are there to allow traversing
the on-line manual, and are not needed for non on-line versions.
---

(Personally I found Eli's explanation confusing -- what does "on-line"
mean here? If it means HTML, makeinfo does support HTML output -- does
it mean it doesn't cope with missing node pointers in the HTML case? If
it means the standard Info manuals, then that's the principal format
supported, isn't it...)

-- 
Štěpán

bug#2975: texinfo-master-menu and emacs.texi

[Eli Zaretskii]

> From: Štěpán Němec <stepnem@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,  2975@debbugs.gnu.org,  Karl Berry <karl@freefriends.org>
> Date: Thu, 08 Dec 2011 20:06:45 +0100
> 
> (Personally I found Eli's explanation confusing -- what does "on-line"
> mean here? If it means HTML, makeinfo does support HTML output -- does
> it mean it doesn't cope with missing node pointers in the HTML case?

"On-line" means all on-line formats, including HTML.

What do you mean by "it doesn't cope" -- who or what is "it" here?

makeinfo does not need these pointers in the Texinfo sources to
produce them in any of its outputs that are meant for on-line
browsing.  That includes HTML (and Info, of course).

bug#2975: texinfo-master-menu and emacs.texi

[Štěpán Němec]

On Thu, Dec 08, 2011 at 09:37:29PM +0200, Eli Zaretskii wrote:
> > From: Štěpán Němec <stepnem@gmail.com>
> > Cc: Eli Zaretskii <eliz@gnu.org>,  2975@debbugs.gnu.org,  Karl Berry
> > <karl@freefriends.org>
> > Date: Thu, 08 Dec 2011 20:06:45 +0100
> >
> > (Personally I found Eli's explanation confusing -- what does
> > "on-line"
> > mean here? If it means HTML, makeinfo does support HTML output --
> > does
> > it mean it doesn't cope with missing node pointers in the HTML case?
>
> "On-line" means all on-line formats, including HTML.
>
> What do you mean by "it doesn't cope" -- who or what is "it" here?

makeinfo

> makeinfo does not need these pointers in the Texinfo sources to
> produce them in any of its outputs that are meant for on-line
> browsing.  That includes HTML (and Info, of course).

Thank you for the clarification. Wouldn't it be even clearer (and
simpler) to say that makeinfo just never needs those pointers? You
wrote:

  TeX doesn't need them.  These pointers are there to allow traversing
  the on-line manual, and are not needed for non on-line versions.

So, given that makeinfo can add the info itself when needed, is there
really ever any need for listing the node pointers explicitly at all?

--
Štěpán

bug#2975: texinfo-master-menu and emacs.texi

[Roland Winkler]

On Thu Dec 8 2011 Št pán N mec wrote:
> So, given that makeinfo can add the info itself when needed, is there
> really ever any need for listing the node pointers explicitly at all?

If Karl or whoever could answer this question with a clear "no, these
node pointers are never needed" (say, for recent versions of makeinfo
and other tools for formatting info pages) this could make things
much easier!

Roland

bug#2975: texinfo-master-menu and emacs.texi

[Eli Zaretskii]

> Date: Thu, 8 Dec 2011 14:54:55 -0600
> From: "Roland Winkler" <winkler@gnu.org>
> Cc: Eli Zaretskii <eliz@gnu.org>, 2975@debbugs.gnu.org, karl@freefriends.org
> 
> On Thu Dec 8 2011 Št pán N mec wrote:
> > So, given that makeinfo can add the info itself when needed, is there
> > really ever any need for listing the node pointers explicitly at all?
> 
> If Karl or whoever could answer this question with a clear "no, these
> node pointers are never needed" (say, for recent versions of makeinfo
> and other tools for formatting info pages) this could make things
> much easier!

I tried to explain that already, in my original mail: they are not
needed if you structure your Texinfo source according to the rules
described in "(texinfo)makeinfo Pointer Creation".

Most manuals should have no problems being structured like that (the
Emacs User Manual and Emacs Lisp Manual are actually structured
according to those rules), but some specialized uses of Texinfo cannot
be limited to tree-like structure, or don't want to use sectioning
commands (@chapter, @section, etc.) or menus, or want to order the
nodes in some special way that defeats the automatic generation of
node pointers.  For these, you must explicitly have the Next, Prev, Up
pointers in Texinfo.

bug#2975: texinfo-master-menu and emacs.texi

[Roland Winkler]

On Fri Dec 9 2011 Eli Zaretskii wrote:
> I tried to explain that already, in my original mail: they are not
> needed if you structure your Texinfo source according to the rules
> described in "(texinfo)makeinfo Pointer Creation".
> 
> Most manuals should have no problems being structured like that (the
> Emacs User Manual and Emacs Lisp Manual are actually structured
> according to those rules), but some specialized uses of Texinfo cannot
> be limited to tree-like structure, or don't want to use sectioning
> commands (@chapter, @section, etc.) or menus, or want to order the
> nodes in some special way that defeats the automatic generation of
> node pointers.  For these, you must explicitly have the Next, Prev, Up
> pointers in Texinfo.

OK, thanks a lot. For me, this is an important clarification.

Roland

bug#2975: texinfo-master-menu and emacs.texi

[Karl Berry]

    > So, given that makeinfo can add the info itself when needed, is there
    > really ever any need for listing the node pointers explicitly at all?

    If Karl or whoever could answer this question with a clear "no, these
    node pointers are never needed"

I believe Eli answered this, but to reiterate, it is only (very)
exceptional manuals which might need node pointers.

So if you're asking if texinfo-mode needs to keep supporting them, I
would say, definitely not.  In fact, I think it would be a good thing if
it didn't.  I have seen many authors have unnecessary problems due to
texinfo-mode inserting the node pointers.

k

bug#2975: texinfo-master-menu and emacs.texi

[Eli Zaretskii]

> Date: Fri, 9 Dec 2011 16:17:41 -0800
> From: karl@freefriends.org (Karl Berry)
> Cc: stepnem@gmail.com, eliz@gnu.org, 2975@debbugs.gnu.org
> 
>     > So, given that makeinfo can add the info itself when needed, is there
>     > really ever any need for listing the node pointers explicitly at all?
> 
>     If Karl or whoever could answer this question with a clear "no, these
>     node pointers are never needed"
> 
> I believe Eli answered this, but to reiterate, it is only (very)
> exceptional manuals which might need node pointers.
> 
> So if you're asking if texinfo-mode needs to keep supporting them, I
> would say, definitely not.  In fact, I think it would be a good thing if
> it didn't.  I have seen many authors have unnecessary problems due to
> texinfo-mode inserting the node pointers.

I updated the commentary and the doc strings of the relevant functions
in texnfo-upd.el to the effect that texinfo-update-node and the
commands that call it should only be used if one knows what they are
doing.  I also made texinfo-master-menu call texinfo-update-node only
if the prefix arg is numeric, because invoking texinfo-master-menu
with just C-u is still useful and much less problematic.

I decided not to remove the code that updates the @node lines
entirely, since texinfo-update-node could still be useful to experts
in very specialized use cases.

I also added to the doc strings of relevant commands a note about
non-support of multi-file Texinfo manuals, and a reference to
texinfo-multiple-files-update, which does.

I hope this makes the situation quite a bit better.

bug#2975: texinfo-master-menu and emacs.texi

[Eli Zaretskii]

> Date: Thu, 8 Dec 2011 20:59:57 +0100
> From: "Štěpán Němec" <stepnem@gmail.com>
> Cc: Štěpán Němec <stepnem@gmail.com>,
> 	winkler@gnu.org, 2975@debbugs.gnu.org, karl@freefriends.org
> 
> > makeinfo does not need these pointers in the Texinfo sources to
> > produce them in any of its outputs that are meant for on-line
> > browsing.  That includes HTML (and Info, of course).
> 
> Thank you for the clarification. Wouldn't it be even clearer (and
> simpler) to say that makeinfo just never needs those pointers?

It would, if it were true.  But it isn't, see my other mail.

bug#2975: texinfo-master-menu and emacs.texi

[Eli Zaretskii]

> Date: Thu, 8 Dec 2011 12:52:17 -0600
> From: "Roland Winkler" <winkler@gnu.org>
> Cc: Štěpán Němec <stepnem@gmail.com>,
>         2975@debbugs.gnu.org, karl@freefriends.org (Karl Berry)
> 
> On Thu Dec 8 2011 Eli Zaretskii wrote:
> > The simplest fix would be to remove the updating of the @node lines.
> > Would anyone object?  Karl?
> 
> A TeXnical question: what about using TeX to generate the output? 
> To the best of my knowledge makinfo doesn't care about @node lines
> being up to date or not, it can fix them itself. Does the same hold
> for TeX?

TeX ignores @node.