Re: Dangling reference in zshroadmap(1) (was: Re: test for newline in a variable--unexpected results sometimes)

[Daniel Shahaf <d.s@daniel.shahaf.name>]

dana wrote on Sun, 16 Sep 2018 17:16 -0500:
> I guess it's designed with the sections that get separate pages (like
> 'Parameters') in mind? The top-level heading seems to be omitted if the first
> immediate descendant is a sub-section.

I don't understand the last sentence?

> The same is true of other sections like 'Invocation', 'Files', and 'Jobs & Signals'.
> 
> Confusingly, the first two sections mentioned above each contain a sub-section
> with the same name, so the exact part of the documentation being referred to is
> unclear/inconsistent.

On the other hand, redirect.yo explicitly adds a sect() in man page format
only.  The net effect is that the heading "Redirection" is shown as a
chapter heading in html/pdf but as a section heading in man.

> (In the man pages, the top-level headings are missing,

That's because zman.yo defines chapter() to expand to nothing.

> so that leaves only the sub-headings. But in the HTML version, the
> links take you to the top of the entire section.)
> 

Yes, the texinode() directives are placed on the chapter(), not on the
sect() with the same name.

The mapping between chapter() nodes and man pages is not one to one;
there are more chapters than man pages.

> Not sure how to address that

What end result would we like to achieve?  Once we nail that down we can
think how to implement it.

At least, we could grep for any instances of ifnzman(see the section
`foo'...) where `foo' is a texinode() of a chapter(), and fix them.

Or we could hack at the yodl to reduce the differences between the
various output formats.

There are probably other options 

Daniel