Re: [help-texinfo] Visible HTML anchors for options?

[David Malcolm]

On Fri, 2019-02-15 at 21:43 +0000, Gavin Smith wrote:
> On Thu, Feb 14, 2019 at 05:26:59PM -0500, David Malcolm wrote:
> > I'm a GCC developer; we use texinfo for our documentation.
> > 
> > GCC has a lot of options, so it's very useful to be able to provide
> > users with URLs to *specific* options in our documentation.
> > 
> > For a long time I didn't think texinfo's HTML generator provided
> > anchors for these, but using "View Source" shows it does.
> > 
> > For example, this .texi input:
> > 
> > @item address@hidden
> > @opindex flive-patching
> > Control GCC's optimizations to provide a safe compilation for live-
> > patching.
> > 
> > provides this HTML:
> > 
> > <dt><code>-flive-patching=<var>level</var></code></dt>
> > <dd><a name="index-flive-patching"></a>
> > <p>Control GCC&rsquo;s optimizations to provide a safe compilation
> > for
> > live-patching.
> > </p>
> > 
> > which can thus be accessed via this anchored URL:
> > 
> > https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-fliv
> > e-patching
> > 
> > 
> > Unfortunately, the anchor is invisible in the web page as there's
> > no
> > text within it.
> > 
> > I'm wondering if there's a way to make the anchors visible?  For
> > example, could the whole of the <dt> text become the anchor?
> > This would make it much easier to get the URL for just that option
> > (without having to use View Source and hunt for it).  Or am I
> > missing
> > something here?
> 
> I don't know what you mean by a "visible anchor".

>From an end-user perspective, I want the title of the option to be
visibly linkified in the browser, so that the user can right-click on
an option in the HTML docs and select "Copy Link Location" (and e.g.
paste it into IRC, bugreports, etc).

I think what I want is an <a> with an href on the title associated
with the item (here the <dt>), expressing a clickable link.  I hacked
up the attachment you sent, and something like this works:

<dd>
<span id="index-flive_002dpatching"></span>
</dd>
<dt><a 
href="#index-flive_002dpatching">-flive-patching=<var>level</var></a></dt>
<dd>
<p>Control GCC&rsquo;s optimizations to provide a safe compilation for live-
patching.
</p>
</dd>

...where the destination of the href anchor is the adjacent id span.  
With that, the title is visibly linkified in the browser in the way I'm
looking for.

Though it'd be much nicer if the URL were:

  SOME_PAGE.html#-flive-patching

or:

  SOME_PAGE.html#option-flive-patching

rather than

  SOME_PAGE.html#index-flive_002dpatching

(URLs are part of the UI).


For reference, sphinx (which I'm using for libgccjit, a component of
gcc) emits something like this:

<dt id="gcc_jit_context_acquire">
<a class="reference internal" href="#gcc_jit_context"
title="gcc_jit_context">gcc_jit_context</a> *<tt
class="descname">gcc_jit_context_acquire</tt><big>(</big>void<big>)</bi
g><a class="headerlink" href="#gcc_jit_context_acquire"
title="Permalink to this definition">¶</a></dt>
<dd><p>This function a

for e.g. 
https://gcc.gnu.org/onlinedocs/jit/topics/contexts.html#gcc_jit_context_acquire

with some CSS magic (I think) to make the pilcrow mark appear when
hovering over the item of interest.

> In the latest development version, 

[FWIW, gcc.gnu.org is currently building its docs using "GNU Texinfo
6.4.91"]

> the <a> tag is not used with
> the 'name' attribute to define the target of a hyperlink: the 'id'
> attribute is used instead, usually on a <span> element.  (There has
> been no good reason for this change other than the fact that the
> 'name'
> attribute has been removed in later HTML standards.)  This opens the
> possibly of using the 'id' attribute on another HTML element, e.g.
> <dt>
> as you mention, or <p>.  What part of the document exactly an index
> command is associated with is, however, a slightly murky area I find.
> 
> I found that putting the index command before the @item leads to the
> link target being output before the <dt> element, inside another
> <dd> element.  See attached files.  This doesn't make much sense,
> but does have the benefit that when the user follows the link in the
> index entry, the page will be scrolled to make the <dt> text visible.

The other thing to note is that the link ID's used for index entries
> are 
> not guaranteed to be consistent across Texinfo versions, unlike the
> ID's 
> used for nodes of a manual.

Thanks for the pointers and the examples, they're very helpful.

I'm going to keep experimenting to see if I can improve this with a
macro from the gcc side.


[...snip...]

Dave