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

Gavin Smith Fri, 15 Feb 2019 14:05:44 -0800

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 -flive-patching=@var{level}
> @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-flive-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".

In the latest development version, 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.

test.texi
Description: TeXInfo document

Title: Untitled Document

1 Chapter One

more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more more

-flive-patching=level: Control GCC’s optimizations to provide a safe compilation for live- patching.

Appendix A Concept Index

Jump to:	F

	Index Entry	Section

F
	flive-patching:	One
	flive-patching2:	One

Jump to:	F

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

1 Chapter One

Appendix A Concept Index

Reply via email to