Re: automatic generation of @menu entries

[Mike Frysinger]

On 13 Sep 2021 10:37, Patrice Dumas wrote:
> On Sun, Sep 12, 2021 at 03:09:30PM -0400, Mike Frysinger wrote:
> > based on the manual description, it sounds like the tree structure is
> > accessible already since that's how the @contents are generated, and
> > it's able to output that just fine.  so i (naively) assume that adding
> > an automatic menu would be comparable.
> 
> As I said in another mail, it is already the case, in Info output a menu
> is automatically added if there is none.  Also now, in the default case,
> in HTML output the sectioning commands are used for directions, not
> menus (default is 'sectiontoc' for FORMAT_MENU).
> 
> > > It would also mean the produced menu items will lack the short
> > > descriptions, which are produced by a human typing them in Texinfo.
> > 
> > right, that's why i suggested a new @menudesc to retain that part 
> 
> I do not think that it is very relevant to add a separate @-command for
> that.  My understanding of the @menu use-case is to allow to have
> a control on the formatting of the menu for the Info format, to have
> a menu that looks good in plain text, with control on spacing in
> particular.  Having a separate @menudesc command would be more in line
> with the semantic nature of the Texinfo language, but would see little
> use, as, my feeling is that descriptions are not really useful if not
> part of a menu.
> 
> > (if
> > the existing @unnumberedsec and such are insufficient).
> 
> Node names are used in menus, not sectioning commands names.  There is
> a TREE_TRANSFORMATIONS, insert_nodes_for_sectioning_commands, that uses
> sectioning commands to setup nodes automatically using sectioning
> commands names, but it is not the default setting.  With
> @xrefautomaticsectiontitle and other customization variables
> it is possible to use more section names, but in general it is not the
> default.

tbh, if @menu is only for info pages, i'm not super invested in them.  i only
use html & pdf sources personally.  i was just trying to DTRT, and the existing
GNU projects use them, and the texinfo manual says to define them.  if texinfo
generates stub ones for me, i'll just delete my curated ones and move on.

that said, i'll note that in my testing, @menu is being generated for chapter
nodes with sections, but it's not being generated for the Top node.  i tried:
$ makeinfo -I doc --no-split -I doc -I ../../../sim/doc -o doc/sim.info 
../../../sim/doc/sim.texi \
    -c 'TREE_TRANSFORMATIONS=complete_tree_nodes_menus,regenerate_master_menu'
-mike

signature.asc
Description: PGP signature