wishlist: implicit anchor for @deffn etc

[Per Bothner]

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

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

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.

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}.
--
        --Per Bothner
address@hidden   http://per.bothner.com/