help / color / mirror / code / Atom feed
From: Bart Schaefer <schaefer@brasslantern.com>
To: Zach Riggle <zachriggle@gmail.com>
Cc: Zsh Users <zsh-users@zsh.org>
Subject: Re: HTML docs and Hyperlinks
Date: Wed, 20 Apr 2022 15:42:15 -0700	[thread overview]
Message-ID: <CAH+w=7bk1+9cpAAVKrhbbhm7VCXQdG87ouJ+JWsadAO7Uc+0FQ@mail.gmail.com> (raw)
In-Reply-To: <CAMP9c5mZ7nHRNf7NHMbH7UhQ9fTo5wtofgMEjPwTw4Nr+ysM_A@mail.gmail.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.

  parent reply	other threads:[~2022-04-20 22:43 UTC|newest]

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-04-20 19:40 Zach Riggle
2022-04-20 20:51 ` Ray Andrews
2022-04-20 21:05 ` Mikael Magnusson
2022-04-20 22:42 ` Bart Schaefer [this message]
2022-04-21  0:31   ` Lawrence Velázquez
2022-04-21 11:38     ` Peter Stephenson

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to='CAH+w=7bk1+9cpAAVKrhbbhm7VCXQdG87ouJ+JWsadAO7Uc+0FQ@mail.gmail.com' \
    --to=schaefer@brasslantern.com \
    --cc=zachriggle@gmail.com \
    --cc=zsh-users@zsh.org \
    --subject='Re: HTML docs and Hyperlinks' \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:


This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).