Re: wishlist: implicit anchor for @deffn etc

[Per Bothner]

On 11/01/2017 12:30 PM, Eli Zaretskii wrote:
> > Cc: address@hidden
> > From: Per Bothner <address@hidden>
> > Date: Tue, 31 Oct 2017 21:46:10 -0700
> >
> > > > How about @dref ?
> > >
> > > I'm not good with names, but @dref sounds like a command from the *ref
> > > family (@xref, @pxref, etc.), which it isn't.
> >
> > Yes and no. Like @uref and the *ref family, it is a link (reference) to
> > another location.  I.e. a reference to a definition.
> >
> > So @dref works quite well.
>
> Perhaps there's a misunderstanding.  I was talking about a command
> which would _establish_ an anchor, and be used instead of @defun.
> @dref is a fine name for a command that _goes_ to that anchor, which
> should be placed where you want a link to where the function was
> described, and where the command I was talking about was supposed to
> be used.

I don't see any need to add new @defun commands. Doing so would add
extra complication to an already complicated family of commands.

Instead I propose a @dref command:

  @dref{[CATEGORY] NAME [NUMBER][,ONLINE LABEL]}

The default for ONLINE LABEL is NAME.
NUMBER may be omitted if it is unambiguous.
CATEGORY may be omitted if it is unambiguous and NUMBER is omitted.

This displays as ONLINE LABEL and acts like a cross references to the
NUMBER'th @defxxx for the given CATEGORY and NAME.  It uses the same
"hidden" anchor as the index uses.

> > Furthermore, there is familiarity of links:  Even if the 'i' keystroke is 
> > implemented
> > in a webpage (using JavaScript) it is useful to have an actual link to the 
> > definition,
> > because everybody knows what a link is, and most people may not know the 'i' 
> > shortcut.
>
> Users of Info should know.

"Should" is meaningless.  People "should" be using texinfo for their technical
documentation - but they don't (and won't as long as we keep focusing on info).

I use info but I am not fluent in many of its commands and features. (Same with 
lots of
other tools I use.)  I have not been in the habit of using the 'i' command
(though I will probably use it more in the future now that it has brought to my 
attention).
--
        --Per Bothner
address@hidden   http://per.bothner.com/