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

[Eli Zaretskii <eliz@gnu.org>]

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