Re: Info about how to write links in doc string

[Eli Zaretskii]

> Date: Fri, 04 May 2007 15:41:51 +0200
> From: "Lennart Borgman (gmail)" <address@hidden>
> CC:  address@hidden
> 
> Eli Zaretskii wrote:
> >     (@code{describe-variable}) to view the documentation string.  There
> >     are many other conventions for doc strings; see @ref{Documentation
> >     Tips}.
> > 
> > IMO, this can hardly be regarded as ``hidden information''.
> 
> 
> I would not look for how to write links under something labeled with 
> "other conventions".

Are you talking about the situation where someone looks specifically
for the information about how to write links?  If so, the index entry
I just added should solve that: just type "i hyperlink RET", and you
are there.

If, by contrast, you are talking about someone who studies the doc
string facility for the first time, then that person will bump into
the cross-reference to "Documentation Tips", and I expect them to go
there, since the text is quite inviting.

> The way you write links is a way to use a functionality, not a
> convention.

It is a convention because you don't _have_ to use links, it's just a
nicety that makes documentation better.

The Tips section describes a lot of other similar functionalities,
such as \\[foo], \\<bar>, the fact that arguments should be written in
UPPER case, the fact that opening parens should be escaped, etc.  It
doesn't make sense to move only the links stuff to the other section;
either we move most of the rest, or we don't move anything at all.