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

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

[dana]

(This belongs in workers now, yeah?)

On 16 Sep 2018, at 17:56, Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
>I don't understand the last sentence?

I haven't bothered to look at the actual source (and don't know it well from
memory yet), but just from the end result, it seems that it's set up so that if
a chapter has no sub-sections (like 'Command Execution') or if it has some
introductory text before the sub-sections (like 'Functions'), the top-level
heading is preserved. For chapters like 'Jobs & Signals', where the first bit of
content is a sub-heading, that top-level heading goes away, so as not to have
two consecutive headings.

On 16 Sep 2018, at 17:56, Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
>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.

For cases like the 'Shell Grammar' reference you found, it seems like there are
basically two kinds of options: Either change the reference to point to a
specific section instead of a whole chapter, or change the structure of the
pages to include the chapter heading. Assuming that's true, only the latter is
appropriate here, right?

I'm probably speaking out of turn, though, tbh; i know way less about how this
works than you.

dana

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

[Daniel Shahaf]

dana wrote on Sun, 16 Sep 2018 18:33 -0500:
> (This belongs in workers now, yeah?)
> 

Sure.

> On 16 Sep 2018, at 17:56, Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
> >I don't understand the last sentence?
> 
> I haven't bothered to look at the actual source (and don't know it well from
> memory yet), but just from the end result, it seems that it's set up so that if
> a chapter has no sub-sections (like 'Command Execution') or if it has some
> introductory text before the sub-sections (like 'Functions'), the top-level
> heading is preserved. For chapters like 'Jobs & Signals', where the first bit of
> content is a sub-heading, that top-level heading goes away, so as not to have
> two consecutive headings.
> 

Ah, I see.  So you're saying there's some method to the madness by which
it's decided which chapter() directives do, or do not, appear in the man page.

Furthermore, chapter() headings ("9. Functions") and sect() headings
("9.1 Autoloading Functions") are rendered the same way in the man page.
It would be nice to fix this.

> On 16 Sep 2018, at 17:56, Daniel Shahaf <d.s@daniel.shahaf.name> wrote:
> >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.
> 
> For cases like the 'Shell Grammar' reference you found, it seems like there are
> basically two kinds of options: Either change the reference to point to a
> specific section instead of a whole chapter, or change the structure of the
> pages to include the chapter heading. Assuming that's true, only the latter is
> appropriate here, right?
> 

Actually, if you look at the source, you'll find that all these
references are done separately for the man page output and for the
texinfo output.  This instance is typical; it looks like this:
.
    General shell syntax is introduced in ifzman(the section `Shell Grammar' in
    zmanref(zshmisc))\
    ifnzman(noderef(Shell Grammar)).
.
Therefore, we can easily change the text for the man page output only,
as a low-hanging fruit / hotfix.

> I'm probably speaking out of turn, though, tbh; i know way less about how this
> works than you.

I don't think you are.  What I know about yodl and the manual could fit
in a very small number of bytes.

Cheers,

Daniel