2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998, 1999, 2002, 2003,
4 @c 2004, 2005, 2006 Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/tips
7 @node Tips, GNU Emacs Internals, GPL, Top
8 @appendix Tips and Conventions
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
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
25 * Coding Conventions:: Conventions for clean and robust programs.
26 * Key Binding Conventions:: Which keys should be bound by which programs.
27 * Programming Tips:: Making Emacs code fit smoothly in Emacs.
28 * Compilation Tips:: Making compiled code run fast.
29 * Warning Tips:: Turning off compiler warnings.
30 * Documentation Tips:: Writing readable documentation strings.
31 * Comment Tips:: Conventions for writing comments.
32 * Library Headers:: Standard headers for library packages.
35 @node Coding Conventions
36 @section Emacs Lisp Coding Conventions
38 @cindex coding conventions in Emacs Lisp
39 Here are conventions that you should follow when writing Emacs Lisp
40 code intended for widespread use:
44 Simply loading the package should not change Emacs's editing behavior.
45 Include a command or commands to enable and disable the feature,
48 This convention is mandatory for any file that includes custom
49 definitions. If fixing such a file to follow this convention requires
50 an incompatible change, go ahead and make the incompatible change;
54 Since all global variables share the same name space, and all
55 functions share another name space, you should choose a short word to
56 distinguish your program from other Lisp programs@footnote{The
57 benefits of a Common Lisp-style package system are considered not to
58 outweigh the costs.}. Then take care to begin the names of all global
59 variables, constants, and functions in your program with the chosen
60 prefix. This helps avoid name conflicts.
62 Occasionally, for a command name intended for users to use, it is more
63 convenient if some words come before the package's name prefix. And
64 constructs that define functions, variables, etc., work better if they
65 start with @samp{defun} or @samp{defvar}, so put the name prefix later
68 This recommendation applies even to names for traditional Lisp
69 primitives that are not primitives in Emacs Lisp---such as
70 @code{copy-list}. Believe it or not, there is more than one plausible
71 way to define @code{copy-list}. Play it safe; append your name prefix
72 to produce a name like @code{foo-copy-list} or @code{mylib-copy-list}
75 If you write a function that you think ought to be added to Emacs under
76 a certain name, such as @code{twiddle-files}, don't call it by that name
77 in your program. Call it @code{mylib-twiddle-files} in your program,
78 and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add
79 it to Emacs. If and when we do, we can change the name easily enough.
81 If one prefix is insufficient, your package can use two or three
82 alternative common prefixes, so long as they make sense.
84 Separate the prefix from the rest of the symbol name with a hyphen,
85 @samp{-}. This will be consistent with Emacs itself and with most Emacs
89 Put a call to @code{provide} at the end of each separate Lisp file.
92 If a file requires certain other Lisp programs to be loaded
93 beforehand, then the comments at the beginning of the file should say
94 so. Also, use @code{require} to make sure they are loaded.
97 If one file @var{foo} uses a macro defined in another file @var{bar},
98 @var{foo} should contain this expression before the first use of the
102 (eval-when-compile (require '@var{bar}))
106 (And the library @var{bar} should contain @code{(provide '@var{bar})},
107 to make the @code{require} work.) This will cause @var{bar} to be
108 loaded when you byte-compile @var{foo}. Otherwise, you risk compiling
109 @var{foo} without the necessary macro loaded, and that would produce
110 compiled code that won't work right. @xref{Compiling Macros}.
112 Using @code{eval-when-compile} avoids loading @var{bar} when
113 the compiled version of @var{foo} is @emph{used}.
116 Please don't require the @code{cl} package of Common Lisp extensions at
117 run time. Use of this package is optional, and it is not part of the
118 standard Emacs namespace. If your package loads @code{cl} at run time,
119 that could cause name clashes for users who don't use that package.
121 However, there is no problem with using the @code{cl} package at compile
122 time, with @code{(eval-when-compile (require 'cl))}.
125 When defining a major mode, please follow the major mode
126 conventions. @xref{Major Mode Conventions}.
129 When defining a minor mode, please follow the minor mode
130 conventions. @xref{Minor Mode Conventions}.
133 If the purpose of a function is to tell you whether a certain condition
134 is true or false, give the function a name that ends in @samp{p}. If
135 the name is one word, add just @samp{p}; if the name is multiple words,
136 add @samp{-p}. Examples are @code{framep} and @code{frame-live-p}.
139 If a user option variable records a true-or-false condition, give it a
140 name that ends in @samp{-flag}.
143 If the purpose of a variable is to store a single function, give it a
144 name that ends in @samp{-function}. If the purpose of a variable is
145 to store a list of functions (i.e., the variable is a hook), please
146 follow the naming conventions for hooks. @xref{Hooks}.
149 @cindex unloading packages
150 If loading the file adds functions to hooks, define a function
151 @code{@var{feature}-unload-hook}, where @var{feature} is the name of
152 the feature the package provides, and make it undo any such changes.
153 Using @code{unload-feature} to unload the file will run this function.
157 It is a bad idea to define aliases for the Emacs primitives. Normally
158 you should use the standard names instead. The case where an alias
159 may be useful is where it facilitates backwards compatibility or
163 If a package needs to define an alias or a new function for
164 compatibility with some other version of Emacs, name it with the package
165 prefix, not with the raw name with which it occurs in the other version.
166 Here is an example from Gnus, which provides many examples of such
167 compatibility issues.
170 (defalias 'gnus-point-at-bol
171 (if (fboundp 'point-at-bol)
173 'line-beginning-position))
177 Redefining (or advising) an Emacs primitive is a bad idea. It may do
178 the right thing for a particular program, but there is no telling what
179 other programs might break as a result. In any case, it is a problem
180 for debugging, because the two advised function doesn't do what its
181 source code says it does. If the programmer investigating the problem
182 is unaware that there is advice on the function, the experience can be
185 We hope to remove all the places in Emacs that advise primitives.
186 In the mean time, please don't add any more.
189 It is likewise a bad idea for one Lisp package to advise a function
190 in another Lisp package.
193 Likewise, avoid using @code{eval-after-load} (@pxref{Hooks for
194 Loading}) in libraries and packages. This feature is meant for
195 personal customizations; using it in a Lisp program is unclean because
196 it modifies the behavior of another Lisp file in an invisible way.
197 This is an obstacle for debugging, much like advising a function in
201 If a file does replace any of the functions or library programs of
202 standard Emacs, prominent comments at the beginning of the file should
203 say which functions are replaced, and how the behavior of the
204 replacements differs from that of the originals.
207 Constructs that define a function or variable should be macros,
208 not functions, and their names should start with @samp{def}.
211 Macros that define a functions or variables should take the name to be
212 defined as the first argument. That will help various tools find the
213 definition automatically. Avoid constructing the names in the macro
214 itself, since that would confuse these tools.
217 Please keep the names of your Emacs Lisp source files to 13 characters
218 or less. This way, if the files are compiled, the compiled files' names
219 will be 14 characters or less, which is short enough to fit on all kinds
223 In some other systems there is a convention of choosing variable names
224 that begin and end with @samp{*}. We don't use that convention in Emacs
225 Lisp, so please don't use it in your programs. (Emacs uses such names
226 only for special-purpose buffers.) The users will find Emacs more
227 coherent if all libraries use the same conventions.
230 If your program contains non-ASCII characters in string or character
231 constants, you should make sure Emacs always decodes these characters
232 the same way, regardless of the user's settings. There are two ways
237 Use coding system @code{emacs-mule}, and specify that for
238 @code{coding} in the @samp{-*-} line or the local variables list.
241 ;; XXX.el -*- coding: emacs-mule; -*-
245 Use one of the coding systems based on ISO 2022 (such as
246 iso-8859-@var{n} and iso-2022-7bit), and specify it with @samp{!} at
247 the end for @code{coding}. (The @samp{!} turns off any possible
248 character translation.)
251 ;; XXX.el -*- coding: iso-latin-2!; -*-
256 Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
257 default indentation parameters.
260 Don't make a habit of putting close-parentheses on lines by themselves;
261 Lisp programmers find this disconcerting. Once in a while, when there
262 is a sequence of many consecutive close-parentheses, it may make sense
263 to split the sequence in one or two significant places.
266 Please put a copyright notice and copying permission notice on the
267 file if you distribute copies. Use a notice like this one:
270 ;; Copyright (C) @var{year} @var{name}
272 ;; This program is free software; you can redistribute it and/or
273 ;; modify it under the terms of the GNU General Public License as
274 ;; published by the Free Software Foundation; either version 2 of
275 ;; the License, or (at your option) any later version.
277 ;; This program is distributed in the hope that it will be
278 ;; useful, but WITHOUT ANY WARRANTY; without even the implied
279 ;; warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
280 ;; PURPOSE. See the GNU General Public License for more details.
282 ;; You should have received a copy of the GNU General Public
283 ;; License along with this program; if not, write to the Free
284 ;; Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
288 If you have signed papers to assign the copyright to the Foundation,
289 then use @samp{Free Software Foundation, Inc.} as @var{name}.
290 Otherwise, use your name. See also @xref{Library Headers}.
293 @node Key Binding Conventions
294 @section Key Binding Conventions
299 @cindex references, following
300 Special major modes used for read-only text should usually redefine
301 @kbd{mouse-2} and @key{RET} to trace some sort of reference in the text.
302 Modes such as Dired, Info, Compilation, and Occur redefine it in this
305 In addition, they should mark the text as a kind of ``link'' so that
306 @kbd{mouse-1} will follow it also. @xref{Links and Mouse-1}.
309 @cindex reserved keys
310 @cindex keys, reserved
311 Please do not define @kbd{C-c @var{letter}} as a key in Lisp programs.
312 Sequences consisting of @kbd{C-c} and a letter (either upper or lower
313 case) are reserved for users; they are the @strong{only} sequences
314 reserved for users, so do not block them.
316 Changing all the Emacs major modes to respect this convention was a
317 lot of work; abandoning this convention would make that work go to
318 waste, and inconvenience users. Please comply with it.
321 Function keys @key{F5} through @key{F9} without modifier keys are
322 also reserved for users to define.
325 Applications should not bind mouse events based on button 1 with the
326 shift key held down. These events include @kbd{S-mouse-1},
327 @kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on. They are reserved for
331 Sequences consisting of @kbd{C-c} followed by a control character or a
332 digit are reserved for major modes.
335 Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
336 @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes.
339 Sequences consisting of @kbd{C-c} followed by any other punctuation
340 character are allocated for minor modes. Using them in a major mode is
341 not absolutely prohibited, but if you do that, the major mode binding
342 may be shadowed from time to time by minor modes.
345 Do not bind @kbd{C-h} following any prefix character (including
346 @kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically available
347 as a help character for listing the subcommands of the prefix character.
350 Do not bind a key sequence ending in @key{ESC} except following
351 another @key{ESC}. (That is, it is OK to bind a sequence ending in
352 @kbd{@key{ESC} @key{ESC}}.)
354 The reason for this rule is that a non-prefix binding for @key{ESC} in
355 any context prevents recognition of escape sequences as function keys in
359 Anything which acts like a temporary mode or state which the user can
360 enter and leave should define @kbd{@key{ESC} @key{ESC}} or
361 @kbd{@key{ESC} @key{ESC} @key{ESC}} as a way to escape.
363 For a state which accepts ordinary Emacs commands, or more generally any
364 kind of state in which @key{ESC} followed by a function key or arrow key
365 is potentially meaningful, then you must not define @kbd{@key{ESC}
366 @key{ESC}}, since that would preclude recognizing an escape sequence
367 after @key{ESC}. In these states, you should define @kbd{@key{ESC}
368 @key{ESC} @key{ESC}} as the way to escape. Otherwise, define
369 @kbd{@key{ESC} @key{ESC}} instead.
372 @node Programming Tips
373 @section Emacs Programming Tips
375 Following these conventions will make your program fit better
376 into Emacs when it runs.
380 Don't use @code{next-line} or @code{previous-line} in programs; nearly
381 always, @code{forward-line} is more convenient as well as more
382 predictable and robust. @xref{Text Lines}.
385 Don't call functions that set the mark, unless setting the mark is one
386 of the intended features of your program. The mark is a user-level
387 feature, so it is incorrect to change the mark except to supply a value
388 for the user's benefit. @xref{The Mark}.
390 In particular, don't use any of these functions:
394 @code{beginning-of-buffer}, @code{end-of-buffer}
396 @code{replace-string}, @code{replace-regexp}
398 @code{insert-file}, @code{insert-buffer}
401 If you just want to move point, or replace a certain string, or insert
402 a file or buffer's contents, without any of the other features
403 intended for interactive users, you can replace these functions with
404 one or two lines of simple Lisp code.
407 Use lists rather than vectors, except when there is a particular reason
408 to use a vector. Lisp has more facilities for manipulating lists than
409 for vectors, and working with lists is usually more convenient.
411 Vectors are advantageous for tables that are substantial in size and are
412 accessed in random order (not searched front to back), provided there is
413 no need to insert or delete elements (only lists allow that).
416 The recommended way to show a message in the echo area is with
417 the @code{message} function, not @code{princ}. @xref{The Echo Area}.
420 When you encounter an error condition, call the function @code{error}
421 (or @code{signal}). The function @code{error} does not return.
422 @xref{Signaling Errors}.
424 Do not use @code{message}, @code{throw}, @code{sleep-for},
425 or @code{beep} to report errors.
428 An error message should start with a capital letter but should not end
432 A question asked in the minibuffer with @code{y-or-n-p} or
433 @code{yes-or-no-p} should start with a capital letter and end with
437 When you mention a default value in a minibuffer prompt,
438 put it and the word @samp{default} inside parentheses.
439 It should look like this:
442 Enter the answer (default 42):
446 In @code{interactive}, if you use a Lisp expression to produce a list
447 of arguments, don't try to provide the ``correct'' default values for
448 region or position arguments. Instead, provide @code{nil} for those
449 arguments if they were not specified, and have the function body
450 compute the default value when the argument is @code{nil}. For
451 instance, write this:
456 (list (if @var{specified} @var{specified-pos})))
457 (unless pos (setq pos @var{default-pos}))
467 (list (if @var{specified} @var{specified-pos}
473 This is so that repetition of the command will recompute
474 these defaults based on the current circumstances.
476 You do not need to take such precautions when you use interactive
477 specs @samp{d}, @samp{m} and @samp{r}, because they make special
478 arrangements to recompute the argument values on repetition of the
482 Many commands that take a long time to execute display a message that
483 says something like @samp{Operating...} when they start, and change it to
484 @samp{Operating...done} when they finish. Please keep the style of
485 these messages uniform: @emph{no} space around the ellipsis, and
486 @emph{no} period after @samp{done}.
489 Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e}
490 command does: use a new local keymap that contains one command defined
491 to switch back to the old local keymap. Or do what the
492 @code{edit-options} command does: switch to another buffer and let the
493 user switch back at will. @xref{Recursive Editing}.
496 @node Compilation Tips
497 @section Tips for Making Compiled Code Fast
498 @cindex execution speed
501 Here are ways of improving the execution speed of byte-compiled
507 @cindex timing programs
508 @cindex @file{elp.el}
509 Profile your program with the @file{elp} library. See the file
510 @file{elp.el} for instructions.
513 @cindex @file{benchmark.el}
515 Check the speed of individual Emacs Lisp forms using the
516 @file{benchmark} library. See the functions @code{benchmark-run} and
517 @code{benchmark-run-compiled} in @file{benchmark.el}.
520 Use iteration rather than recursion whenever possible.
521 Function calls are slow in Emacs Lisp even when a compiled function
522 is calling another compiled function.
525 Using the primitive list-searching functions @code{memq}, @code{member},
526 @code{assq}, or @code{assoc} is even faster than explicit iteration. It
527 can be worth rearranging a data structure so that one of these primitive
528 search functions can be used.
531 Certain built-in functions are handled specially in byte-compiled code,
532 avoiding the need for an ordinary function call. It is a good idea to
533 use these functions rather than alternatives. To see whether a function
534 is handled specially by the compiler, examine its @code{byte-compile}
535 property. If the property is non-@code{nil}, then the function is
538 For example, the following input will show you that @code{aref} is
539 compiled specially (@pxref{Array Functions}):
543 (get 'aref 'byte-compile)
544 @result{} byte-compile-two-args
549 If calling a small function accounts for a substantial part of your
550 program's running time, make the function inline. This eliminates
551 the function call overhead. Since making a function inline reduces
552 the flexibility of changing the program, don't do it unless it gives
553 a noticeable speedup in something slow enough that users care about
554 the speed. @xref{Inline Functions}.
558 @section Tips for Avoiding Compiler Warnings
562 Try to avoid compiler warnings about undefined free variables, by adding
563 dummy @code{defvar} definitions for these variables, like this:
569 Such a definition has no effect except to tell the compiler
570 not to warn about uses of the variable @code{foo} in this file.
573 If you use many functions and variables from a certain file, you can
574 add a @code{require} for that package to avoid compilation warnings
575 for them. For instance,
583 If you bind a variable in one function, and use it or set it in
584 another function, the compiler warns about the latter function unless
585 the variable has a definition. But adding a definition would be
586 unclean if the variable has a short name, since Lisp packages should
587 not define short variable names. The right thing to do is to rename
588 this variable to start with the name prefix used for the other
589 functions and variables in your package.
592 The last resort for avoiding a warning, when you want to do something
593 that usually is a mistake but it's not a mistake in this one case,
594 is to put a call to @code{with-no-warnings} around it.
597 @node Documentation Tips
598 @section Tips for Documentation Strings
600 @findex checkdoc-minor-mode
601 Here are some tips and conventions for the writing of documentation
602 strings. You can check many of these conventions by running the command
603 @kbd{M-x checkdoc-minor-mode}.
607 Every command, function, or variable intended for users to know about
608 should have a documentation string.
611 An internal variable or subroutine of a Lisp program might as well have
612 a documentation string. In earlier Emacs versions, you could save space
613 by using a comment instead of a documentation string, but that is no
614 longer the case---documentation strings now take up very little space in
618 Format the documentation string so that it fits in an Emacs window on an
619 80-column screen. It is a good idea for most lines to be no wider than
620 60 characters. The first line should not be wider than 67 characters
621 or it will look bad in the output of @code{apropos}.
623 You can fill the text if that looks good. However, rather than blindly
624 filling the entire documentation string, you can often make it much more
625 readable by choosing certain line breaks with care. Use blank lines
626 between topics if the documentation string is long.
629 The first line of the documentation string should consist of one or two
630 complete sentences that stand on their own as a summary. @kbd{M-x
631 apropos} displays just the first line, and if that line's contents don't
632 stand on their own, the result looks bad. In particular, start the
633 first line with a capital letter and end with a period.
635 For a function, the first line should briefly answer the question,
636 ``What does this function do?'' For a variable, the first line should
637 briefly answer the question, ``What does this value mean?''
639 Don't limit the documentation string to one line; use as many lines as
640 you need to explain the details of how to use the function or
641 variable. Please use complete sentences for the rest of the text too.
644 The first line should mention all the important arguments of the
645 function, and should mention them in the order that they are written
646 in a function call. If the function has many arguments, then it is
647 not feasible to mention them all in the first line; in that case, the
648 first line should mention the first few arguments, including the most
652 For consistency, phrase the verb in the first sentence of a function's
653 documentation string as an imperative---for instance, use ``Return the
654 cons of A and B.'' in preference to ``Returns the cons of A and B@.''
655 Usually it looks good to do likewise for the rest of the first
656 paragraph. Subsequent paragraphs usually look better if each sentence
657 is indicative and has a proper subject.
660 Write documentation strings in the active voice, not the passive, and in
661 the present tense, not the future. For instance, use ``Return a list
662 containing A and B.'' instead of ``A list containing A and B will be
666 Avoid using the word ``cause'' (or its equivalents) unnecessarily.
667 Instead of, ``Cause Emacs to display text in boldface,'' write just
668 ``Display text in boldface.''
671 When a command is meaningful only in a certain mode or situation,
672 do mention that in the documentation string. For example,
673 the documentation of @code{dired-find-file} is:
676 In Dired, visit the file or directory named on this line.
680 Do not start or end a documentation string with whitespace.
683 @strong{Do not} indent subsequent lines of a documentation string so
684 that the text is lined up in the source code with the text of the first
685 line. This looks nice in the source code, but looks bizarre when users
686 view the documentation. Remember that the indentation before the
687 starting double-quote is not part of the string!
690 When the user tries to use a disabled command, Emacs displays just the
691 first paragraph of its documentation string---everything through the
692 first blank line. If you wish, you can choose which information to
693 include before the first blank line so as to make this display useful.
696 When you define a variable that users ought to set interactively, you
697 normally should use @code{defcustom}. However, if for some reason you
698 use @code{defvar} instead, start the doc string with a @samp{*}.
699 @xref{Defining Variables}.
702 The documentation string for a variable that is a yes-or-no flag should
703 start with words such as ``Non-nil means@dots{}'', to make it clear that
704 all non-@code{nil} values are equivalent and indicate explicitly what
705 @code{nil} and non-@code{nil} mean.
708 The documentation string for a function that is a yes-or-no predicate
709 should start with words such as ``Return t if @dots{}'', to indicate
710 explicitly what constitutes ``truth''. The word ``return'' avoids
711 starting the sentence with lower-case ``t'', which is somewhat
715 When a function's documentation string mentions the value of an argument
716 of the function, use the argument name in capital letters as if it were
717 a name for that value. Thus, the documentation string of the function
718 @code{eval} refers to its second argument as @samp{FORM}, because the
719 actual argument name is @code{form}:
722 Evaluate FORM and return its value.
725 Also write metasyntactic variables in capital letters, such as when you
726 show the decomposition of a list or vector into subunits, some of which
727 may vary. @samp{KEY} and @samp{VALUE} in the following example
728 illustrate this practice:
731 The argument TABLE should be an alist whose elements
732 have the form (KEY . VALUE). Here, KEY is ...
736 Never change the case of a Lisp symbol when you mention it in a doc
737 string. If the symbol's name is @code{foo}, write ``foo'', not
738 ``Foo'' (which is a different symbol).
740 This might appear to contradict the policy of writing function
741 argument values, but there is no real contradiction; the argument
742 @emph{value} is not the same thing as the @emph{symbol} which the
743 function uses to hold the value.
745 If this puts a lower-case letter at the beginning of a sentence
746 and that annoys you, rewrite the sentence so that the symbol
747 is not at the start of it.
750 If a line in a documentation string begins with an open-parenthesis,
751 write a backslash before the open-parenthesis, like this:
754 The argument FOO can be either a number
755 \(a buffer position) or a string (a file name).
758 This prevents the open-parenthesis from being treated as the start of a
759 defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
761 @anchor{Docstring hyperlinks}
764 When a documentation string refers to a Lisp symbol, write it as it
765 would be printed (which usually means in lower case), with single-quotes
766 around it. For example: @samp{`lambda'}. There are two exceptions:
767 write @code{t} and @code{nil} without single-quotes.
770 When a documentation string refers to a Lisp symbol, write it as it
771 would be printed (which usually means in lower case), with single-quotes
772 around it. For example: @samp{lambda}. There are two exceptions: write
773 t and nil without single-quotes. (In this manual, we use a different
774 convention, with single-quotes for all symbols.)
777 Help mode automatically creates a hyperlink when a documentation string
778 uses a symbol name inside single quotes, if the symbol has either a
779 function or a variable definition. You do not need to do anything
780 special to make use of this feature. However, when a symbol has both a
781 function definition and a variable definition, and you want to refer to
782 just one of them, you can specify which one by writing one of the words
783 @samp{variable}, @samp{option}, @samp{function}, or @samp{command},
784 immediately before the symbol name. (Case makes no difference in
785 recognizing these indicator words.) For example, if you write
788 This function sets the variable `buffer-file-name'.
792 then the hyperlink will refer only to the variable documentation of
793 @code{buffer-file-name}, and not to its function documentation.
795 If a symbol has a function definition and/or a variable definition, but
796 those are irrelevant to the use of the symbol that you are documenting,
797 you can write the words @samp{symbol} or @samp{program} before the
798 symbol name to prevent making any hyperlink. For example,
801 If the argument KIND-OF-RESULT is the symbol `list',
802 this function returns a list of all the objects
803 that satisfy the criterion.
807 does not make a hyperlink to the documentation, irrelevant here, of the
808 function @code{list}.
810 Normally, no hyperlink is made for a variable without variable
811 documentation. You can force a hyperlink for such variables by
812 preceding them with one of the words @samp{variable} or
815 Hyperlinks for faces are only made if the face name is preceded or
816 followed by the word @samp{face}. In that case, only the face
817 documentation will be shown, even if the symbol is also defined as a
818 variable or as a function.
820 To make a hyperlink to Info documentation, write the name of the Info
821 node (or anchor) in single quotes, preceded by @samp{info node},
822 @samp{Info node}, @samp{info anchor} or @samp{Info anchor}. The Info
823 file name defaults to @samp{emacs}. For example,
826 See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
829 Finally, to create a hyperlink to URLs, write the URL in single
830 quotes, preceded by @samp{URL}. For example,
833 The home page for the GNU project has more information (see URL
834 `http://www.gnu.org/').
838 Don't write key sequences directly in documentation strings. Instead,
839 use the @samp{\\[@dots{}]} construct to stand for them. For example,
840 instead of writing @samp{C-f}, write the construct
841 @samp{\\[forward-char]}. When Emacs displays the documentation string,
842 it substitutes whatever key is currently bound to @code{forward-char}.
843 (This is normally @samp{C-f}, but it may be some other character if the
844 user has moved key bindings.) @xref{Keys in Documentation}.
847 In documentation strings for a major mode, you will want to refer to the
848 key bindings of that mode's local map, rather than global ones.
849 Therefore, use the construct @samp{\\<@dots{}>} once in the
850 documentation string to specify which key map to use. Do this before
851 the first use of @samp{\\[@dots{}]}. The text inside the
852 @samp{\\<@dots{}>} should be the name of the variable containing the
853 local keymap for the major mode.
855 It is not practical to use @samp{\\[@dots{}]} very many times, because
856 display of the documentation string will become slow. So use this to
857 describe the most important commands in your major mode, and then use
858 @samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
862 @section Tips on Writing Comments
864 We recommend these conventions for where to put comments and how to
869 Comments that start with a single semicolon, @samp{;}, should all be
870 aligned to the same column on the right of the source code. Such
871 comments usually explain how the code on the same line does its job. In
872 Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment})
873 command automatically inserts such a @samp{;} in the right place, or
874 aligns such a comment if it is already present.
876 This and following examples are taken from the Emacs sources.
880 (setq base-version-list ; there was a base
881 (assoc (substring fn 0 start-vn) ; version to which
882 file-version-assoc-list)) ; this looks like
888 Comments that start with two semicolons, @samp{;;}, should be aligned to
889 the same level of indentation as the code. Such comments usually
890 describe the purpose of the following lines or the state of the program
891 at that point. For example:
895 (prog1 (setq auto-fill-function
899 (force-mode-line-update)))
903 We also normally use two semicolons for comments outside functions.
907 ;; This Lisp code is run in Emacs
908 ;; when it is to operate as a server
909 ;; for other processes.
913 Every function that has no documentation string (presumably one that is
914 used only internally within the package it belongs to), should instead
915 have a two-semicolon comment right before the function, explaining what
916 the function does and how to call it properly. Explain precisely what
917 each argument means and how the function interprets its possible values.
920 Comments that start with three semicolons, @samp{;;;}, should start at
921 the left margin. These are used, occasionally, for comments within
922 functions that should start at the margin. We also use them sometimes
923 for comments that are between functions---whether to use two or three
924 semicolons depends on whether the comment should be considered a
925 ``heading'' by Outline minor mode. By default, comments starting with
926 at least three semicolons (followed by a single space and a
927 non-whitespace character) are considered headings, comments starting
928 with two or less are not.
930 Another use for triple-semicolon comments is for commenting out lines
931 within a function. We use three semicolons for this precisely so that
932 they remain at the left margin. By default, Outline minor mode does
933 not consider a comment to be a heading (even if it starts with at
934 least three semicolons) if the semicolons are followed by at least two
935 spaces. Thus, if you add an introductory comment to the commented out
936 code, make sure to indent it by at least two spaces after the three
941 ;;; This is no longer necessary.
942 ;;; (force-mode-line-update)
943 (message "Finished with %s" a))
946 When commenting out entire functions, use two semicolons.
949 Comments that start with four semicolons, @samp{;;;;}, should be aligned
950 to the left margin and are used for headings of major sections of a
951 program. For example:
959 The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;}
960 (@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}),
961 automatically indent comments according to these conventions,
962 depending on the number of semicolons. @xref{Comments,,
963 Manipulating Comments, emacs, The GNU Emacs Manual}.
965 @node Library Headers
966 @section Conventional Headers for Emacs Libraries
967 @cindex header comments
968 @cindex library header comments
970 Emacs has conventions for using special comments in Lisp libraries
971 to divide them into sections and give information such as who wrote
972 them. This section explains these conventions.
974 We'll start with an example, a package that is included in the Emacs
977 Parts of this example reflect its status as part of Emacs; for
978 example, the copyright notice lists the Free Software Foundation as the
979 copyright holder, and the copying permission says the file is part of
980 Emacs. When you write a package and post it, the copyright holder would
981 be you (unless your employer claims to own it instead), and you should
982 get the suggested copying permission from the end of the GNU General
983 Public License itself. Don't say your file is part of Emacs
984 if we haven't installed it in Emacs yet!
986 With that warning out of the way, on to the example:
990 ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
992 ;; Copyright (C) 1992 Free Software Foundation, Inc.
995 ;; Author: Eric S. Raymond <esr@@snark.thyrsus.com>
996 ;; Maintainer: Eric S. Raymond <esr@@snark.thyrsus.com>
997 ;; Created: 14 Jul 1992
1002 ;; This file is part of GNU Emacs.
1004 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
1005 ;; Boston, MA 02110-1301, USA.
1009 The very first line should have this format:
1012 ;;; @var{filename} --- @var{description}
1016 The description should be complete in one line. If the file
1017 needs a @samp{-*-} specification, put it after @var{description}.
1019 After the copyright notice come several @dfn{header comment} lines,
1020 each beginning with @samp{;; @var{header-name}:}. Here is a table of
1021 the conventional possibilities for @var{header-name}:
1025 This line states the name and net address of at least the principal
1026 author of the library.
1028 If there are multiple authors, you can list them on continuation lines
1029 led by @code{;;} and a tab character, like this:
1033 ;; Author: Ashwin Ram <Ram-Ashwin@@cs.yale.edu>
1034 ;; Dave Sill <de5@@ornl.gov>
1035 ;; Dave Brennan <brennan@@hal.com>
1036 ;; Eric Raymond <esr@@snark.thyrsus.com>
1041 This line should contain a single name/address as in the Author line, or
1042 an address only, or the string @samp{FSF}. If there is no maintainer
1043 line, the person(s) in the Author field are presumed to be the
1044 maintainers. The example above is mildly bogus because the maintainer
1047 The idea behind the @samp{Author} and @samp{Maintainer} lines is to make
1048 possible a Lisp function to ``send mail to the maintainer'' without
1049 having to mine the name out by hand.
1051 Be sure to surround the network address with @samp{<@dots{}>} if
1052 you include the person's full name as well as the network address.
1055 This optional line gives the original creation date of the
1056 file. For historical interest only.
1059 If you wish to record version numbers for the individual Lisp program, put
1063 In this header line, place the name of the person who adapted the
1064 library for installation (to make it fit the style conventions, for
1068 This line lists keywords for the @code{finder-by-keyword} help command.
1069 Please use that command to see a list of the meaningful keywords.
1071 This field is important; it's how people will find your package when
1072 they're looking for things by topic area. To separate the keywords, you
1073 can use spaces, commas, or both.
1076 Just about every Lisp library ought to have the @samp{Author} and
1077 @samp{Keywords} header comment lines. Use the others if they are
1078 appropriate. You can also put in header lines with other header
1079 names---they have no standard meanings, so they can't do any harm.
1081 We use additional stylized comments to subdivide the contents of the
1082 library file. These should be separated by blank lines from anything
1083 else. Here is a table of them:
1086 @item ;;; Commentary:
1087 This begins introductory comments that explain how the library works.
1088 It should come right after the copying permissions, terminated by a
1089 @samp{Change Log}, @samp{History} or @samp{Code} comment line. This
1090 text is used by the Finder package, so it should make sense in that
1093 @item ;;; Documentation:
1094 This was used in some files in place of @samp{;;; Commentary:},
1095 but it is deprecated.
1097 @item ;;; Change Log:
1098 This begins change log information stored in the library file (if you
1099 store the change history there). For Lisp files distributed with Emacs,
1100 the change history is kept in the file @file{ChangeLog} and not in the
1101 source file at all; these files generally do not have a @samp{;;; Change
1102 Log:} line. @samp{History} is an alternative to @samp{Change Log}.
1105 This begins the actual code of the program.
1107 @item ;;; @var{filename} ends here
1108 This is the @dfn{footer line}; it appears at the very end of the file.
1109 Its purpose is to enable people to detect truncated versions of the file
1110 from the lack of a footer line.
1114 arch-tag: 9ea911c2-6b1d-47dd-88b7-0a94e8b27c2e