From: Bart Schaefer <firstname.lastname@example.org> To: Zach Riggle <email@example.com> Cc: Zsh Users <firstname.lastname@example.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 <email@example.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.
next prev 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: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * 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' \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --subject='Re: HTML docs and Hyperlinks' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * 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: https://git.vuxu.org/mirror/zsh/ 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).