Re: wishlist: implicit anchor for @deffn etc

[Per Bothner]

On 10/31/2017 01:18 PM, Eli Zaretskii wrote:
> > From: Gavin Smith <address@hidden>
> > Date: Tue, 31 Oct 2017 19:59:13 +0000
> > Cc: Texinfo <address@hidden>
> >
> > 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?
>
> IMO, if we are going to have such a feature, it should be a new
> command, like @defunidx or somesuch.

How about @dref ?

> It makes little sense to produce
> gobs of anchors in manuals that don't have any uses for them.  The
> @def commands produce index entries,

Which are basically implicit anchors, anyway ...

> and the usual way to find them
> quickly is to type "i FUNCTION" in the Info reader, which is almost as
> fast as following an explicit cross-reference.

Fast but unreliable.  In HTML the marking (usually underline) for
a link makes it clear that it *is* a link, and selecting it will
take you to the correct place, rather than just one with the same name.

> > > 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?
>
> Using a colon is not a good idea, IMO: the Texinfo manual explicitly
> warns against using it in node names, for similar reasons.

I don't see a warning about colons in the 'Choosing Node Names'.

Regardless, if we introduce a new command like @dref then colons would
only appear there.  But perhaps we don't even need colons - spaces will do:

  @dref{Procedure sqrt}

or (when unambiguous):

  @dref{sqrt}

An info format reader should ideally display such a link as plain NAME but with 
some special
color or style to mark it as a link, but otherwise not clutter up the display.  
If that is too
difficult, one just output plain NAME without any decoration.
--
        --Per Bothner
address@hidden   http://per.bothner.com/