From a2a48b7105721ff79f5eac019d5056608e477da5 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 4 May 2007 13:20:25 +0000 Subject: [PATCH 1/4] (Documentation Tips): Rearrange items to place the more important ones first. Add an index entry for hyperlinks. --- lispref/ChangeLog | 5 ++ lispref/tips.texi | 145 +++++++++++++++++++++++----------------------- 2 files changed, 78 insertions(+), 72 deletions(-) diff --git a/lispref/ChangeLog b/lispref/ChangeLog index c22f8e66f0f..dbae0af349b 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,8 @@ +2007-05-04 Eli Zaretskii + + * tips.texi (Documentation Tips): Rearrange items to place the + more important ones first. Add an index entry for hyperlinks. + 2007-05-03 Karl Berry * elisp.texi (\urlcolor, \linkcolor) [smallbook]: \Black for printing. diff --git a/lispref/tips.texi b/lispref/tips.texi index ee8caf4953b..254e1faf7ff 100644 --- a/lispref/tips.texi +++ b/lispref/tips.texi @@ -647,52 +647,6 @@ Don't limit the documentation string to one line; use as many lines as you need to explain the details of how to use the function or 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. - -@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 @@ -700,23 +654,12 @@ 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. +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 @@ and that annoys you, rewrite the sentence so that the symbol 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 @@ t and nil without single-quotes. (In this manual, we use a different 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 @@ It is not practical to use @samp{\\[@dots{}]} very many times, because 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 From 16fb735f4ac2e2d9696285247aaa26b5c565fb1e Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 4 May 2007 13:41:15 +0000 Subject: [PATCH 2/4] Add information about building with Cygwin Make 3.80. --- nt/INSTALL | 14 ++++++++------ nt/configure.bat | 14 ++++++++------ 2 files changed, 16 insertions(+), 12 deletions(-) diff --git a/nt/INSTALL b/nt/INSTALL index fe5381a6f21..c9afa8f5de3 100644 --- a/nt/INSTALL +++ b/nt/INSTALL @@ -157,11 +157,11 @@ cygwin compiled gmake 3.77: fails[1, 5] fails[2, 5] cygwin compiled make 3.78.1: fails[5] fails[2, 5] cygwin compiled make 3.79.1: fails[3, 5] fails[2?, 5] - cygwin compiled make 3.80: fails?[6] fails?[6] - cygwin compiled make 3.81: fails fails?[6] + cygwin compiled make 3.80: okay[6] fails?[7] + cygwin compiled make 3.81: fails fails?[7] mingw32 compiled make 3.79.1: okay okay - mingw32 compiled make 3.80: okay okay[6] - mingw32 compiled make 3.81: okay okay[7] + mingw32 compiled make 3.80: okay okay[7] + mingw32 compiled make 3.81: okay okay[8] Notes: @@ -173,8 +173,10 @@ [4] may fail on Windows 9X and Windows ME; if so, install Bash. [5] fails when building leim due to the use of cygwin style paths. May work if building emacs without leim. - [6] not recommended; please report if you try this combination. - [7] tested only on Windows XP. + [6] need to uncomment 3 lines in nt/gmake.defs that invoke `cygpath' + (look for "cygpath" near line 85 of gmake.defs). + [7] not recommended; please report if you try this combination. + [8] tested only on Windows XP. Other compilers may work, but specific reports from people that have tried suggest that the Intel C compiler (for example) may produce an diff --git a/nt/configure.bat b/nt/configure.bat index 1223f7e861d..2ff90186445 100755 --- a/nt/configure.bat +++ b/nt/configure.bat @@ -41,11 +41,11 @@ rem mingw32/gcc-2.92.2 make (3.77): okay okay[4] rem cygwin compiled gmake 3.77: fails[1,5] fails[2,5] rem cygwin compiled gmake 3.78.1: fails[5] fails[2,5] rem cygwin compiled gmake 3.79.1: fails[3,5] fails[2?,5] -rem cygwin compiled make 3.80: fails?[6] fails?[6] -rem cygwin compiled make 3.81: fails fails?[6] +rem cygwin compiled make 3.80: okay[6] fails?[7] +rem cygwin compiled make 3.81: fails fails?[7] rem mingw32 compiled make 3.79.1: okay okay -rem mingw32 compiled make 3.80: okay okay?[6] -rem mingw32 compiled make 3.81: okay okay[7] +rem mingw32 compiled make 3.80: okay okay?[7] +rem mingw32 compiled make 3.81: okay okay[8] rem rem [1] doesn't cope with makefiles with DOS line endings, so must mount rem emacs source with text!=binary. @@ -55,8 +55,10 @@ rem versions of cygwin. rem [4] may fail on Windows 9X and Windows ME; if so, install Bash. rem [5] fails when building leim due to the use of cygwin style paths. rem May work if building emacs without leim. -rem [6] not recommended; please report if you try this combination. -rem [7] tested only on Windows XP. +rem [6] need to uncomment 3 lines in nt/gmake.defs that invoke `cygpath'; +rem look for "cygpath" near line 85 of gmake.defs. +rem [7] not recommended; please report if you try this combination. +rem [8] tested only on Windows XP. rem if exist config.log del config.log From 66d6ead825d11497a9211813ce0159b0da4e65c6 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 4 May 2007 17:03:08 +0000 Subject: [PATCH 3/4] EMACSVER 22.1 for printed version --- lispref/ChangeLog | 4 ++++ lispref/elisp.texi | 2 +- man/ChangeLog | 4 ++++ man/emacs.texi | 2 +- 4 files changed, 10 insertions(+), 2 deletions(-) diff --git a/lispref/ChangeLog b/lispref/ChangeLog index dbae0af349b..c67b9c21829 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,7 @@ +2007-05-04 Karl Berry + + * elisp.texi (EMACSVER) [smallbook]: 22.1, not 22. + 2007-05-04 Eli Zaretskii * tips.texi (Documentation Tips): Rearrange items to place the diff --git a/lispref/elisp.texi b/lispref/elisp.texi index 1860ae710a0..3ece3c53d0a 100644 --- a/lispref/elisp.texi +++ b/lispref/elisp.texi @@ -29,7 +29,7 @@ @tex @ifset smallbook @fonttextsize 10 -@set EMACSVER 22 +@set EMACSVER 22.1 \global\let\urlcolor=\Black % don't print links in grayscale \global\let\linkcolor=\Black @end ifset diff --git a/man/ChangeLog b/man/ChangeLog index a960322f17e..a7caf64f195 100644 --- a/man/ChangeLog +++ b/man/ChangeLog @@ -1,3 +1,7 @@ +2007-05-04 Karl Berry + + * emacs.texi (EMACSVER) [smallbook]: 22.1 for printed version, not 22. + 2007-05-03 Karl Berry * emacs.texi (EMACSVER) [smallbook]: 22 for printed version. diff --git a/man/emacs.texi b/man/emacs.texi index 8ab1eea4a11..d264a67f29a 100644 --- a/man/emacs.texi +++ b/man/emacs.texi @@ -51,7 +51,7 @@ Software Foundation raise funds for GNU development.'' @tex @ifset smallbook @fonttextsize 10 -@set EMACSVER 22 +@set EMACSVER 22.1 \global\let\urlcolor=\Black % don't print links in grayscale \global\let\linkcolor=\Black @end ifset From 2511170598c70994042e68108481a8f5792e5f96 Mon Sep 17 00:00:00 2001 From: "Richard M. Stallman" Date: Fri, 4 May 2007 17:09:11 +0000 Subject: [PATCH 4/4] *** empty log message *** --- admin/FOR-RELEASE | 3 +++ 1 file changed, 3 insertions(+) diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE index e0ad1eb885d..b794006a493 100644 --- a/admin/FOR-RELEASE +++ b/admin/FOR-RELEASE @@ -51,6 +51,9 @@ http://lists.gnu.org/archive/html/emacs-devel/2007-04/msg00732.html http://lists.gnu.org/archive/html/emacs-devel/2007-04/msg01113.html ** Takaaki.Ota@am.sony.com, May 2: table cell menu does not appear at the menubar + Bug is intermittent. + +** david.reitter@gmail.com, May 4: Euro sign bound, Pound sign not bound. (Bug?) * DOCUMENTATION