[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/lispref/tips.texi,v [EMACS_22_BASE]
From: |
Eli Zaretskii |
Subject: |
[Emacs-diffs] Changes to emacs/lispref/tips.texi,v [EMACS_22_BASE] |
Date: |
Fri, 04 May 2007 13:20:04 +0000 |
CVSROOT: /cvsroot/emacs
Module name: emacs
Branch: EMACS_22_BASE
Changes by: Eli Zaretskii <eliz> 07/05/04 13:20:04
Index: tips.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/tips.texi,v
retrieving revision 1.94
retrieving revision 1.94.2.1
diff -u -b -r1.94 -r1.94.2.1
--- tips.texi 7 Apr 2007 01:47:07 -0000 1.94
+++ tips.texi 4 May 2007 13:20:03 -0000 1.94.2.1
@@ -648,75 +648,18 @@
variable. Please use complete sentences for the rest of the text too.
@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
-not feasible to mention them all in the first line; in that case, the
-first line should mention the first few arguments, including the most
-important arguments.
-
address@hidden
-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
address@hidden''
-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.
-
address@hidden
-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.''
-
address@hidden
-Avoid using the word ``cause'' (or its equivalents) unnecessarily.
-Instead of, ``Cause Emacs to display text in boldface,'' write just
-``Display text in boldface.''
-
address@hidden
-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:
-
address@hidden
-In Dired, visit the file or directory named on this line.
address@hidden example
-
address@hidden
-Do not start or end a documentation string with whitespace.
-
address@hidden
address@hidden 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!
-
address@hidden
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{*}.
address@hidden Variables}.
-
address@hidden
-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 address@hidden values are equivalent and indicate explicitly what
address@hidden and address@hidden mean.
-
address@hidden
-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.
+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
+not feasible to mention them all in the first line; in that case, the
+first line should mention the first few arguments, including the most
+important arguments.
@item
When a function's documentation string mentions the value of an argument
@@ -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:
-
address@hidden
-The argument FOO can be either a number
-\(a buffer position) or a string (a file name).
address@hidden example
+Do not start or end a documentation string with whitespace.
-This prevents the open-parenthesis from being treated as the start of a
-defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
address@hidden
address@hidden 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
address@hidden 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
@address@hidden@address@hidden to display the rest of the mode's keymap.
+
address@hidden
+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
address@hidden''
+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.
+
address@hidden
+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.
+
address@hidden
+If a line in a documentation string begins with an open-parenthesis,
+write a backslash before the open-parenthesis, like this:
+
address@hidden
+The argument FOO can be either a number
+\(a buffer position) or a string (a file name).
address@hidden example
+
+This prevents the open-parenthesis from being treated as the start of a
+defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
+
address@hidden
+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.''
+
address@hidden
+Avoid using the word ``cause'' (or its equivalents) unnecessarily.
+Instead of, ``Cause Emacs to display text in boldface,'' write just
+``Display text in boldface.''
+
address@hidden
+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:
+
address@hidden
+In Dired, visit the file or directory named on this line.
address@hidden example
+
address@hidden
+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{*}.
address@hidden Variables}.
+
address@hidden
+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 address@hidden values are equivalent and indicate explicitly what
address@hidden and address@hidden mean.
@end itemize
@node Comment Tips
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] Changes to emacs/lispref/tips.texi,v [EMACS_22_BASE],
Eli Zaretskii <=