Re: wishlist: implicit anchor for @deffn etc

[Gavin Smith]

On 30 October 2017 at 20:57, Per Bothner <address@hidden> wrote:
> Two related problems:
> (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':
>
> @example
> (@ref{Procedure:sqrt) 4) ==> 2
> @end example
>
> would generate something like:
>
> <pre>
> (<a href="#Procedure:sqrt">sqrt</a> 4) ==> 2
> </pre>
>
> (Yes, a ':' is valid in a URL fragment.)
>

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?

The main downside that comes to mind is that it is adding bloat to all
output formats with targets (e.g. HTML, Info).

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.


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

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.