[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: `texinfo-master-menu' doesn't work.
From: |
Alan Mackenzie |
Subject: |
Re: `texinfo-master-menu' doesn't work. |
Date: |
Sun, 11 Dec 2011 17:38:59 +0000 |
User-agent: |
Mutt/1.5.21 (2010-09-15) |
Hello, Eli!
On Sat, Dec 10, 2011 at 02:40:39PM +0200, Eli Zaretskii wrote:
> > Date: Sun, 12 Apr 2009 21:33:40 +0000
> > From: Alan Mackenzie <address@hidden>
> > 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.
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.
@dfn{master menu} is on page "Master Menu Parts" in the Texinfo manual.
In particular,
A master menu is enclosed in address@hidden' and address@hidden menu'
commands ...
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?
> > 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.
> 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 think there's a mismatch between the command and its doc string. The
doc string says "make a master menu", not merely the insides of one.
> 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
OK.
> > 3.
[ .... ]
> > 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.
Ah. My understanding of that was a strict "includes", as distinct from a
"consists of". The first part of the master menu remains uncreated.
> 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.
> All of the above changes are in revision 106651 on the trunk.
I've got that.
> I'm closing this bug report.
Hmmm. I'm not entirely happy about that.
I can't help feeling that there's some specific word or phrase which I've
misunderstood, and this isn't clear to either of us. In the mean time,
C-c C-u m, without a prefix, seems to me to be a command of limited
utility.
> Sorry for the long delay in handling it.
No problem!
--
Alan Mackenzie (Nuremberg, Germany).