# HG changeset patch # User Eli Zaretskii # Date 1178284803 0 # Node ID 63ebf0b1cf38b2f021470816bfe4c4e1ad759246 # Parent 01d54caeca941009f5da7d56649947e484a35afb (Documentation Tips): Rearrange items to place the more important ones first. Add an index entry for hyperlinks. diff -r 01d54caeca94 -r 63ebf0b1cf38 lispref/tips.texi --- 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