Re: HTML docs and Hyperlinks

[Bart Schaefer <schaefer@brasslantern.com>]

On Wed, Apr 20, 2022 at 12:41 PM Zach Riggle <zachriggle@gmail.com> wrote:
>
> Is there anybody who'd be willing to mentor me / provide 1-1 assistance for adding this functionality to the Yo templates / Yo arguments?

Links in the generated html are created with the noderef(target)
macro.  They're also automatically generated for menu(target) entries
and for the node headings introduced by
texinode(this)(next)(prev)(up).  The "target" in noderef or menu must
be a "this" from a texinode.  That is, "this" becomes the anchor name
for a fragment and noderef or menu creates a URI referencing that
fragment.  Similarly next/prev/up become URIs referencing the
corresponding fragments.

Fragments can also be created with the cindex [concepts index], findex
[functions index], kindex [styles/tags], pindex [options], tindex
[widgets], or vindex [variables] macros.  The URIs pointing to those
fragments are automatically created in the corresponding index
sections, but they're not reference-able elsewhere in the yodl source
documents.  It's possible they could be made explicitly linkable by
edits to Doc/zman.yo and Doc/ztexi.yo, but my TeX skills are 30 years
rusty (the HTML is generated by first creating texi and then
post-processing that).

How closely the fragment URIs get you to the content they're intended
to reference depends on where the writer chose to place the yodl
macros and on the versions of the tools that transform the yodl or
display the result.  For example, older versions of the "info" browser
would just jump to the top of the node and then forward-search for the
target text, which could take you to the wrong place if the target
text appeared elsewhere in the prose.

To echo Mikael's question, what do you anticipate to introduce that's
not covered by the above?

> Separately, would Zsh be willing to accept a post-processing step to the HTML documentation to add things post-hoc?  This will likely require some Python libraries being included in the process of building the docs.

We've used Perl for such post-processing so far (e.g.,
Util/helpfiles); I can't speak to whether python is now so ubiquitous
that creating a dependency on it would be a non-issue.