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)" <address@hidden>
> 
> 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.