Re: wishlist: implicit anchor for @deffn etc

[Per Bothner]

On 10/31/2017 12:59 PM, Gavin Smith wrote:
> On 30 October 2017 at 20:57, Per Bothner <address@hidden> wrote:

> > (1) It would be convenient to be able to easily reference a definition
> > without having to explicitly create an @anchor.  For example:
> >
> > @deffn Procedure sqrt @var{z}
> > @end deffn
> >
> > The '@deffn Procedure sqrt' implicitly defines an '@anchor Procedure:sqrt':

> Do you think it should be generated for all index entries or just for
> index entries from @def* commands? What would be the benefit of only
> doing it for @def* commands?

I've only considered it for @def*, but it is worth considering for other
index entries that aren't nodes.  I'm focusing on @def* because that's
the biggest chunk of entries - plus they're useful for (1) above.

FWIW Sphinx has the functionality of (1) - see:

  http://www.sphinx-doc.org/en/stable/domains.html#basic-markup

specifically the example:

  The function :py:func:`spam` does a similar thing.

The Racket documentation has extensive links from examples to
procedure definitions, so I assume Scribble has something similar.

Being able to more conveniently link to definitions in examples
or discursive text would be very nice.

> It is not obviously wrong, but it has always been the case with
> Texinfo that an index entry and a node/anchor are different things. I
> feel that any changes in this area should be approached with caution.
> The two have different name spaces and act differently in many ways.

Maybe a new command @dref{DEF-NAME,ONLINE-LABEL} where ONLINE-LABEL
is optional and defaults to NAME (or possible @code{NAME} ?)
The category could be optional if it is unique, so you could write either
  @dref{Procedure:sqrt}
or
  @dref{sqrt}
as long as the latter is unambiguous.

> > (2) The index has an entry to a link to the @deffn for sqrt.  Texinfo has
> > to generate a unique identifier and use that.  This has two problems:
> > It makes for ugly URLs.  Worse, it makes for non-stable URLs: when you
> > change
> > the manual, you get a new set of generated link identifiers.  (This also
> > makes
> > diff of html output much more difficult.)
>
> As you point out there is already an HTML anchor generated for index
> entries. Would one possibility be to change whatever this anchor is so
> that the URL is not so ugly? This would be a change for HTML only,
> leaving other output formats unchanged.

A clarification: I didn't realize that the html backend already does generate
somewhat stable and semi-readable links.  (I missed that because I normally
first convert to DocBook.)

So the functionality in terms of generated links is already there.
However, I suggest (for HTML output) changing the encoding to use the standard 
percent-encoding
as in the encodeURIComponent encoding:

  
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent

Browsers and other tools already understand percent encoding.

> I can see that there could be a benefit to having a stable link to a
> definition in a manual.
>
> > The exact form of these generated anchors is open.  I like the form
> > CATEGORY:NAME as it's relatively readable and easy to type; unlikely to
> > clash
> > with other node names or anchors; and does not clash with other definitions
> > of the same NAME but different CATEGORY.
>
> That seems like valid reasoning to me. Does anyone else have any suggestions?
>
> Then again, in some manuals the CATEGORY might not be necessary if
> there are not other index entries, nodes or anchors with the same
> name.
>
> > We need a convention for duplicate definitions.  For example:
> >
> > @deffn Procedure foo x
> > @end deffn
> >
> > @deffn Procedure foo a b c
> > @end deffn
> >
> > I suggest using sequence numbers in this case.  Maybe
> > @ref{Procedure:foo:1} and @ref{Procedure:foo:2}.
>
> This is not stable because if another definition of foo is given or
> the definitions are re-ordered, the numbering may change.

No, but it seems good enough.  Multiple definitions of foo with the same
category are probably rare, and even rarer that you'd re-order them.

--
        --Per Bothner
address@hidden   http://per.bothner.com/