@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
@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
name that ends in @samp{-flag}.
@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{@}},
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},
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.
@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
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
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 @samp{Operating...} when they start, and change it to
+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 at the end.
+@emph{no} period after @samp{done}.
@item
Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e}
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.
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
@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.
@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}
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
@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
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.
+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
``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
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
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}:
-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.
+@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.
+
+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}).
@item
@iftex
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}.
+
+To make a hyperlink to Info documentation, write the name of the Info
+node in single quotes, preceded by @samp{info node} or @samp{Info
+node}. 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
@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 there is a matter of style.
+
Another use for triple-semicolon comments is for commenting out lines
-within a function. We use triple-semicolons for this precisely so that
+within a function. We use three semicolons for this precisely so that
they remain at the left margin.
@smallexample
@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}.
@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
;; 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
@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.
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 has been used in some files in place of @samp{;;; Commentary:},
+but @samp{;;; Commentary:} is preferred.
-@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.