On Mon, Sep 28, 2026 at 12:22:02PM +0300, Eli Zaretskii wrote: > > Date: Mon, 28 Sep 2026 10:39:36 +0200 > > From: [email protected] > > Cc: Gavin Smith <[email protected]>, [email protected] > > > > On Mon, Sep 28, 2026 at 08:13:31AM +0300, Eli Zaretskii wrote: > > > What about the @detailmenu used by large manuals? E.g., Emacs uses it > > > in 2 of its manuals. This menu includes all the nodes from the entire > > > manual, but the automatically-generated nodes will be absent from > > > there, won't they? > > > > No, they will be present, the addition of nodes for sectioning commands > > is done before the automatic generation of menu and detailmenu. > > I'm talking about the cases where @detailmenu is maintained by hand. > This is the case with the Emacs manuals.
Indeed, in that case they will be absent, but I doubt that there are sectioning commands not already associated to nodes in the Emacs manuals. If there are, it is probably by choice, such that the addition of nodes is not wanted, in addition to the detailmenu issue. I think that unwanted added nodes is the main situation that is likely to happen. For that, there should be a customization variable added to prevent added nodes, which can be set in that case. It should be somewhat backward compatible, as an unknown customization variable leads to a warning for Texinfo > 5.0, which can be annoying but is not fatal. I am not sure about older releases. If the user wants to have nodes added for sectioning command, and also manually generates the @detailmenu, it should be ok (according to my testing). > > > There's also the issue of stuff that can appear in section names, but > > > is not recommended for node names (colons, Texinfo commands, etc.). > > > > What needs to be protected in the Texinfo code is protected (comma, > > leading parenthesis, colons...), and in the generated Info, the node > > name is also quoted if needed. Texinfo commands are fine in node names. > > _Any_ commands, including macros and suchlikes, which completely > change the underlying text? How do you check indexing and menu > consistency in such situations? The user-defined macros or values expansion is done even before, when parsing the Texinfo manual to an internal tree. Nodes are added afterwards and Indexing and menu consistency is done even after. > > > More generally, I don't understand why it would be a good idea to make > > > this the default. It is a useful feature, but why make it the > > > default? Is the intent to invite authors of the Texinfo manuals not > > > to name the nodes? > > > > Exactly. In the long term, it would be easier for documentation writers > > if node names are optional. > > But the node names are important, they are shown by the Info readers. > So the authors are well advised to think about the node names. For > example, they should be short enough to make them easy to type and > read in a menu, and so that they can be nicely displayed in the > "bread-crumbs" display at the top of the current node. It would still be possible to give node names, but it would only be needed if the node name is different from the section name. -- Pat
