X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/bfe721d172158ccdcd925e55f5a658421ca0d4fe..db8af011af1d4d58b42a285e252504c860693d9a:/lispref/tips.texi diff --git a/lispref/tips.texi b/lispref/tips.texi index 76cd3427ee..a85147f1d8 100644 --- a/lispref/tips.texi +++ b/lispref/tips.texi @@ -1,50 +1,61 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998, 1999 +@c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/tips -@node Tips, GNU Emacs Internals, Calendar, Top -@appendix Tips and Standards +@node Tips, GNU Emacs Internals, GPL, Top +@appendix Tips and Conventions @cindex tips @cindex standards of coding style @cindex coding standards - This chapter describes no additional features of Emacs Lisp. -Instead it gives advice on making effective use of the features described -in the previous chapters. + This chapter describes no additional features of Emacs Lisp. Instead +it gives advice on making effective use of the features described in the +previous chapters, and describes conventions Emacs Lisp programmers +should follow. + + You can automatically check some of the conventions described below by +running the command @kbd{M-x checkdoc RET} when visiting a Lisp file. +It cannot check all of the conventions, and not all the warnings it +gives necessarily correspond to problems, but it is worth examining them +all. @menu -* Style Tips:: Writing clean and robust programs. +* Coding Conventions:: Conventions for clean and robust programs. * Compilation Tips:: Making compiled code run fast. * Documentation Tips:: Writing readable documentation strings. * Comment Tips:: Conventions for writing comments. * Library Headers:: Standard headers for library packages. @end menu -@node Style Tips -@section Writing Clean Lisp Programs +@node Coding Conventions +@section Emacs Lisp Coding Conventions - Here are some tips for avoiding common errors in writing Lisp code -intended for widespread use: + Here are conventions that you should follow when writing Emacs Lisp +code intended for widespread use: @itemize @bullet @item -Since all global variables share the same name space, and all functions -share another name space, you should choose a short word to distinguish -your program from other Lisp programs. Then take care to begin the -names of all global variables, constants, and functions with the chosen +Since all global variables share the same name space, and all +functions share another name space, you should choose a short word to +distinguish your program from other Lisp programs.@footnote{The +benefits of a Common Lisp-style package system are considered not to +outweigh the costs.} Then take care to begin the names of all global +variables, constants, and functions in your program with the chosen prefix. This helps avoid name conflicts. This recommendation applies even to names for traditional Lisp -primitives that are not primitives in Emacs Lisp---even to @code{cadr}. -Believe it or not, there is more than one plausible way to define -@code{cadr}. Play it safe; append your name prefix to produce a name -like @code{foo-cadr} or @code{mylib-cadr} instead. +primitives that are not primitives in Emacs Lisp---even to +@code{copy-list}. Believe it or not, there is more than one plausible +way to define @code{copy-list}. Play it safe; append your name prefix +to produce a name like @code{foo-copy-list} or @code{mylib-copy-list} +instead. If you write a function that you think ought to be added to Emacs under a certain name, such as @code{twiddle-files}, don't call it by that name in your program. Call it @code{mylib-twiddle-files} in your program, -and send mail to @samp{bug-gnu-emacs@@prep.ai.mit.edu} suggesting we add +and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add it to Emacs. If and when we do, we can change the name easily enough. If one prefix is insufficient, your package may use two or three @@ -74,18 +85,35 @@ macro: @end example @noindent -(And @var{bar} should contain @code{(provide '@var{bar})}, to make the -@code{require} work.) This will cause @var{bar} to be loaded when you -byte-compile @var{foo}. Otherwise, you risk compiling @var{foo} without -the necessary macro loaded, and that would produce compiled code that -won't work right. @xref{Compiling Macros}. +(And the library @var{bar} should contain @code{(provide '@var{bar})}, +to make the @code{require} work.) This will cause @var{bar} to be +loaded when you byte-compile @var{foo}. Otherwise, you risk compiling +@var{foo} without the necessary macro loaded, and that would produce +compiled code that won't work right. @xref{Compiling Macros}. Using @code{eval-when-compile} avoids loading @var{bar} when the compiled version of @var{foo} is @emph{used}. @item -If you define a major mode, make sure to run a hook variable using -@code{run-hooks}, just as the existing major modes do. @xref{Hooks}. +Please don't require the @code{cl} package of Common Lisp extensions at +run time. Use of this package is optional, and it is not part of the +standard Emacs namespace. If your package loads @code{cl} at run time, +that could cause name clashes for users who don't use that package. + +However, there is no problem with using the @code{cl} package at compile +time, for the sake of macros. You do that like this: + +@example +(eval-when-compile (require 'cl)) +@end example + +@item +When defining a major mode, please follow the major mode +conventions. @xref{Major Mode Conventions}. + +@item +When defining a minor mode, please follow the minor mode +conventions. @xref{Minor Mode Conventions}. @item If the purpose of a function is to tell you whether a certain condition @@ -98,17 +126,26 @@ If a user option variable records a true-or-false condition, give it a name that ends in @samp{-flag}. @item +If the purpose of a variable is to store a single function, give it a +name that ends in @samp{-function}. If the purpose of a variable is +to store a list of functions (i.e., the variable is a hook), please +follow the naming conventions for hooks. @xref{Hooks}. + +@item +@cindex reserved keys +@cindex keys, reserved Please do not define @kbd{C-c @var{letter}} as a key in your major -modes. These sequences are reserved for users; they are the -@strong{only} sequences reserved for users, so we cannot do without -them. +modes. Sequences consisting of @kbd{C-c} and a letter (either upper +or lower case) are reserved for users; they are the @strong{only} +sequences reserved for users, so do not block them. -Instead, define sequences consisting of @kbd{C-c} followed by a -non-letter. These sequences are reserved for major modes. +Changing all the Emacs major modes to respect this convention was a +lot of work; abandoning this convention would make that work go to +waste, and inconvenience users. Please comply with it. -Changing all the major modes in Emacs 18 so they would follow this -convention was a lot of work. Abandoning this convention would make -that work go to waste, and inconvenience users. +@item +Sequences consisting of @kbd{C-c} followed by a control character or a +digit are reserved for major modes. @item Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}}, @@ -121,19 +158,36 @@ not absolutely prohibited, but if you do that, the major mode binding may be shadowed from time to time by minor modes. @item -You should not bind @kbd{C-h} following any prefix character (including +Function keys @key{F5} through @key{F9} without modifier keys are +reserved for users to define. + +@item +Do not bind @kbd{C-h} following any prefix character (including @kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically available as a help character for listing the subcommands of the prefix character. @item -You should not bind a key sequence ending in @key{ESC} except following -another @key{ESC}. (That is, it is ok to bind a sequence ending in +Do not bind a key sequence ending in @key{ESC} except following +another @key{ESC}. (That is, it is OK to bind a sequence ending in @kbd{@key{ESC} @key{ESC}}.) The reason for this rule is that a non-prefix binding for @key{ESC} in any context prevents recognition of escape sequences as function keys in that context. +@item +Anything which acts like a temporary mode or state which the user can +enter and leave should define @kbd{@key{ESC} @key{ESC}} or +@kbd{@key{ESC} @key{ESC} @key{ESC}} as a way to escape. + +For a state which accepts ordinary Emacs commands, or more generally any +kind of state in which @key{ESC} followed by a function key or arrow key +is potentially meaningful, then you must not define @kbd{@key{ESC} +@key{ESC}}, since that would preclude recognizing an escape sequence +after @key{ESC}. In these states, you should define @kbd{@key{ESC} +@key{ESC} @key{ESC}} as the way to escape. Otherwise, define +@kbd{@key{ESC} @key{ESC}} instead. + @item Applications should not bind mouse events based on button 1 with the shift key held down. These events include @kbd{S-mouse-1}, @@ -141,27 +195,53 @@ shift key held down. These events include @kbd{S-mouse-1}, 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. +@cindex mouse-2 +@cindex references, following +Special major modes used for read-only text should usually redefine +@kbd{mouse-2} and @key{RET} to trace some sort of reference in the text. +Modes such as Dired, Info, Compilation, and Occur redefine it in this +way. @item When a package provides a modification of ordinary Emacs behavior, it is -good to include a command to enable and disable the feature, Provide a +good to include a command to enable and disable the feature, provide a command named @code{@var{whatever}-mode} which turns the feature on or off, and make it autoload (@pxref{Autoload}). Design the package so that simply loading it has no visible effect---that should not enable -the feature. Users will request the feature by invoking the command. +the feature.@footnote{Consider that the package may be loaded +arbitrarily by Custom for instance.} Users will request the feature by +invoking the command. It is a good idea to define this command +as a minor mode. + +@cindex unloading packages +If loading the file adds functions to hooks, define a function +@code{@var{feature}-unload-hook}, where @var{feature} is the name of +the feature the package provides, and make it undo any such changes. +Using @code{unload-feature} to unload the file will run this function. +@xref{Unloading}. @item It is a bad idea to define aliases for the Emacs primitives. Use the standard names instead. @item -Redefining an Emacs primitive is an even worse idea. -It may do the right thing for a particular program, but -there is no telling what other programs might break as a result. +If a package needs to define an alias or a new function for +compatibility with some other version of Emacs, name it with the package +prefix, not with the raw name with which it occurs in the other version. +Here is an example from Gnus, which provides many examples of such +compatibility issues. + +@example +(defalias 'gnus-point-at-bol + (if (fboundp 'point-at-bol) + 'point-at-bol + 'line-beginning-position)) +@end example + +@item +Redefining (or advising) an Emacs primitive is discouraged. It may do +the right thing for a particular program, but there is no telling what +other programs might break as a result. @item If a file does replace any of the functions or library programs of @@ -169,6 +249,13 @@ standard Emacs, prominent comments at the beginning of the file should say which functions are replaced, and how the behavior of the replacements differs from that of the originals. +@item +Avoid using macros that define functions and variables with names that +are constructed. It is best for maintenance when the name of the +function or variable being defined is given explicitly in the source +code, as the second element of the list---as it is when you use +@code{defun}, @code{defalias}, @code{defvar} and @code{defcustom}. + @item Please keep the names of your Emacs Lisp source files to 13 characters or less. This way, if the files are compiled, the compiled files' names @@ -186,7 +273,7 @@ of the intended features of your program. The mark is a user-level feature, so it is incorrect to change the mark except to supply a value for the user's benefit. @xref{The Mark}. -In particular, don't use these functions: +In particular, don't use any of these functions: @itemize @bullet @item @@ -224,6 +311,49 @@ or @code{beep} to report errors. An error message should start with a capital letter but should not end with a period. +@item +In @code{interactive}, if you use a Lisp expression to produce a list +of arguments, don't try to provide the ``correct'' default values for +region or position arguments. Instead, provide @code{nil} for those +arguments if they were not specified, and have the function body +compute the default value when the argument is @code{nil}. For +instance, write this: + +@example +(defun foo (pos) + (interactive + (list (if @var{specified} @var{specified-pos}))) + (unless pos (setq pos @var{default-pos})) + ...) +@end example + +@noindent +rather than this: + +@example +(defun foo (pos) + (interactive + (list (if @var{specified} @var{specified-pos} + @var{default-pos}))) + ...) +@end example + +@noindent +This is so that repetition of the command will recompute +these defaults based on the current circumstances. + +You do not need to take such precautions when you use interactive +specs @samp{d}, @samp{m} and @samp{r}, because they make special +arrangements to recompute the argument values on repetition of the +command. + +@item +Many commands that take a long time to execute display a message that +says something like @samp{Operating...} when they start, and change it to +@samp{Operating...done} when they finish. Please keep the style of +these messages uniform: @emph{no} space around the ellipsis, and +@emph{no} period after @samp{done}. + @item 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 @@ -235,9 +365,31 @@ user switch back at will. @xref{Recursive Editing}. 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 programs. (Emacs uses such names -only for program-generated buffers.) The users will find Emacs more +only for special-purpose buffers.) The users will find Emacs more coherent if all libraries use the same conventions. +@item +Try to avoid compiler warnings about undefined free variables, by adding +@code{defvar} definitions for these variables. + +Sometimes adding a @code{require} for another package is useful to avoid +compilation warnings for variables and functions defined in that +package. If you do this, often it is better if the @code{require} acts +only at compile time. Here's how to do that: + +@example +(eval-when-compile + (require 'foo) + (defvar bar-baz)) +@end example + +If you bind a variable in one function, and use it or set it in another +function, the compiler warns about the latter function unless the +variable has a definition. But often these variables have short names, +and it is not clean for Lisp packages to define such variable names. +Therefore, you should rename the variable to start with the name prefix +used for the other functions and variables in your package. + @item Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the default indentation parameters. @@ -246,14 +398,34 @@ default indentation parameters. Don't make a habit of putting close-parentheses on lines by themselves; Lisp programmers find this disconcerting. Once in a while, when there is a sequence of many consecutive close-parentheses, it may make sense -to split them in one or two significant places. +to split the sequence in one or two significant places. @item Please put a copyright notice on the file if you give copies to anyone. -Use the same lines that appear at the top of the Lisp files in Emacs -itself. If you have not signed papers to assign the copyright to the -Foundation, then place your name in the copyright notice in place of the -Foundation's name. +Use a message like this one: + +@smallexample +;; Copyright (C) @var{year} @var{name} + +;; This program is free software; you can redistribute it and/or +;; modify it under the terms of the GNU General Public License as +;; published by the Free Software Foundation; either version 2 of +;; the License, or (at your option) any later version. + +;; This program is distributed in the hope that it will be +;; useful, but WITHOUT ANY WARRANTY; without even the implied +;; warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +;; PURPOSE. See the GNU General Public License for more details. + +;; You should have received a copy of the GNU General Public +;; License along with this program; if not, write to the Free +;; Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, +;; MA 02111-1307 USA +@end smallexample + +If you have signed papers to assign the copyright to the Foundation, +then use @samp{Free Software Foundation, Inc.} as @var{name}. +Otherwise, use your name. @end itemize @node Compilation Tips @@ -268,9 +440,9 @@ Lisp programs. @item @cindex profiling @cindex timing programs -@cindex @file{profile.el} -Use the @file{profile} library to profile your program. See the file -@file{profile.el} for instructions. +@cindex @file{elp.el} +Profile your program with the @file{elp} library. See the file +@file{elp.el} for instructions. @item Use iteration rather than recursion whenever possible. @@ -280,11 +452,11 @@ is calling another compiled function. @item Using the primitive list-searching functions @code{memq}, @code{member}, @code{assq}, or @code{assoc} is even faster than explicit iteration. It -may be worth rearranging a data structure so that one of these primitive +can be worth rearranging a data structure so that one of these primitive search functions can be used. @item -Certain built-in functions are handled specially in byte-compiled code, +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} @@ -292,23 +464,17 @@ property. If the property is non-@code{nil}, then the function is handled specially. For example, the following input will show you that @code{aref} is -compiled specially (@pxref{Array Functions}) while @code{elt} is not -(@pxref{Sequence Functions}): +compiled specially (@pxref{Array Functions}): @example @group (get 'aref 'byte-compile) @result{} byte-compile-two-args @end group - -@group -(get 'elt 'byte-compile) - @result{} nil -@end group @end example @item -If calling a small function accounts for a substantial part of your +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 @@ -319,7 +485,10 @@ the speed. @xref{Inline Functions}. @node Documentation Tips @section Tips for Documentation Strings - Here are some tips for the writing of documentation strings. +@findex checkdoc-minor-mode + Here are some tips and conventions for the writing of documentation +strings. You can check many of these conventions by running the command +@kbd{M-x checkdoc-minor-mode}. @itemize @bullet @item @@ -330,27 +499,50 @@ should have a documentation string. An internal variable or subroutine of a Lisp program might as well have a documentation string. In earlier Emacs versions, you could save space by using a comment instead of a documentation string, but that is no -longer the case. +longer the case---documentation strings now take up very little space in +a running Emacs. + +@item +Format the documentation string so that it fits in an Emacs window on an +80-column screen. It is a good idea for most lines to be no wider than +60 characters. The first line should not be wider than 67 characters +or it will look bad in the output of @code{apropos}. + +You can fill the text if that looks good. However, rather than blindly +filling the entire documentation string, you can often make it much more +readable by choosing certain line breaks with care. Use blank lines +between topics if the documentation string is long. @item The first line of the documentation string should consist of one or two complete sentences that 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. +apropos} displays just the first line, and if that line's contents don't +stand on their own, the result looks bad. In particular, start the +first line with a capital letter and end with a period. + +For a function, the first line should briefly answer the question, +``What does this function do?'' For a variable, the first line should +briefly answer the question, ``What does this value mean?'' -The documentation string can have additional lines that expand on the -details of how to use the function or variable. The additional lines -should be made up of complete sentences also, but they may be filled if -that looks good. +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 -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. +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 @@ -364,18 +556,17 @@ Instead of, ``Cause Emacs to display text in boldface,'' write just ``Display text in boldface.'' @item -Do not start or end a documentation string with whitespace. +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 -Format the documentation string so that it fits in an Emacs window on an -80-column screen. It is a good idea for most lines to be no wider than -60 characters. The first line can be wider if necessary to fit the -information that ought to be there. +Do not start or end a documentation string with whitespace. -However, rather than simply filling the entire documentation string, you -can make it much more readable by choosing line breaks with care. -Use blank lines between topics if the documentation string is long. - @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 @@ -383,6 +574,12 @@ 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 A variable's documentation string should start with @samp{*} if the variable is one that users would often want to set interactively. If @@ -396,17 +593,61 @@ 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 +The documentation string for a function that is a yes-or-no predicate +should start with words such as ``Return t if @dots{}'', to indicate +explicitly what constitutes ``truth''. The word ``return'' avoids +starting the sentence with lower-case ``t'', which is 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 -@code{/} refers to its second argument as @samp{DIVISOR}, because the -actual argument name is @code{divisor}. +@code{eval} refers to its second argument as @samp{FORM}, because the +actual argument name is @code{form}: + +@example +Evaluate FORM and return its value. +@end example + +Also write metasyntactic variables in capital letters, such as when you +show the decomposition of a list or vector into subunits, some of which +may vary. @samp{KEY} and @samp{VALUE} in the following example +illustrate this practice: + +@example +The argument TABLE should be an alist whose elements +have the form (KEY . VALUE). Here, KEY is ... +@end example + +@item +Never change the case of a Lisp symbol when you mention it in a doc +string. If the symbol's name is @code{foo}, write ``foo'', not +``Foo'' (which is a different symbol). + +This might appear to contradict the policy of writing function +argument values, but there is no real contradiction; the argument +@emph{value} is not the same thing as the @emph{symbol} which the +function uses to hold the value. -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 -vary. +If this puts a lower-case letter at the beginning of a sentence +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: + +@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}). + +@anchor{Docstring hyperlinks} @item @iftex When a documentation string refers to a Lisp symbol, write it as it @@ -414,22 +655,74 @@ would be printed (which usually means in lower case), with single-quotes around it. For example: @samp{`lambda'}. There are two exceptions: write @code{t} and @code{nil} without single-quotes. @end iftex -@ifinfo +@ifnottex When a documentation string refers to a Lisp symbol, write it as it would be printed (which usually means in lower case), with single-quotes around it. For example: @samp{lambda}. There are two exceptions: write -t and nil without single-quotes. (In this manual, we normally do use -single-quotes for those symbols.) -@end ifinfo +t and nil without single-quotes. (In this manual, we use a different +convention, with single-quotes for all symbols.) +@end ifnottex + +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 +special to make use of this feature. However, when a symbol has both a +function definition and a variable definition, and you want to refer to +just one of them, you can specify which one by writing one of the words +@samp{variable}, @samp{option}, @samp{function}, or @samp{command}, +immediately before the symbol name. (Case makes no difference in +recognizing these indicator words.) For example, if you write + +@example +This function sets the variable `buffer-file-name'. +@end example + +@noindent +then the hyperlink will refer only to the variable documentation of +@code{buffer-file-name}, and not to its function documentation. + +If a symbol has a function definition and/or a variable definition, but +those are irrelevant to the use of the symbol that you are documenting, +you can write the word @samp{symbol} before the symbol name to prevent +making any hyperlink. For example, + +@example +If the argument KIND-OF-RESULT is the symbol `list', +this function returns a list of all the objects +that satisfy the criterion. +@end example + +@noindent +does not make a hyperlink to the documentation, irrelevant here, of the +function @code{list}. + +Normally, no hyperlink is made for a variable without variable +documentation. You can force a hyperlink for such variables by +preceding them with one of the words @samp{variable} or +@samp{option}. + +Hyperlinks for faces are only made if the face name is preceded or +followed by the word @samp{face}. In that case, only the face +documentation will be shown, even if the symbol is also defined as a +variable or as a function. + +To make a hyperlink to Info documentation, write the name of the Info +node (or anchor) in single quotes, preceded by @samp{info node}, +@samp{Info node}, @samp{info anchor} or @samp{Info anchor}. The Info +file name defaults to @samp{emacs}. For example, + +@smallexample +See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'. +@end smallexample @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 -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}. +instead of writing @samp{C-f}, write the construct +@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 @@ -488,37 +781,51 @@ at that point. For example: @end group @end smallexample -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 values. - -@item ;;; -Comments that start with three semicolons, @samp{;;;}, should start at -the left margin. Such comments are used outside function definitions to -make general statements explaining the design principles of the program. -For example: +We also normally use two semicolons for comments outside functions. @smallexample @group -;;; This Lisp code is run in Emacs -;;; when it is to operate as a server -;;; for other processes. +;; This Lisp code is run in Emacs +;; when it is to operate as a server +;; for other processes. @end group @end smallexample +Every function that has no documentation string (presumably one that is +used only internally within the package it belongs to), should instead +have 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 values. + +@item ;;; +Comments that start with three semicolons, @samp{;;;}, should start at +the left margin. These are used, occasionally, for comments within +functions that should start at the margin. We also use them sometimes +for comments that are between functions---whether to use two or three +semicolons depends on whether the comment should be considered a +``heading'' by Outline minor mode. By default, comments starting with +at least three semicolons (followed by a single space and a +non-whitespace character) are considered headings, comments starting +with two or less are not. + Another use for triple-semicolon comments is for commenting out lines -within a function. We use triple-semicolons for this precisely so that -they remain at the left margin. +within a function. We use three semicolons for this precisely so that +they remain at the left margin. By default, Outline minor mode does +not consider a comment to be a heading (even if it starts with at +least three semicolons) if the semicolons are followed by at least two +spaces. Thus, if you add an introductory comment to the commented out +code, make sure to indent it by at least two spaces after the three +semicolons. @smallexample (defun foo (a) -;;; This is no longer necessary. +;;; This is no longer necessary. ;;; (force-mode-line-update) (message "Finished with %s" a)) @end smallexample +When commenting out entire functions, use two semicolons. + @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 @@ -531,7 +838,7 @@ program. For example: @noindent The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;} -(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}) +(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}), automatically indent comments according to these conventions, depending on the number of semicolons. @xref{Comments,, Manipulating Comments, emacs, The GNU Emacs Manual}. @@ -541,9 +848,23 @@ Manipulating Comments, emacs, The GNU Emacs Manual}. @cindex header comments @cindex library header comments - Emacs 19 has conventions for using special comments in Lisp libraries + Emacs has conventions for using special comments in Lisp libraries to divide them into sections and give information such as who wrote -them. This section explains these conventions. First, an example: +them. This section explains these conventions. + + We'll start with an example, a package that is included in the Emacs +distribution. + + Parts of this example reflect its status as part of Emacs; for +example, the copyright notice lists the Free Software Foundation as the +copyright holder, and the copying permission says the file is part of +Emacs. When you write a package and post it, the copyright holder would +be you (unless your employer claims to own it instead), and you should +get the suggested copying permission from the end of the GNU General +Public License itself. Don't say your file is part of Emacs +if we haven't installed it in Emacs yet! + + With that warning out of the way, on to the example: @smallexample @group @@ -560,7 +881,9 @@ them. This section explains these conventions. First, an example: ;; Keywords: docs ;; This file is part of GNU Emacs. -@var{copying permissions}@dots{} +@dots{} +;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, +;; Boston, MA 02111-1307, USA. @end group @end smallexample @@ -571,7 +894,8 @@ them. This section explains these conventions. First, an example: @end example @noindent -The description should be complete in one line. +The description should be complete in one line. If the file +needs a @samp{-*-} specification, put it after @var{description}. After the copyright notice come several @dfn{header comment} lines, each beginning with @samp{;; @var{header-name}:}. Here is a table of @@ -623,6 +947,8 @@ example). @item Keywords This line lists keywords for the @code{finder-by-keyword} help command. +Please use that command to see a list of the meaningful keywords. + This field is important; it's how people will find your package when they're looking for things by topic area. To separate the keywords, you can use spaces, commas, or both. @@ -634,19 +960,27 @@ appropriate. You can also put in header lines with other header names---they have no standard meanings, so they can't do any harm. We use additional stylized comments to subdivide the contents of the -library file. Here is a table of them: +library file. These should be separated by blank lines from anything +else. Here is a table of them: @table @samp @item ;;; Commentary: This begins introductory comments that explain how the library works. -It should come right after the copying permissions. +It should come right after the copying permissions, terminated by a +@samp{Change Log}, @samp{History} or @samp{Code} comment line. This +text is used by the Finder package, so it should make sense in that +context. + +@item ;;; Documentation: +This was used in some files in place of @samp{;;; Commentary:}, +but it is deprecated. -@item ;;; Change log: +@item ;;; Change Log: This begins change log information stored in the library file (if you -store the change history there). For most of the Lisp -files distributed with Emacs, the change history is kept in the file -@file{ChangeLog} and not in the source file at all; these files do -not have a @samp{;;; Change log:} line. +store the change history there). For Lisp files distributed with Emacs, +the change history is kept in the file @file{ChangeLog} and not in the +source file at all; these files generally do not have a @samp{;;; Change +Log:} line. @samp{History} is an alternative to @samp{Change Log}. @item ;;; Code: This begins the actual code of the program. @@ -656,3 +990,7 @@ This is the @dfn{footer line}; it appears at the very end of the file. Its purpose is to enable people to detect truncated versions of the file from the lack of a footer line. @end table + +@ignore + arch-tag: 9ea911c2-6b1d-47dd-88b7-0a94e8b27c2e +@end ignore