zsh-users
 help / color / mirror / code / Atom feed
* HTML docs and Hyperlinks
@ 2022-04-20 19:40 Zach Riggle
  2022-04-20 20:51 ` Ray Andrews
                   ` (2 more replies)
  0 siblings, 3 replies; 6+ messages in thread
From: Zach Riggle @ 2022-04-20 19:40 UTC (permalink / raw)
  To: Zsh Users

[-- Attachment #1: Type: text/plain, Size: 639 bytes --]

Hey all!

I'm working on some scripts to add hyperlinks (URI fragments) to the HTML
generated documentation to make it easier to link to various parts in the
Zsh documentation.

I'm not familiar with Yo for generating docs, but it seems that would be
the "ideal" way.

Is there anybody who'd be willing to mentor me / provide 1-1 assistance for
adding this functionality to the Yo templates / Yo arguments?

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.

*Zach Riggle*

[-- Attachment #2: Type: text/html, Size: 961 bytes --]

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: HTML docs and Hyperlinks
  2022-04-20 19:40 HTML docs and Hyperlinks Zach Riggle
@ 2022-04-20 20:51 ` Ray Andrews
  2022-04-20 21:05 ` Mikael Magnusson
  2022-04-20 22:42 ` Bart Schaefer
  2 siblings, 0 replies; 6+ messages in thread
From: Ray Andrews @ 2022-04-20 20:51 UTC (permalink / raw)
  To: zsh-users

On 2022-04-20 12:40, Zach Riggle wrote:
> Hey all!
>
> I'm working on some scripts to add hyperlinks (URI fragments) to the 
> HTML generated documentation to make it easier to link to various 
> parts in the Zsh documentation.

Thanks for the spirit there Zach.  I can't do anything myself but I sure 
hope that goes forward.



^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: HTML docs and Hyperlinks
  2022-04-20 19:40 HTML docs and Hyperlinks Zach Riggle
  2022-04-20 20:51 ` Ray Andrews
@ 2022-04-20 21:05 ` Mikael Magnusson
  2022-04-20 22:42 ` Bart Schaefer
  2 siblings, 0 replies; 6+ messages in thread
From: Mikael Magnusson @ 2022-04-20 21:05 UTC (permalink / raw)
  To: Zach Riggle; +Cc: Zsh Users

On 4/20/22, Zach Riggle <zachriggle@gmail.com> wrote:
> Hey all!
>
> I'm working on some scripts to add hyperlinks (URI fragments) to the HTML
> generated documentation to make it easier to link to various parts in the
> Zsh documentation.
>
> I'm not familiar with Yo for generating docs, but it seems that would be
> the "ideal" way.

What do you want to do, more concretely? References in the
documentation source are already hyperlinked in the generated HTML. If
you want to add a reference somewhere, just send a patch for that.

-- 
Mikael Magnusson


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: HTML docs and Hyperlinks
  2022-04-20 19:40 HTML docs and Hyperlinks Zach Riggle
  2022-04-20 20:51 ` Ray Andrews
  2022-04-20 21:05 ` Mikael Magnusson
@ 2022-04-20 22:42 ` Bart Schaefer
  2022-04-21  0:31   ` Lawrence Velázquez
  2 siblings, 1 reply; 6+ messages in thread
From: Bart Schaefer @ 2022-04-20 22:42 UTC (permalink / raw)
  To: Zach Riggle; +Cc: Zsh Users

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.


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: HTML docs and Hyperlinks
  2022-04-20 22:42 ` Bart Schaefer
@ 2022-04-21  0:31   ` Lawrence Velázquez
  2022-04-21 11:38     ` Peter Stephenson
  0 siblings, 1 reply; 6+ messages in thread
From: Lawrence Velázquez @ 2022-04-21  0:31 UTC (permalink / raw)
  To: zsh-users

On Wed, Apr 20, 2022, at 6:42 PM, Bart Schaefer wrote:
> On Wed, Apr 20, 2022 at 12:41 PM Zach Riggle <zachriggle@gmail.com> wrote:
>> 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.

I would rather not introduce another dependency if it can be avoided.

-- 
vq


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: HTML docs and Hyperlinks
  2022-04-21  0:31   ` Lawrence Velázquez
@ 2022-04-21 11:38     ` Peter Stephenson
  0 siblings, 0 replies; 6+ messages in thread
From: Peter Stephenson @ 2022-04-21 11:38 UTC (permalink / raw)
  To: Lawrence Velázquez, zsh-users

> On 21 April 2022 at 01:31 Lawrence Velázquez <larryv@zsh.org> wrote:
> On Wed, Apr 20, 2022, at 6:42 PM, Bart Schaefer wrote:
> > On Wed, Apr 20, 2022 at 12:41 PM Zach Riggle <zachriggle@gmail.com> wrote:
> >> 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.
> 
> I would rather not introduce another dependency if it can be avoided.

I agree, this would at the least be another version management headache
we could well do without.

Adding a few simple fix-ups should be doable without external dependencies.

pws


^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2022-04-21 11:39 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-04-20 19:40 HTML docs and Hyperlinks Zach Riggle
2022-04-20 20:51 ` Ray Andrews
2022-04-20 21:05 ` Mikael Magnusson
2022-04-20 22:42 ` Bart Schaefer
2022-04-21  0:31   ` Lawrence Velázquez
2022-04-21 11:38     ` Peter Stephenson

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).