* Info about how to write links in doc string @ 2007-05-01 21:35 Lennart Borgman (gmail) 2007-05-02 4:39 ` Richard Stallman 2007-05-04 13:26 ` Eli Zaretskii 0 siblings, 2 replies; 5+ messages in thread From: Lennart Borgman (gmail) @ 2007-05-01 21:35 UTC (permalink / raw) To: Emacs Devel 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. ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Info about how to write links in doc string 2007-05-01 21:35 Info about how to write links in doc string Lennart Borgman (gmail) @ 2007-05-02 4:39 ` Richard Stallman 2007-05-04 13:26 ` Eli Zaretskii 1 sibling, 0 replies; 5+ messages in thread From: Richard Stallman @ 2007-05-02 4:39 UTC (permalink / raw) To: Lennart Borgman (gmail); +Cc: emacs-devel Thanks. ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Info about how to write links in doc string 2007-05-01 21:35 Info about how to write links in doc string Lennart Borgman (gmail) 2007-05-02 4:39 ` Richard Stallman @ 2007-05-04 13:26 ` Eli Zaretskii 2007-05-04 13:41 ` Lennart Borgman (gmail) 1 sibling, 1 reply; 5+ messages in thread From: Eli Zaretskii @ 2007-05-04 13:26 UTC (permalink / raw) To: Lennart Borgman (gmail); +Cc: emacs-devel > 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. ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Info about how to write links in doc string 2007-05-04 13:26 ` Eli Zaretskii @ 2007-05-04 13:41 ` Lennart Borgman (gmail) 2007-05-04 14:01 ` Eli Zaretskii 0 siblings, 1 reply; 5+ messages in thread From: Lennart Borgman (gmail) @ 2007-05-04 13:41 UTC (permalink / raw) To: Eli Zaretskii; +Cc: emacs-devel 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. ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: Info about how to write links in doc string 2007-05-04 13:41 ` Lennart Borgman (gmail) @ 2007-05-04 14:01 ` Eli Zaretskii 0 siblings, 0 replies; 5+ messages in thread From: Eli Zaretskii @ 2007-05-04 14:01 UTC (permalink / raw) To: Lennart Borgman (gmail); +Cc: emacs-devel > 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. ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2007-05-04 14:01 UTC | newest] Thread overview: 5+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2007-05-01 21:35 Info about how to write links in doc string Lennart Borgman (gmail) 2007-05-02 4:39 ` Richard Stallman 2007-05-04 13:26 ` Eli Zaretskii 2007-05-04 13:41 ` Lennart Borgman (gmail) 2007-05-04 14:01 ` Eli Zaretskii
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.