Re: control over sectioning and splitting

[Gavin Smith]

On Wed, Jul 26, 2023 at 02:55:20PM +0200, Patrice Dumas wrote:
> Hello,
> 
> Resuscitating an old thread as I tried to progress on the issue.

I hadn't had a clear idea of how to resolve this issue and wasn't
even confident that a resolution was possible.  I don't know if
I can give the issue the attention it deserves, but here's my
response and hopefully it does not add more confusion.

> On Fri, Jan 28, 2022 at 05:39:04PM +0100, Patrice Dumas wrote:
> > On Sun, Jan 23, 2022 at 10:20:03AM -0800, Per Bothner wrote:
> > > 
> > > On 1/22/22 02:07, Gavin Smith wrote:
> > > > @chapter or @section without @node would become a lot like
> > > > @heading except perhaps there could also be an @anchor generated
> > > > for the chapter heading as well as appearing in the table of
> > > > contents.  There would have to be a check that the name of the
> > > > automatic @anchor didn't clash with any other @node or @anchor.
> > > 
> > > If the @section/whatever is immediately preceded by an @anchor,
> > > one can use the explicit anchor instead.  In a sense the @anchor
> > > functions like the @missing node command, except in terms of splitting.
> > 
> > I see that indeed, there is currently no good way to associate a
> > sectionning command with an anchor preceding it such that links appear
> > before the heading and not after, and still be considered to be with
> > this sectioning command and not the previous one.  Yet, I do not think
> > that associating an @anchor to the next sectioning command is correct to
> > do in every situations, as the @anchor could really be meant to be at
> > the end of the preceding section.

I agree that it might be difficult to do an @anchor association with
a following @section correctly.  It would be less straightforward
to parse as the association of @anchor would depend on what came
after it.  However, it might be a clean way (for document authors)
to give a way to link to the @section if it doesn't have a @node.

> I tried to progress on that issue, not by tweaking anchors associated to
> @*heading but starting to work on nodes association with the following
> @*heading command.

If I understand correctly, this is using @heading instead of @section, but
with a @node line.  One difference is that @heading would not put an
entry in the table of contents.  If you look at Per's original message, then
he wanted the entries in the table of contents.

With the following input:

>>>>>
\input texinfo

@node Top
@top

Test manual.

@contents

@node Frontends including browsers
@chapter Frontends including browsers

A frontend is a program that handles the user interface.

@node Copy and paste
@heading Copy and paste

Paste should work on all front-ends if domterm makes use of libclipboard.

@node Electron
@subheading Electron

Start the Electron frontend (if available) with the --electron option.

@bye
>>>>>

and then running 'texi2any test.texi --html', there are
files 'Electron.html' and 'Copy-and-paste.html' created that are not
linked to from anywhere.  The contents are only linked with
'texi2any test.texi --html -c USE_NODES=0'.

> There are still at least two issues for this to correspond to Per
> use cas (if I understood well, feel free to correct me).
> 
> First, there are, with USE_NODES=1, navigation panels for each of the
> nodes.  They are mostly empty for lone nodes without explicit
> directions, but not completly empty.  Are thses navigation panels
> wanted?  Should there be a specific way to remove them, or are the
> existing ways ok?

I'm confused as I thought the whole point was to use USE_NODES=0 to
split the manual at the @chapter level.  The "Copy and paste" and
"Electron" sections should all be in the same file.

Navigation heading appear with --no-split, but I don't think they are
going to be ok.

> Second, there is no <div> set up to include the content associated to
> the @node.  Is it an issue?

I don't have an opinion on this.