Re: Cross-reference format in man pages

On 8/7/2026 10:44, Mikael Magnusson wrote:
> On Sun, Jul 13, 2025 at 5:30 PM Jun. T <[email protected]> wrote:
>> Patch is attached as a file (since it's rather long).
>>
>>> 2025/07/04 13:48, Jun T <[email protected] <mailto:[email protected]>> wrote:
>>>
>>>     See the section `Filename Generation'
>>> but the section is in zshexpn(1).
>> In addition to fixing the missing man page name, various minor
>> fixes (and improvements, hopefully) are included
>> (using more specific referent, etc.).
>>
>>> Since section names in man pages are in bold ALLCAPS, I
>>> will (try to) use
>>> bf(FILENAME GENERATION)
>>> when referring to the section names. Is this OK?
>>> (I will define a new macro for this)
>> Four new yodl macros are defined.
>>
>>    nmref(node)(manpage) is for referring to texi node or manpage
>>    (depending on ifnzman or ifzman).
>>
>>    sectref(sectname)(manpage) is for referring to a section in
>>    manpage, or a texi node. There should be a texi node (or anchor)
>>    with the same name as the 'sectname'.
>>    Use anchor() for creating the anchor.
>>
>>    subref(subsectname)(manpage) is similar but for a subsection.
>>
>> I also patched Util/zyodl.vim to recognize the 4 new macros.
> Happened to notice this,
>
> @@ -373,7 +371,7 @@ Define a function which is referenced by any one
> of var(word).
>   Normally, only one var(word) is provided; multiple var(word)s
>   are usually only useful for setting traps.
>   The body of the function is the var(list) between
> -the tt({) and tt(}).  See noderef(Functions).
> +the tt({) and tt(}).  See sectref(Functions)(blow).
>
>   The options of tt(function) have the following meanings:
>
> Which results in this manpage output:
>                where term is one or more newline or ;.  Define a
> function  which  is  refer‐
>                enced  by  any  one  of  word.  Normally, only one word
> is provided; multiple
>                words are usually only useful for setting traps.  The
> body of the function is
>                the list between the { and }.  See FUNCTIONS in blow(1).
>
> I assume this is an error, since we do not provide a blow.1? But I'm
> not sure what you meant for it to say.
>
Also as I mentioned a few days ago when I sent a sample, I'm working on 
a project to move off the dead-end mostly self-supported YODL to the 
well-supported but admittedly ugly rST using sphinx, a very popular 
documentation set up with a wide community and strong support.