# HG changeset patch # User Richard M. Stallman # Date 766718871 0 # Node ID 3b19456b877abae92e3d4fcdf096a14a6cd6e505 # Parent 6962dec6fe55dd669ea8e88961349100c26db107 *** empty log message *** diff -r 6962dec6fe55 -r 3b19456b877a lispref/tips.texi --- a/lispref/tips.texi Tue Apr 19 00:51:24 1994 +0000 +++ b/lispref/tips.texi Tue Apr 19 01:27:51 1994 +0000 @@ -101,6 +101,18 @@ that context. @item +Applications should not bind mouse events based on button 1 with the +shift key held down. These events include @kbd{S-mouse-1}, +@kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on. They are reserved for +users. + +@item +Modes should redefine @kbd{mouse-2} as a command to follow some sort of +reference in the text of a buffer, if users usually would not want to +alter the text in that buffer by hand. Modes such as Dired, Info, +Compilation, and Occur redefine it in this way. + +@item It is a bad idea to define aliases for the Emacs primitives. Use the standard names instead. @@ -163,19 +175,18 @@ or @code{beep} to report errors. @item -Avoid using recursive edits. Instead, do what the Rmail @kbd{w} command -does: use a new local keymap that contains one command defined to -switch back to the old local keymap. Or do what the @code{edit-options} -command does: switch to another buffer and let the user switch back at -will. @xref{Recursive Editing}. +Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e} +command does: use a new local keymap that contains one command defined +to switch back to the old local keymap. Or do what the +@code{edit-options} command does: switch to another buffer and let the +user switch back at will. @xref{Recursive Editing}. @item In some other systems there is a convention of choosing variable names that begin and end with @samp{*}. We don't use that convention in Emacs -Lisp, so please don't use it in your library. (In fact, in Emacs names -of this form are conventionally used for program-generated buffers.) The -users will find Emacs more coherent if all libraries use the same -conventions. +Lisp, so please don't use it in your programs. (Emacs uses such names +only for program-generated buffers.) The users will find Emacs more +coherent if all libraries use the same conventions. @item Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the @@ -201,7 +212,7 @@ @cindex speedups Here are ways of improving the execution speed of byte-compiled -lisp programs. +Lisp programs. @itemize @bullet @item @@ -223,7 +234,7 @@ functions can be used. @item -Certain built-in functions are handled specially by the byte compiler +Certain built-in functions are handled specially in byte-compiled code, avoiding the need for an ordinary function call. It is a good idea to use these functions rather than alternatives. To see whether a function is handled specially by the compiler, examine its @code{byte-compile} @@ -234,7 +245,7 @@ compiled specially (@pxref{Array Functions}) while @code{elt} is not (@pxref{Sequence Functions}): -@smallexample +@example @group (get 'aref 'byte-compile) @result{} byte-compile-two-args @@ -244,14 +255,14 @@ (get 'elt 'byte-compile) @result{} nil @end group -@end smallexample +@end example @item If calling a small function accounts for a substantial part of your program's running time, make the function inline. This eliminates the function call overhead. Since making a function inline reduces the flexibility of changing the program, don't do it unless it gives -a noticeable speedup in something slow enough for users to care about +a noticeable speedup in something slow enough that users care about the speed. @xref{Inline Functions}. @end itemize @@ -271,10 +282,10 @@ @item The first line of the documentation string should consist of one or two -complete sentences which stand on their own as a summary. In particular, -start the line with a capital letter and end with a period. -For instance, use ``Return the cons of A and B.'' in preference to -``Returns the cons of A and B@.'' +complete sentences which stand on their own as a summary. @kbd{M-x +apropos} displays just the first line, and if it doesn't stand on its +own, the result looks bad. In particular, start the first line with a +capital letter and end with a period. The documentation string can have additional lines which expand on the details of how to use the function or variable. The additional lines @@ -282,6 +293,14 @@ that looks good. @item +For consistency, phrase the verb in the first sentence of a +documentation string as an infinitive with ``to'' omitted. 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 they have proper subjects. + +@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 @@ -314,22 +333,23 @@ @item A variable's documentation string should start with @samp{*} if the -variable is one that users would want to set interactively often. If +variable is one that users would often want to set interactively. If the value is a long list, or a function, or if the variable would only be set in init files, then don't start the documentation string with @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@dots{}'', to make it clear both -that the variable only has two meaningfully distinct values and which value -means ``yes''. +start with words such as ``Non-nil means@dots{}'', to make it clear that +all non-@code{nil} values are equivalent and indicate explicitly what +@code{nil} and non-@code{nil} mean. @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 -@code{/} refers to its second argument as @samp{DIVISOR}. +@code{/} refers to its second argument as @samp{DIVISOR}, because the +actual argument name is @code{divisor}. Also use all caps for meta-syntactic variables, such as when you show the decomposition of a list or vector into subunits, some of which may @@ -353,11 +373,11 @@ @item Don't write key sequences directly in documentation strings. Instead, use the @samp{\\[@dots{}]} construct to stand for them. For example, -instead of writing @samp{C-f}, write @samp{\\[forward-char]}. When the -documentation string is printed, Emacs will substitute whatever key is -currently bound to @code{forward-char}. This will usually be -@samp{C-f}, but if the user has moved key bindings, it will be the -correct key for that user. @xref{Keys in Documentation}. +instead of writing @samp{C-f}, write @samp{\\[forward-char]}. When +Emacs displays the documentation string, it substitutes whatever key is +currently bound to @code{forward-char}. (This is normally @samp{C-f}, +but it may be some other character if the user has moved key bindings.) +@xref{Keys in Documentation}. @item In documentation strings for a major mode, you will want to refer to the @@ -391,7 +411,7 @@ comments usually explain how the code on the same line does its job. In Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment}) command automatically inserts such a @samp{;} in the right place, or -aligns such a comment if it is already inserted. +aligns such a comment if it is already present. (The following examples are taken from the Emacs sources.) @@ -406,7 +426,7 @@ @item ;; Comments that start with two semicolons, @samp{;;}, should be aligned to -the same level of indentation as the code. Such comments are used to +the same level of indentation as the code. Such comments usually describe the purpose of the following lines or the state of the program at that point. For example: @@ -415,18 +435,22 @@ (prog1 (setq auto-fill-function @dots{} @dots{} - ;; update mode-line + ;; update mode line (force-mode-line-update))) @end group @end smallexample -These comments are also written before a function definition to explain -what the function does and how to call it properly. +Every function that has no documentation string (because it is use only +internally within the package it belongs to), should have instead a +two-semicolon comment right before the function, explaining what the +function does and how to call it properly. Explain precisely what each +argument means and how the function interprets its possible value. @item ;;; Comments that start with three semicolons, @samp{;;;}, should start at -the left margin. Such comments are not used within function -definitions, but are used to make more general comments. For example: +the left margin. Such comments are used outside function definitions to +make general statements explaining the design principles of the program. +For example: @smallexample @group @@ -436,6 +460,17 @@ @end group @end smallexample +Another use for triple-semicolon comments is for commenting out line +within a function. We use triple-semicolons for this precisely so that +they remain at the left margin. + +@smallexample +(defun foo (a) +;;; This is no longer necessary. +;;; (force-mode-line-update) + (message "Finished with %s" a)) +@end smallexample + @item ;;;; Comments that start with four semicolons, @samp{;;;;}, should be aligned to the left margin and are used for headings of major sections of a @@ -453,14 +488,6 @@ depending on the the number of semicolons. @xref{Comments,, Manipulating Comments, emacs, The GNU Emacs Manual}. - If you wish to ``comment out'' a number of lines of code, use triple -semicolons at the beginnings of the lines. - - Any character may be included in a comment, but it is advisable to -precede a character with syntactic significance in Lisp (such as -@samp{\} or unpaired @samp{(} or @samp{)}) with a @samp{\}, to prevent -it from confusing the Emacs commands for editing Lisp. - @node Library Headers @section Conventional Headers for Emacs Libraries @cindex header comments @@ -499,7 +526,7 @@ The description should be complete in one line. After the copyright notice come several @dfn{header comment} lines, -each beginning with @samp{;;; @var{header-name}:}. Here is a table of +each beginning with @samp{;; @var{header-name}:}. Here is a table of the conventional possibilities for @var{header-name}: @table @samp @@ -508,23 +535,23 @@ author of the library. If there are multiple authors, you can list them on continuation lines -led by @code{;;}, like this: +led by @code{;;} and a tab character, like this: @smallexample @group ;; Author: Ashwin Ram -;; Dave Sill -;; Dave Brennan -;; Eric Raymond +;; Dave Sill +;; Dave Brennan +;; Eric Raymond @end group @end smallexample @item Maintainer This line should contain a single name/address as in the Author line, or -an address only, or the string ``FSF''. If there is no maintainer line, -the person(s) in the Author field are presumed to be the maintainers. -The example above is mildly bogus because the maintainer line is -redundant. +an address only, or the string @samp{FSF}. If there is no maintainer +line, the person(s) in the Author field are presumed to be the +maintainers. The example above is mildly bogus because the maintainer +line is redundant. The idea behind the @samp{Author} and @samp{Maintainer} lines is to make possible a Lisp function to ``send mail to the maintainer'' without