On Tue, Oct 13, 2026 at 10:18:09PM +0200, Patrice Dumas wrote: > On Tue, Oct 13, 2026 at 08:52:08PM +0100, Gavin Smith wrote: > > I've done some work on this but I have a lot more to do on this as it will > > likely involve reviewing several different parts of the documentation. > > It is a big change, but I think that it would be better if the manual was > reorganized as the following: > > Have "Chapter Structuring" before "Nodes"
Is the thinking to have the more familiar concept described to users first as those familiar with other markup languages (e.g. HTML, Markdown) will easily grasp the idea of a sectioning(*) command? It would also be supporting users to write files without using the @node command which may be a common use case. (*) I'm never sure if we prefer the name "sectioning" or "chapter structuring". The manual calls them "chapter structuring" commands when first introduced but we also call them "sectioning" commands elsewhere, and to me that seems to be a more understandable name. In the "Nodes" chapter, the "Texinfo Document Structure" node refers to the "sectioning structure", even though we haven't had the chapter on sectioning commands yet, so it may provide a better flow of information to have the chapter on sectioning commands first. I'll try making some rearrangements according to your suggestions. There is quite a lot of information in both chapters so we should proceed carefully to avoid making a mess. > > In "Chapter Structuring": > * explain nodes as a refinement in the default case, for > - better names for Info > - disambiguated cross-references > * explain how to get menus automatically by reusing the "Node Descriptions" > section > > Reorganize the "Nodes" chapter > * remove or move to the end of the chapter all that is related to > the hierarchical structure, like "Texinfo Document Structure" or most > of what is in the "Menus" part. Instead, describe Nodes and Menus > use in term of what can be done differently from hierarchically > structured documents (giving different directions than given by > sectioning commands, both on node line and in menus, referring to > other Info files, using @node as a delimiter where multiple sectioning > command can be...). > * move "Unstructured Nodes" sections to "Nodes" as part of the > preceding point > > I could work on that, but only if it seems to be a good idea, and a > good idea for this release. > > -- > Pat
