changeset 77642:63ebf0b1cf38

(Documentation Tips): Rearrange items to place the more important ones first. Add an index entry for hyperlinks.

--- a/lispref/tips.texi	Thu May 03 22:56:49 2007 +0000
+++ b/lispref/tips.texi	Fri May 04 13:20:03 2007 +0000
@@ -648,6 +648,12 @@
 variable.  Please use complete sentences for the rest of the text too.
 
 @item
+When the user tries to use a disabled command, Emacs displays just the
+first paragraph of its documentation string---everything through the
+first blank line.  If you wish, you can choose which information to
+include before the first blank line so as to make this display useful.
+
+@item
 The first line should mention all the important arguments of the
 function, and should mention them in the order that they are written
 in a function call.  If the function has many arguments, then it is
@@ -656,69 +662,6 @@
 important arguments.
 
 @item
-For consistency, phrase the verb in the first sentence of a function's
-documentation string as an imperative---for instance, use ``Return the
-cons of A and B.'' in preference to ``Returns the cons of A and B@.''
-Usually it looks good to do likewise for the rest of the first
-paragraph.  Subsequent paragraphs usually look better if each sentence
-is indicative and has a proper subject.
-
-@item
-Write documentation strings in the active voice, not the passive, and in
-the present tense, not the future.  For instance, use ``Return a list
-containing A and B.'' instead of ``A list containing A and B will be
-returned.''
-
-@item
-Avoid using the word ``cause'' (or its equivalents) unnecessarily.
-Instead of, ``Cause Emacs to display text in boldface,'' write just
-``Display text in boldface.''
-
-@item
-When a command is meaningful only in a certain mode or situation,
-do mention that in the documentation string.  For example,
-the documentation of @code{dired-find-file} is:
-
-@example
-In Dired, visit the file or directory named on this line.
-@end example
-
-@item
-Do not start or end a documentation string with whitespace.
-
-@item
-@strong{Do not} indent subsequent lines of a documentation string so
-that the text is lined up in the source code with the text of the first
-line.  This looks nice in the source code, but looks bizarre when users
-view the documentation.  Remember that the indentation before the
-starting double-quote is not part of the string!
-
-@item
-When the user tries to use a disabled command, Emacs displays just the
-first paragraph of its documentation string---everything through the
-first blank line.  If you wish, you can choose which information to
-include before the first blank line so as to make this display useful.
-
-@item
-When you define a variable that users ought to set interactively, you
-normally should use @code{defcustom}.  However, if for some reason you
-use @code{defvar} instead, start the doc string with a @samp{*}.
-@xref{Defining Variables}.
-
-@item
-The documentation string for a variable that is a yes-or-no flag should
-start with words such as ``Non-nil means,'' to make it clear that
-all non-@code{nil} values are equivalent and indicate explicitly what
-@code{nil} and non-@code{nil} mean.
-
-@item
-The documentation string for a function that is a yes-or-no predicate
-should start with words such as ``Return t if,'' to indicate
-explicitly what constitutes ``truth.''  The word ``return'' avoids
-starting the sentence with lower-case ``t,'' which could be somewhat
-distracting.
-
-@item
 When a function's documentation string mentions the value of an argument
 of the function, use the argument name in capital letters as if it were
 a name for that value.  Thus, the documentation string of the function
@@ -754,16 +697,14 @@
 is not at the start of it.
 
 @item
-If a line in a documentation string begins with an open-parenthesis,
-write a backslash before the open-parenthesis, like this:
+Do not start or end a documentation string with whitespace.
 
-@example
-The argument FOO can be either a number
-\(a buffer position) or a string (a file name).
-@end example
-
-This prevents the open-parenthesis from being treated as the start of a
-defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
+@item
+@strong{Do not} indent subsequent lines of a documentation string so
+that the text is lined up in the source code with the text of the first
+line.  This looks nice in the source code, but looks bizarre when users
+view the documentation.  Remember that the indentation before the
+starting double-quote is not part of the string!
 
 @anchor{Docstring hyperlinks}
 @item
@@ -781,6 +722,7 @@
 convention, with single-quotes for all symbols.)
 @end ifnottex
 
+@cindex hyperlinks in documentation strings
 Help mode automatically creates a hyperlink when a documentation string
 uses a symbol name inside single quotes, if the symbol has either a
 function or a variable definition.  You do not need to do anything
@@ -863,6 +805,65 @@
 display of the documentation string will become slow.  So use this to
 describe the most important commands in your major mode, and then use
 @samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
+
+@item
+For consistency, phrase the verb in the first sentence of a function's
+documentation string as an imperative---for instance, use ``Return the
+cons of A and B.'' in preference to ``Returns the cons of A and B@.''
+Usually it looks good to do likewise for the rest of the first
+paragraph.  Subsequent paragraphs usually look better if each sentence
+is indicative and has a proper subject.
+
+@item
+The documentation string for a function that is a yes-or-no predicate
+should start with words such as ``Return t if,'' to indicate
+explicitly what constitutes ``truth.''  The word ``return'' avoids
+starting the sentence with lower-case ``t,'' which could be somewhat
+distracting.
+
+@item
+If a line in a documentation string begins with an open-parenthesis,
+write a backslash before the open-parenthesis, like this:
+
+@example
+The argument FOO can be either a number
+\(a buffer position) or a string (a file name).
+@end example
+
+This prevents the open-parenthesis from being treated as the start of a
+defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
+
+@item
+Write documentation strings in the active voice, not the passive, and in
+the present tense, not the future.  For instance, use ``Return a list
+containing A and B.'' instead of ``A list containing A and B will be
+returned.''
+
+@item
+Avoid using the word ``cause'' (or its equivalents) unnecessarily.
+Instead of, ``Cause Emacs to display text in boldface,'' write just
+``Display text in boldface.''
+
+@item
+When a command is meaningful only in a certain mode or situation,
+do mention that in the documentation string.  For example,
+the documentation of @code{dired-find-file} is:
+
+@example
+In Dired, visit the file or directory named on this line.
+@end example
+
+@item
+When you define a variable that users ought to set interactively, you
+normally should use @code{defcustom}.  However, if for some reason you
+use @code{defvar} instead, start the doc string with a @samp{*}.
+@xref{Defining Variables}.
+
+@item
+The documentation string for a variable that is a yes-or-no flag should
+start with words such as ``Non-nil means,'' to make it clear that
+all non-@code{nil} values are equivalent and indicate explicitly what
+@code{nil} and non-@code{nil} mean.
 @end itemize
 
 @node Comment Tips