[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Info about how to write links in doc string

From: Eli Zaretskii
Subject: Re: Info about how to write links in doc string
Date: Fri, 04 May 2007 16:26:02 +0300

> 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

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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]