[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: wishlist: implicit anchor for @deffn etc
From: |
Eli Zaretskii |
Subject: |
Re: wishlist: implicit anchor for @deffn etc |
Date: |
Wed, 01 Nov 2017 22:27:02 +0200 |
> Cc: address@hidden
> From: Per Bothner <address@hidden>
> Date: Wed, 1 Nov 2017 13:07:10 -0700
>
> > 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.
That's unlike any other command in Texinfo, and confusingly so. Using
NUMBER is IMO a problem, because (1) the author need to count them,
and (2) it needs to be updated when text changes.
I thought more along the lines of @ftable and its relation to @table.
IOW, introduce a new command that does the same as @defun and also
produces an anchor that could then be referenced via @xref and
friends.
> > 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).
The GNU project uses Texinfo all the time, and our users use the Info
manuals produced from that.
> 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).
The index-search is a very central feature in Info; people who don't
know about it or don't use it much don't know what they are losing,
IMO.