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
[email protected] http://per.bothner.com/
