Info about how to write links in doc string

Info about how to write links in doc string

[Lennart Borgman (gmail)]

Information about how to write links in doc strings is kind of hidden. 
It is not found under

   (info "(elisp) Documentation")

which is where I think most programmers would look for it. Instead it is 
found under

   (info "(elisp) Documentation Tips")

I think at least mentioning this after the link from 1 above to 2 above 
would be good.

Re: Info about how to write links in doc string

[Richard Stallman]

Thanks.

Re: Info about how to write links in doc string

[Eli Zaretskii]

> Date: Tue, 01 May 2007 23:35:01 +0200
> From: "Lennart Borgman (gmail)" <lennart.borgman@gmail.com>
> 
> Information about how to write links in doc strings is kind of hidden. 
> It is not found under
> 
>    (info "(elisp) Documentation")
> 
> which is where I think most programmers would look for it. Instead it is 
> found under
> 
>    (info "(elisp) Documentation Tips")
> 
> I think at least mentioning this after the link from 1 above to 2 above 
> would be good.

Thanks for the suggestion, but I decided not to change the manual.
This is because there's a direct cross-reference from "Documentation"
to "Documentation Tips" right near the beginning of the former:

      A documentation string is written using the Lisp syntax for strings,
    with double-quote characters surrounding the text of the string.  This
    is because it really is a Lisp string object.  The string serves as
    documentation when it is written in the proper place in the definition
    of a function or variable.  In a function definition, the documentation
    string follows the argument list.  In a variable definition, the
    documentation string follows the initial value of the variable.

      When you write a documentation string, make the first line a
    complete sentence (or two complete sentences) since some commands,
    such as @code{apropos}, show only the first line of a multi-line
    documentation string.  Also, you should not indent the second line of
    a documentation string, if it has one, because that looks odd when you
    use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v}
    (@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 did reorder the items in the "Documentation Tips" section to put the
more important ones first.  That included the item that described the
hyperlinks: it doesn't make sense to me to make that the last tip.

I also added an index entry for the hyperlinks in doc strings, so now
this material can be easily found no matter where it is.

Thanks again for pointing this out.

Re: Info about how to write links in doc string

[Lennart Borgman (gmail)]

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". The way you write links is a way to use a 
functionality, not a convention.

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)" <lennart.borgman@gmail.com>
> CC:  emacs-devel@gnu.org
> 
> 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.