*** empty log message ***
[emacs.git] / lispref / tips.texi
blob8854bb806141bff67e760c355826e817954773b6
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998, 1999
4 @c   Free Software Foundation, Inc. 
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/tips
7 @node Tips, GNU Emacs Internals, Copying, Top
8 @appendix Tips and Conventions
9 @cindex tips
10 @cindex standards of coding style
11 @cindex coding standards
13   This chapter describes no additional features of Emacs Lisp.  Instead
14 it gives advice on making effective use of the features described in the
15 previous chapters, and describes conventions Emacs Lisp programmers
16 should follow.
18   You can automatically check some of the conventions described below by
19 running the command @kbd{M-x checkdoc RET} when visiting a Lisp file.
20 It cannot check all of the conventions, and not all the warnings it
21 gives necessarily correspond to problems, but it is worth examining them
22 all.
24 @menu
25 * Coding Conventions::        Conventions for clean and robust programs.
26 * Compilation Tips::          Making compiled code run fast.
27 * Documentation Tips::        Writing readable documentation strings.
28 * Comment Tips::              Conventions for writing comments.
29 * Library Headers::           Standard headers for library packages.
30 @end menu
32 @node Coding Conventions
33 @section Emacs Lisp Coding Conventions
35   Here are conventions that you should follow when writing Emacs Lisp
36 code intended for widespread use:
38 @itemize @bullet
39 @item
40 Since all global variables share the same name space, and all functions
41 share another name space, you should choose a short word to distinguish
42 your program from other Lisp programs.  Then take care to begin the
43 names of all global variables, constants, and functions with the chosen
44 prefix.  This helps avoid name conflicts.
46 This recommendation applies even to names for traditional Lisp
47 primitives that are not primitives in Emacs Lisp---even to
48 @code{copy-list}.  Believe it or not, there is more than one plausible
49 way to define @code{copy-list}.  Play it safe; append your name prefix
50 to produce a name like @code{foo-copy-list} or @code{mylib-copy-list}
51 instead.
53 If you write a function that you think ought to be added to Emacs under
54 a certain name, such as @code{twiddle-files}, don't call it by that name
55 in your program.  Call it @code{mylib-twiddle-files} in your program,
56 and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add
57 it to Emacs.  If and when we do, we can change the name easily enough.
59 If one prefix is insufficient, your package may use two or three
60 alternative common prefixes, so long as they make sense.
62 Separate the prefix from the rest of the symbol name with a hyphen,
63 @samp{-}.  This will be consistent with Emacs itself and with most Emacs
64 Lisp programs.
66 @item
67 It is often useful to put a call to @code{provide} in each separate
68 library program, at least if there is more than one entry point to the
69 program.
71 @item
72 If a file requires certain other library programs to be loaded
73 beforehand, then the comments at the beginning of the file should say
74 so.  Also, use @code{require} to make sure they are loaded.
76 @item
77 If one file @var{foo} uses a macro defined in another file @var{bar},
78 @var{foo} should contain this expression before the first use of the
79 macro:
81 @example
82 (eval-when-compile (require '@var{bar}))
83 @end example
85 @noindent
86 (And the library @var{bar} should contain @code{(provide '@var{bar})},
87 to make the @code{require} work.)  This will cause @var{bar} to be
88 loaded when you byte-compile @var{foo}.  Otherwise, you risk compiling
89 @var{foo} without the necessary macro loaded, and that would produce
90 compiled code that won't work right.  @xref{Compiling Macros}.
92 Using @code{eval-when-compile} avoids loading @var{bar} when
93 the compiled version of @var{foo} is @emph{used}.
95 @item
96 Please don't require the @code{cl} package of Common Lisp extensions at
97 run time.  Use of this package is optional, and it is not part of the
98 standard Emacs namespace.  If your package loads @code{cl} at run time,
99 that could cause name clashes for users who don't use that package.
101 However, there is no problem with using the @code{cl} package at compile
102 time, for the sake of macros.  You do that like this:
104 @example
105 (eval-when-compile (require 'cl))
106 @end example
108 @item
109 When defining a major mode, please follow the major mode
110 conventions.  @xref{Major Mode Conventions}.
112 @item
113 When defining a minor mode, please follow the minor mode
114 conventions.  @xref{Minor Mode Conventions}.
116 @item
117 If the purpose of a function is to tell you whether a certain condition
118 is true or false, give the function a name that ends in @samp{p}.  If
119 the name is one word, add just @samp{p}; if the name is multiple words,
120 add @samp{-p}.  Examples are @code{framep} and @code{frame-live-p}.
122 @item
123 If a user option variable records a true-or-false condition, give it a
124 name that ends in @samp{-flag}.
126 @item
127 @cindex reserved keys
128 @cindex keys, reserved
129 Please do not define @kbd{C-c @var{letter}} as a key in your major
130 modes.  These sequences are reserved for users; they are the
131 @strong{only} sequences reserved for users, so do not block them.
133 Instead, define sequences consisting of @kbd{C-c} followed by a control
134 character, a digit, or certain punctuation characters.  These sequences
135 are reserved for major modes.
137 Changing all the Emacs major modes to follow this convention was a lot
138 of work.  Abandoning this convention would make that work go to waste,
139 and inconvenience users.
141 @item
142 Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
143 @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes.
145 @item
146 Sequences consisting of @kbd{C-c} followed by any other punctuation
147 character are allocated for minor modes.  Using them in a major mode is
148 not absolutely prohibited, but if you do that, the major mode binding
149 may be shadowed from time to time by minor modes.
151 @item
152 Function keys @key{F5} through @key{F9} without modifier keys are
153 reserved for users to define.
155 @item
156 Do not bind @kbd{C-h} following any prefix character (including
157 @kbd{C-c}).  If you don't bind @kbd{C-h}, it is automatically available
158 as a help character for listing the subcommands of the prefix character.
160 @item
161 Do not bind a key sequence ending in @key{ESC} except following
162 another @key{ESC}.  (That is, it is OK to bind a sequence ending in
163 @kbd{@key{ESC} @key{ESC}}.)
165 The reason for this rule is that a non-prefix binding for @key{ESC} in
166 any context prevents recognition of escape sequences as function keys in
167 that context.
169 @item
170 Anything which acts like a temporary mode or state which the user can
171 enter and leave should define @kbd{@key{ESC} @key{ESC}} or
172 @kbd{@key{ESC} @key{ESC} @key{ESC}} as a way to escape.
174 For a state which accepts ordinary Emacs commands, or more generally any
175 kind of state in which @key{ESC} followed by a function key or arrow key
176 is potentially meaningful, then you must not define @kbd{@key{ESC}
177 @key{ESC}}, since that would preclude recognizing an escape sequence
178 after @key{ESC}.  In these states, you should define @kbd{@key{ESC}
179 @key{ESC} @key{ESC}} as the way to escape.  Otherwise, define
180 @kbd{@key{ESC} @key{ESC}} instead.
182 @item
183 Applications should not bind mouse events based on button 1 with the
184 shift key held down.  These events include @kbd{S-mouse-1},
185 @kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on.  They are reserved for
186 users.
188 @item
189 Special major modes used for read-only text should usually redefine
190 @kbd{mouse-2} and @key{RET} to trace some sort of reference in the text.
191 Modes such as Dired, Info, Compilation, and Occur redefine it in this
192 way.
194 @item
195 When a package provides a modification of ordinary Emacs behavior, it is
196 good to include a command to enable and disable the feature, Provide a
197 command named @code{@var{whatever}-mode} which turns the feature on or
198 off, and make it autoload (@pxref{Autoload}).  Design the package so
199 that simply loading it has no visible effect---that should not enable
200 the feature.  Users will request the feature by invoking the command.
202 @item
203 It is a bad idea to define aliases for the Emacs primitives.  Use the
204 standard names instead.
206 @item
207 Redefining (or advising) an Emacs primitive is discouraged.  It may do
208 the right thing for a particular program, but there is no telling what
209 other programs might break as a result.
211 @item
212 If a file does replace any of the functions or library programs of
213 standard Emacs, prominent comments at the beginning of the file should
214 say which functions are replaced, and how the behavior of the
215 replacements differs from that of the originals.
217 @item
218 Please keep the names of your Emacs Lisp source files to 13 characters
219 or less.  This way, if the files are compiled, the compiled files' names
220 will be 14 characters or less, which is short enough to fit on all kinds
221 of Unix systems.
223 @item
224 Don't use @code{next-line} or @code{previous-line} in programs; nearly
225 always, @code{forward-line} is more convenient as well as more
226 predictable and robust.  @xref{Text Lines}.
228 @item
229 Don't call functions that set the mark, unless setting the mark is one
230 of the intended features of your program.  The mark is a user-level
231 feature, so it is incorrect to change the mark except to supply a value
232 for the user's benefit.  @xref{The Mark}.
234 In particular, don't use any of these functions:
236 @itemize @bullet
237 @item
238 @code{beginning-of-buffer}, @code{end-of-buffer}
239 @item
240 @code{replace-string}, @code{replace-regexp}
241 @end itemize
243 If you just want to move point, or replace a certain string, without any
244 of the other features intended for interactive users, you can replace
245 these functions with one or two lines of simple Lisp code.
247 @item
248 Use lists rather than vectors, except when there is a particular reason
249 to use a vector.  Lisp has more facilities for manipulating lists than
250 for vectors, and working with lists is usually more convenient.
252 Vectors are advantageous for tables that are substantial in size and are
253 accessed in random order (not searched front to back), provided there is
254 no need to insert or delete elements (only lists allow that).
256 @item
257 The recommended way to print a message in the echo area is with
258 the @code{message} function, not @code{princ}.  @xref{The Echo Area}.
260 @item
261 When you encounter an error condition, call the function @code{error}
262 (or @code{signal}).  The function @code{error} does not return.
263 @xref{Signaling Errors}.
265 Do not use @code{message}, @code{throw}, @code{sleep-for},
266 or @code{beep} to report errors.
268 @item
269 An error message should start with a capital letter but should not end
270 with a period.
272 @item
273 Many commands that take a long time to execute display a message that
274 says @samp{Operating...} when they start, and change it to
275 @samp{Operating...done} when they finish.  Please keep the style of
276 these messages uniform: @emph{no} space around the ellipsis, and
277 @emph{no} period at the end.
279 @item
280 Try to avoid using recursive edits.  Instead, do what the Rmail @kbd{e}
281 command does: use a new local keymap that contains one command defined
282 to switch back to the old local keymap.  Or do what the
283 @code{edit-options} command does: switch to another buffer and let the
284 user switch back at will.  @xref{Recursive Editing}.
286 @item
287 In some other systems there is a convention of choosing variable names
288 that begin and end with @samp{*}.  We don't use that convention in Emacs
289 Lisp, so please don't use it in your programs.  (Emacs uses such names
290 only for special-purpose buffers.)  The users will find Emacs more
291 coherent if all libraries use the same conventions.
293 @item
294 Try to avoid compiler warnings about undefined free variables, by adding
295 @code{defvar} definitions for these variables.
297 Sometimes adding a @code{require} for another package is useful to avoid
298 compilation warnings for variables and functions defined in that
299 package.  If you do this, often it is better if the @code{require} acts
300 only at compile time.  Here's how to do that:
302 @example
303 (eval-when-compile
304   (require 'foo)
305   (defvar bar-baz))
306 @end example
308 If you bind a variable in one function, and use it or set it in another
309 function, the compiler warns about the latter function unless the
310 variable has a definition.  But often these variables have short names,
311 and it is not clean for Lisp packages to define such variable names.
312 Therefore, you should rename the variable to start with the name prefix
313 used for the other functions and variables in your package.
315 @item
316 Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
317 default indentation parameters.
319 @item
320 Don't make a habit of putting close-parentheses on lines by themselves;
321 Lisp programmers find this disconcerting.  Once in a while, when there
322 is a sequence of many consecutive close-parentheses, it may make sense
323 to split the sequence in one or two significant places.
325 @item
326 Please put a copyright notice on the file if you give copies to anyone.
327 Use a message like this one:
329 @smallexample
330 ;; Copyright (C) @var{year} @var{name}
332 ;; This program is free software; you can redistribute it and/or
333 ;; modify it under the terms of the GNU General Public License as
334 ;; published by the Free Software Foundation; either version 2 of
335 ;; the License, or (at your option) any later version.
337 ;; This program is distributed in the hope that it will be
338 ;; useful, but WITHOUT ANY WARRANTY; without even the implied
339 ;; warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
340 ;; PURPOSE.  See the GNU General Public License for more details.
342 ;; You should have received a copy of the GNU General Public
343 ;; License along with this program; if not, write to the Free
344 ;; Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
345 ;; MA 02111-1307 USA
346 @end smallexample
348 If you have signed papers to assign the copyright to the Foundation,
349 then use @samp{Free Software Foundation, Inc.} as @var{name}.
350 Otherwise, use your name.
351 @end itemize
353 @node Compilation Tips
354 @section Tips for Making Compiled Code Fast
355 @cindex execution speed
356 @cindex speedups
358   Here are ways of improving the execution speed of byte-compiled
359 Lisp programs.
361 @itemize @bullet
362 @item
363 @cindex profiling
364 @cindex timing programs
365 @cindex @file{profile.el}
366 @cindex @file{elp.el}
367 Profile your program with the @file{profile} library or the @file{elp}
368 library.  See the files @file{profile.el} and @file{elp.el} for
369 instructions.
371 @item
372 Use iteration rather than recursion whenever possible.
373 Function calls are slow in Emacs Lisp even when a compiled function
374 is calling another compiled function.
376 @item
377 Using the primitive list-searching functions @code{memq}, @code{member},
378 @code{assq}, or @code{assoc} is even faster than explicit iteration.  It
379 can be worth rearranging a data structure so that one of these primitive
380 search functions can be used.
382 @item
383 Certain built-in functions are handled specially in byte-compiled code, 
384 avoiding the need for an ordinary function call.  It is a good idea to
385 use these functions rather than alternatives.  To see whether a function
386 is handled specially by the compiler, examine its @code{byte-compile}
387 property.  If the property is non-@code{nil}, then the function is
388 handled specially.
390 For example, the following input will show you that @code{aref} is
391 compiled specially (@pxref{Array Functions}):
393 @example
394 @group
395 (get 'aref 'byte-compile)
396      @result{} byte-compile-two-args
397 @end group
398 @end example
400 @item
401 If calling a small function accounts for a substantial part of your
402 program's running time, make the function inline.  This eliminates
403 the function call overhead.  Since making a function inline reduces
404 the flexibility of changing the program, don't do it unless it gives
405 a noticeable speedup in something slow enough that users care about
406 the speed.  @xref{Inline Functions}.
407 @end itemize
409 @node Documentation Tips
410 @section Tips for Documentation Strings
412 @findex checkdoc-minor-mode
413   Here are some tips and conventions for the writing of documentation
414 strings.  You can check many of these conventions by running the command
415 @kbd{M-x checkdoc-minor-mode}.
417 @itemize @bullet
418 @item
419 Every command, function, or variable intended for users to know about
420 should have a documentation string.
422 @item
423 An internal variable or subroutine of a Lisp program might as well have
424 a documentation string.  In earlier Emacs versions, you could save space
425 by using a comment instead of a documentation string, but that is no
426 longer the case---documentation strings now take up very little space in
427 a running Emacs.
429 @item
430 The first line of the documentation string should consist of one or two
431 complete sentences that stand on their own as a summary.  @kbd{M-x
432 apropos} displays just the first line, and if that line's contents don't
433 stand on their own, the result looks bad.  In particular, start the
434 first line with a capital letter and end with a period.
436 The documentation string is not limited to one line; use as many lines
437 as you need to explain the details of how to use the function or
438 variable.  Please use complete sentences in the additional lines.
440 @item
441 For consistency, phrase the verb in the first sentence of a function's
442 documentation string as an imperative--for instance, use ``Return the
443 cons of A and B.'' in preference to ``Returns the cons of A and B@.''
444 Usually it looks good to do likewise for the rest of the first
445 paragraph.  Subsequent paragraphs usually look better if each sentence
446 has a proper subject.
448 @item
449 Write documentation strings in the active voice, not the passive, and in
450 the present tense, not the future.  For instance, use ``Return a list
451 containing A and B.'' instead of ``A list containing A and B will be
452 returned.''
454 @item
455 Avoid using the word ``cause'' (or its equivalents) unnecessarily.
456 Instead of, ``Cause Emacs to display text in boldface,'' write just
457 ``Display text in boldface.''
459 @item
460 When a command is meaningful only in a certain mode or situation,
461 do mention that in the documentation string.  For example,
462 the documentation of @code{dired-find-file} is:
464 @example
465 In Dired, visit the file or directory named on this line.
466 @end example
468 @item
469 Do not start or end a documentation string with whitespace.
471 @item
472 Format the documentation string so that it fits in an Emacs window on an
473 80-column screen.  It is a good idea for most lines to be no wider than
474 60 characters.  The first line should not be wider than 67 characters
475 or it will look bad in the output of @code{apropos}.
477 You can fill the text if that looks good.  However, rather than blindly
478 filling the entire documentation string, you can often make it much more
479 readable by choosing certain line breaks with care.  Use blank lines
480 between topics if the documentation string is long.
482 @item
483 @strong{Do not} indent subsequent lines of a documentation string so
484 that the text is lined up in the source code with the text of the first
485 line.  This looks nice in the source code, but looks bizarre when users
486 view the documentation.  Remember that the indentation before the
487 starting double-quote is not part of the string!
489 @item
490 When the user tries to use a disabled command, Emacs displays just the
491 first paragraph of its documentation string---everything through the
492 first blank line.  If you wish, you can choose which information to
493 include before the first blank line so as to make this display useful.
495 @item
496 A variable's documentation string should start with @samp{*} if the
497 variable is one that users would often want to set interactively.  If
498 the value is a long list, or a function, or if the variable would be set
499 only in init files, then don't start the documentation string with
500 @samp{*}.  @xref{Defining Variables}.
502 @item
503 The documentation string for a variable that is a yes-or-no flag should
504 start with words such as ``Non-nil means@dots{}'', to make it clear that
505 all non-@code{nil} values are equivalent and indicate explicitly what
506 @code{nil} and non-@code{nil} mean.
508 @item
509 When a function's documentation string mentions the value of an argument
510 of the function, use the argument name in capital letters as if it were
511 a name for that value.  Thus, the documentation string of the function
512 @code{eval} refers to its second argument as @samp{FORM}, because the
513 actual argument name is @code{form}:
515 @example
516 Evaluate FORM and return its value.
517 @end example
519 Also write metasyntactic variables in capital letters, such as when you
520 show the decomposition of a list or vector into subunits, some of which
521 may vary.  @samp{KEY} and @samp{VALUE} in the following example
522 illustrate this practice:
524 @example
525 The argument TABLE should be an alist whose elements
526 have the form (KEY . VALUE).  Here, KEY is ...
527 @end example
529 @item
530 If a line in a documentation string begins with an open-parenthesis,
531 write a backslash before the open-parenthesis, like this:
533 @example
534 The argument FOO can be either a number
535 \(a buffer position) or a string (a file name).
536 @end example
538 This prevents the open-parenthesis from being treated as the start of a
539 defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
541 @item
542 @iftex
543 When a documentation string refers to a Lisp symbol, write it as it
544 would be printed (which usually means in lower case), with single-quotes
545 around it.  For example: @samp{`lambda'}.  There are two exceptions:
546 write @code{t} and @code{nil} without single-quotes.
547 @end iftex
548 @ifnottex
549 When a documentation string refers to a Lisp symbol, write it as it
550 would be printed (which usually means in lower case), with single-quotes
551 around it.  For example: @samp{lambda}.  There are two exceptions: write
552 t and nil without single-quotes.  (In this manual, we use a different
553 convention, with single-quotes for all symbols.)
554 @end ifnottex
556 Help mode automatically creates a hyperlink when a documentation string
557 uses a symbol name inside single quotes, if the symbol has either a
558 function or a variable definition.  You do not need to do anything
559 special to make use of this feature.  However, when a symbol has both a
560 function definition and a variable definition, and you want to refer to
561 just one of them, you can specify which one by writing one of the words
562 @samp{variable}, @samp{option}, @samp{function}, or @samp{command},
563 immediately before the symbol name.  (Case makes no difference in
564 recognizing these indicator words.)  For example, if you write
566 @example
567 This function sets the variable `buffer-file-name'.
568 @end example
570 @noindent
571 then the hyperlink will refer only to the variable documentation of
572 @code{buffer-file-name}, and not to its function documentation.
574 If a symbol has a function definition and/or a variable definition, but
575 those are irrelevant to the use of the symbol that you are documenting,
576 you can write the word @samp{symbol} before the symbol name to prevent
577 making any hyperlink.  For example,
579 @example
580 If the argument KIND-OF-RESULT is the symbol `list',
581 this function returns a list of all the objects
582 that satisfy the criterion.
583 @end example
585 @noindent
586 does not make a hyperlink to the documentation, irrelevant here, of the
587 function @code{list}.
589 To make a hyperlink to Info documentation, write the name of the Info
590 node in single quotes, preceded by @samp{info node} or @samp{Info
591 node}.  The Info file name defaults to @samp{emacs}.  For example,
593 @smallexample
594 See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
595 @end smallexample
597 @item
598 Don't write key sequences directly in documentation strings.  Instead,
599 use the @samp{\\[@dots{}]} construct to stand for them.  For example,
600 instead of writing @samp{C-f}, write the construct
601 @samp{\\[forward-char]}.  When Emacs displays the documentation string,
602 it substitutes whatever key is currently bound to @code{forward-char}.
603 (This is normally @samp{C-f}, but it may be some other character if the
604 user has moved key bindings.)  @xref{Keys in Documentation}.
606 @item
607 In documentation strings for a major mode, you will want to refer to the
608 key bindings of that mode's local map, rather than global ones.
609 Therefore, use the construct @samp{\\<@dots{}>} once in the
610 documentation string to specify which key map to use.  Do this before
611 the first use of @samp{\\[@dots{}]}.  The text inside the
612 @samp{\\<@dots{}>} should be the name of the variable containing the
613 local keymap for the major mode.
615 It is not practical to use @samp{\\[@dots{}]} very many times, because
616 display of the documentation string will become slow.  So use this to
617 describe the most important commands in your major mode, and then use
618 @samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
619 @end itemize
621 @node Comment Tips
622 @section Tips on Writing Comments
624   We recommend these conventions for where to put comments and how to
625 indent them:
627 @table @samp
628 @item ;
629 Comments that start with a single semicolon, @samp{;}, should all be
630 aligned to the same column on the right of the source code.  Such
631 comments usually explain how the code on the same line does its job.  In
632 Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment})
633 command automatically inserts such a @samp{;} in the right place, or
634 aligns such a comment if it is already present.
636 This and following examples are taken from the Emacs sources.
638 @smallexample
639 @group
640 (setq base-version-list                 ; there was a base
641       (assoc (substring fn 0 start-vn)  ; version to which
642              file-version-assoc-list))  ; this looks like
643                                         ; a subversion
644 @end group
645 @end smallexample
647 @item ;;
648 Comments that start with two semicolons, @samp{;;}, should be aligned to
649 the same level of indentation as the code.  Such comments usually
650 describe the purpose of the following lines or the state of the program
651 at that point.  For example:
653 @smallexample
654 @group
655 (prog1 (setq auto-fill-function
656              @dots{}
657              @dots{}
658   ;; update mode line
659   (force-mode-line-update)))
660 @end group
661 @end smallexample
663 We also normally use two semicolons for comments outside functions.
665 @smallexample
666 @group
667 ;; This Lisp code is run in Emacs
668 ;; when it is to operate as a server
669 ;; for other processes.
670 @end group
671 @end smallexample
673 Every function that has no documentation string (presumably one that is
674 used only internally within the package it belongs to), should instead
675 have a two-semicolon comment right before the function, explaining what
676 the function does and how to call it properly.  Explain precisely what
677 each argument means and how the function interprets its possible values.
679 @item ;;;
680 Comments that start with three semicolons, @samp{;;;}, should start at
681 the left margin.  These are used, occasionally, for comments within
682 functions that should start at the margin.  We also use them sometimes
683 for comments that are between functions---whether to use two or three
684 semicolons there is a matter of style.
686 Another use for triple-semicolon comments is for commenting out lines
687 within a function.  We use three semicolons for this precisely so that
688 they remain at the left margin.
690 @smallexample
691 (defun foo (a)
692 ;;; This is no longer necessary.
693 ;;;  (force-mode-line-update)
694   (message "Finished with %s" a))
695 @end smallexample
697 @item ;;;;
698 Comments that start with four semicolons, @samp{;;;;}, should be aligned
699 to the left margin and are used for headings of major sections of a
700 program.  For example:
702 @smallexample
703 ;;;; The kill ring
704 @end smallexample
705 @end table
707 @noindent
708 The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;}
709 (@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}),
710 automatically indent comments according to these conventions,
711 depending on the number of semicolons.  @xref{Comments,,
712 Manipulating Comments, emacs, The GNU Emacs Manual}.
714 @node Library Headers
715 @section Conventional Headers for Emacs Libraries
716 @cindex header comments
717 @cindex library header comments
719   Emacs has conventions for using special comments in Lisp libraries
720 to divide them into sections and give information such as who wrote
721 them.  This section explains these conventions.
723   We'll start with an example, a package that is included in the Emacs
724 distribution.
726   Parts of this example reflect its status as part of Emacs; for
727 example, the copyright notice lists the Free Software Foundation as the
728 copyright holder, and the copying permission says the file is part of
729 Emacs.  When you write a package and post it, the copyright holder would
730 be you (unless your employer claims to own it instead), and you should
731 get the suggested copying permission from the end of the GNU General
732 Public License itself.  Don't say your file is part of Emacs
733 if we haven't installed it in Emacs yet!
735   With that warning out of the way, on to the example:
737 @smallexample
738 @group
739 ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
741 ;; Copyright (C) 1992 Free Software Foundation, Inc.
742 @end group
744 ;; Author: Eric S. Raymond <esr@@snark.thyrsus.com>
745 ;; Maintainer: Eric S. Raymond <esr@@snark.thyrsus.com>
746 ;; Created: 14 Jul 1992
747 ;; Version: 1.2
748 @group
749 ;; Keywords: docs
751 ;; This file is part of GNU Emacs.
752 @dots{}
753 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
754 ;; Boston, MA 02111-1307, USA.
755 @end group
756 @end smallexample
758   The very first line should have this format:
760 @example
761 ;;; @var{filename} --- @var{description}
762 @end example
764 @noindent
765 The description should be complete in one line.
767   After the copyright notice come several @dfn{header comment} lines,
768 each beginning with @samp{;; @var{header-name}:}.  Here is a table of
769 the conventional possibilities for @var{header-name}:
771 @table @samp
772 @item Author
773 This line states the name and net address of at least the principal
774 author of the library.
776 If there are multiple authors, you can list them on continuation lines
777 led by @code{;;} and a tab character, like this:
779 @smallexample
780 @group
781 ;; Author: Ashwin Ram <Ram-Ashwin@@cs.yale.edu>
782 ;;      Dave Sill <de5@@ornl.gov>
783 ;;      Dave Brennan <brennan@@hal.com>
784 ;;      Eric Raymond <esr@@snark.thyrsus.com>
785 @end group
786 @end smallexample
788 @item Maintainer
789 This line should contain a single name/address as in the Author line, or
790 an address only, or the string @samp{FSF}.  If there is no maintainer
791 line, the person(s) in the Author field are presumed to be the
792 maintainers.  The example above is mildly bogus because the maintainer
793 line is redundant.
795 The idea behind the @samp{Author} and @samp{Maintainer} lines is to make
796 possible a Lisp function to ``send mail to the maintainer'' without
797 having to mine the name out by hand.
799 Be sure to surround the network address with @samp{<@dots{}>} if
800 you include the person's full name as well as the network address.
802 @item Created
803 This optional line gives the original creation date of the
804 file.  For historical interest only.
806 @item Version
807 If you wish to record version numbers for the individual Lisp program, put
808 them in this line.
810 @item Adapted-By
811 In this header line, place the name of the person who adapted the
812 library for installation (to make it fit the style conventions, for
813 example).
815 @item Keywords
816 This line lists keywords for the @code{finder-by-keyword} help command.
817 Please use that command to see a list of the meaningful keywords.
819 This field is important; it's how people will find your package when
820 they're looking for things by topic area.  To separate the keywords, you
821 can use spaces, commas, or both.
822 @end table
824   Just about every Lisp library ought to have the @samp{Author} and
825 @samp{Keywords} header comment lines.  Use the others if they are
826 appropriate.  You can also put in header lines with other header
827 names---they have no standard meanings, so they can't do any harm.
829   We use additional stylized comments to subdivide the contents of the
830 library file.  These should be separated by blank lines from anything
831 else.  Here is a table of them:
833 @table @samp
834 @item ;;; Commentary:
835 This begins introductory comments that explain how the library works.
836 It should come right after the copying permissions, terminated by a
837 @samp{Change Log}, @samp{History} or @samp{Code} comment line.  This
838 text is used by the Finder package, so it should make sense in that
839 context.
841 @item ;;; Documentation
842 This has been used in some files in place of @samp{;;; Commentary:},
843 but @samp{;;; Commentary:} is preferred.
845 @item ;;; Change Log:
846 This begins change log information stored in the library file (if you
847 store the change history there).  For Lisp files distributed with Emacs,
848 the change history is kept in the file @file{ChangeLog} and not in the
849 source file at all; these files generally do not have a @samp{;;; Change
850 Log:} line.  @samp{History} is an alternative to @samp{Change Log}.
852 @item ;;; Code:
853 This begins the actual code of the program.
855 @item ;;; @var{filename} ends here
856 This is the @dfn{footer line}; it appears at the very end of the file.
857 Its purpose is to enable people to detect truncated versions of the file
858 from the lack of a footer line.
859 @end table