annotate lispref/tips.texi @ 51031:0c0b80172350

(set_case_table): Pass new arg to map_char_table.
author Richard M. Stallman <rms@gnu.org>
date Sat, 17 May 2003 12:44:28 +0000
parents 10a8aba3dfc7
children 9928a29a3e80
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
27189
d2e5f1b7d8e2 Update copyrights.
Gerd Moellmann <gerd@gnu.org>
parents: 27187
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998, 1999
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44733
diff changeset
4 @c Free Software Foundation, Inc.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @setfilename ../info/tips
30904
a0af1af4aabf * .cvsignore: New file.
Werner LEMBERG <wl@gnu.org>
parents: 29110
diff changeset
7 @node Tips, GNU Emacs Internals, GPL, Top
17280
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
8 @appendix Tips and Conventions
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 @cindex tips
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10 @cindex standards of coding style
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 @cindex coding standards
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12
17280
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
13 This chapter describes no additional features of Emacs Lisp. Instead
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
14 it gives advice on making effective use of the features described in the
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
15 previous chapters, and describes conventions Emacs Lisp programmers
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
16 should follow.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
18 You can automatically check some of the conventions described below by
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
19 running the command @kbd{M-x checkdoc RET} when visiting a Lisp file.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
20 It cannot check all of the conventions, and not all the warnings it
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
21 gives necessarily correspond to problems, but it is worth examining them
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
22 all.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
23
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24 @menu
17280
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
25 * Coding Conventions:: Conventions for clean and robust programs.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26 * Compilation Tips:: Making compiled code run fast.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 * Documentation Tips:: Writing readable documentation strings.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 * Comment Tips:: Conventions for writing comments.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 * Library Headers:: Standard headers for library packages.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 @end menu
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31
17280
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
32 @node Coding Conventions
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
33 @section Emacs Lisp Coding Conventions
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34
17280
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
35 Here are conventions that you should follow when writing Emacs Lisp
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
36 code intended for widespread use:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38 @itemize @bullet
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 @item
38162
40606e2d6b31 Minor change.
Richard M. Stallman <rms@gnu.org>
parents: 38043
diff changeset
40 Since all global variables share the same name space, and all
40606e2d6b31 Minor change.
Richard M. Stallman <rms@gnu.org>
parents: 38043
diff changeset
41 functions share another name space, you should choose a short word to
40606e2d6b31 Minor change.
Richard M. Stallman <rms@gnu.org>
parents: 38043
diff changeset
42 distinguish your program from other Lisp programs.@footnote{The
40606e2d6b31 Minor change.
Richard M. Stallman <rms@gnu.org>
parents: 38043
diff changeset
43 benefits of a Common Lisp-style package system are considered not to
40606e2d6b31 Minor change.
Richard M. Stallman <rms@gnu.org>
parents: 38043
diff changeset
44 outweigh the costs.} Then take care to begin the names of all global
40606e2d6b31 Minor change.
Richard M. Stallman <rms@gnu.org>
parents: 38043
diff changeset
45 variables, constants, and functions in your program with the chosen
40606e2d6b31 Minor change.
Richard M. Stallman <rms@gnu.org>
parents: 38043
diff changeset
46 prefix. This helps avoid name conflicts.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 This recommendation applies even to names for traditional Lisp
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
49 primitives that are not primitives in Emacs Lisp---even to
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
50 @code{copy-list}. Believe it or not, there is more than one plausible
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
51 way to define @code{copy-list}. Play it safe; append your name prefix
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
52 to produce a name like @code{foo-copy-list} or @code{mylib-copy-list}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
53 instead.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 If you write a function that you think ought to be added to Emacs under
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56 a certain name, such as @code{twiddle-files}, don't call it by that name
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57 in your program. Call it @code{mylib-twiddle-files} in your program,
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
58 and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 it to Emacs. If and when we do, we can change the name easily enough.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 If one prefix is insufficient, your package may use two or three
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 alternative common prefixes, so long as they make sense.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64 Separate the prefix from the rest of the symbol name with a hyphen,
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 @samp{-}. This will be consistent with Emacs itself and with most Emacs
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66 Lisp programs.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69 It is often useful to put a call to @code{provide} in each separate
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70 library program, at least if there is more than one entry point to the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71 program.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73 @item
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
74 If a file requires certain other library programs to be loaded
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
75 beforehand, then the comments at the beginning of the file should say
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
76 so. Also, use @code{require} to make sure they are loaded.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
77
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
78 @item
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 If one file @var{foo} uses a macro defined in another file @var{bar},
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
80 @var{foo} should contain this expression before the first use of the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
81 macro:
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
82
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
83 @example
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
84 (eval-when-compile (require '@var{bar}))
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
85 @end example
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
86
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
87 @noindent
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
88 (And the library @var{bar} should contain @code{(provide '@var{bar})},
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
89 to make the @code{require} work.) This will cause @var{bar} to be
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
90 loaded when you byte-compile @var{foo}. Otherwise, you risk compiling
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
91 @var{foo} without the necessary macro loaded, and that would produce
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
92 compiled code that won't work right. @xref{Compiling Macros}.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
93
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
94 Using @code{eval-when-compile} avoids loading @var{bar} when
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
95 the compiled version of @var{foo} is @emph{used}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97 @item
24799
7f38d541d411 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22635
diff changeset
98 Please don't require the @code{cl} package of Common Lisp extensions at
7f38d541d411 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22635
diff changeset
99 run time. Use of this package is optional, and it is not part of the
7f38d541d411 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22635
diff changeset
100 standard Emacs namespace. If your package loads @code{cl} at run time,
7f38d541d411 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22635
diff changeset
101 that could cause name clashes for users who don't use that package.
7f38d541d411 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22635
diff changeset
102
7f38d541d411 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22635
diff changeset
103 However, there is no problem with using the @code{cl} package at compile
7f38d541d411 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22635
diff changeset
104 time, for the sake of macros. You do that like this:
7f38d541d411 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22635
diff changeset
105
7f38d541d411 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22635
diff changeset
106 @example
7f38d541d411 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22635
diff changeset
107 (eval-when-compile (require 'cl))
7f38d541d411 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22635
diff changeset
108 @end example
7f38d541d411 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22635
diff changeset
109
7f38d541d411 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22635
diff changeset
110 @item
17280
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
111 When defining a major mode, please follow the major mode
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
112 conventions. @xref{Major Mode Conventions}.
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
113
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
114 @item
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
115 When defining a minor mode, please follow the minor mode
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
116 conventions. @xref{Minor Mode Conventions}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 @item
9807
d5fa87d62d62 Add function and variable name conventions.
Richard M. Stallman <rms@gnu.org>
parents: 9393
diff changeset
119 If the purpose of a function is to tell you whether a certain condition
d5fa87d62d62 Add function and variable name conventions.
Richard M. Stallman <rms@gnu.org>
parents: 9393
diff changeset
120 is true or false, give the function a name that ends in @samp{p}. If
d5fa87d62d62 Add function and variable name conventions.
Richard M. Stallman <rms@gnu.org>
parents: 9393
diff changeset
121 the name is one word, add just @samp{p}; if the name is multiple words,
d5fa87d62d62 Add function and variable name conventions.
Richard M. Stallman <rms@gnu.org>
parents: 9393
diff changeset
122 add @samp{-p}. Examples are @code{framep} and @code{frame-live-p}.
d5fa87d62d62 Add function and variable name conventions.
Richard M. Stallman <rms@gnu.org>
parents: 9393
diff changeset
123
d5fa87d62d62 Add function and variable name conventions.
Richard M. Stallman <rms@gnu.org>
parents: 9393
diff changeset
124 @item
d5fa87d62d62 Add function and variable name conventions.
Richard M. Stallman <rms@gnu.org>
parents: 9393
diff changeset
125 If a user option variable records a true-or-false condition, give it a
d5fa87d62d62 Add function and variable name conventions.
Richard M. Stallman <rms@gnu.org>
parents: 9393
diff changeset
126 name that ends in @samp{-flag}.
d5fa87d62d62 Add function and variable name conventions.
Richard M. Stallman <rms@gnu.org>
parents: 9393
diff changeset
127
d5fa87d62d62 Add function and variable name conventions.
Richard M. Stallman <rms@gnu.org>
parents: 9393
diff changeset
128 @item
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
129 @cindex reserved keys
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
130 @cindex keys, reserved
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 Please do not define @kbd{C-c @var{letter}} as a key in your major
44733
d49f5ed1a977 Clarify which letters in C-c LETTER are reserved for users.
Richard M. Stallman <rms@gnu.org>
parents: 44654
diff changeset
132 modes. Sequences consisting of @kbd{C-c} and a letter (either upper
d49f5ed1a977 Clarify which letters in C-c LETTER are reserved for users.
Richard M. Stallman <rms@gnu.org>
parents: 44654
diff changeset
133 or lower case) are reserved for users; they are the @strong{only}
d49f5ed1a977 Clarify which letters in C-c LETTER are reserved for users.
Richard M. Stallman <rms@gnu.org>
parents: 44654
diff changeset
134 sequences reserved for users, so do not block them.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135
44733
d49f5ed1a977 Clarify which letters in C-c LETTER are reserved for users.
Richard M. Stallman <rms@gnu.org>
parents: 44654
diff changeset
136 Changing all the Emacs major modes to respect this convention was a
d49f5ed1a977 Clarify which letters in C-c LETTER are reserved for users.
Richard M. Stallman <rms@gnu.org>
parents: 44654
diff changeset
137 lot of work; abandoning this convention would make that work go to
d49f5ed1a977 Clarify which letters in C-c LETTER are reserved for users.
Richard M. Stallman <rms@gnu.org>
parents: 44654
diff changeset
138 waste, and inconvenience users. Please comply with it.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139
44733
d49f5ed1a977 Clarify which letters in C-c LETTER are reserved for users.
Richard M. Stallman <rms@gnu.org>
parents: 44654
diff changeset
140 @item
d49f5ed1a977 Clarify which letters in C-c LETTER are reserved for users.
Richard M. Stallman <rms@gnu.org>
parents: 44654
diff changeset
141 Sequences consisting of @kbd{C-c} followed by a control character or a
d49f5ed1a977 Clarify which letters in C-c LETTER are reserved for users.
Richard M. Stallman <rms@gnu.org>
parents: 44654
diff changeset
142 digit are reserved for major modes.
11648
e09e51d7c35a Describe uses of C-c followed by punctuation chars.
Richard M. Stallman <rms@gnu.org>
parents: 10229
diff changeset
143
e09e51d7c35a Describe uses of C-c followed by punctuation chars.
Richard M. Stallman <rms@gnu.org>
parents: 10229
diff changeset
144 @item
e09e51d7c35a Describe uses of C-c followed by punctuation chars.
Richard M. Stallman <rms@gnu.org>
parents: 10229
diff changeset
145 Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
e09e51d7c35a Describe uses of C-c followed by punctuation chars.
Richard M. Stallman <rms@gnu.org>
parents: 10229
diff changeset
146 @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes.
e09e51d7c35a Describe uses of C-c followed by punctuation chars.
Richard M. Stallman <rms@gnu.org>
parents: 10229
diff changeset
147
e09e51d7c35a Describe uses of C-c followed by punctuation chars.
Richard M. Stallman <rms@gnu.org>
parents: 10229
diff changeset
148 @item
e09e51d7c35a Describe uses of C-c followed by punctuation chars.
Richard M. Stallman <rms@gnu.org>
parents: 10229
diff changeset
149 Sequences consisting of @kbd{C-c} followed by any other punctuation
e09e51d7c35a Describe uses of C-c followed by punctuation chars.
Richard M. Stallman <rms@gnu.org>
parents: 10229
diff changeset
150 character are allocated for minor modes. Using them in a major mode is
e09e51d7c35a Describe uses of C-c followed by punctuation chars.
Richard M. Stallman <rms@gnu.org>
parents: 10229
diff changeset
151 not absolutely prohibited, but if you do that, the major mode binding
e09e51d7c35a Describe uses of C-c followed by punctuation chars.
Richard M. Stallman <rms@gnu.org>
parents: 10229
diff changeset
152 may be shadowed from time to time by minor modes.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154 @item
19361
8546df4cb304 Reserve some function keys for users.
Richard M. Stallman <rms@gnu.org>
parents: 17280
diff changeset
155 Function keys @key{F5} through @key{F9} without modifier keys are
8546df4cb304 Reserve some function keys for users.
Richard M. Stallman <rms@gnu.org>
parents: 17280
diff changeset
156 reserved for users to define.
8546df4cb304 Reserve some function keys for users.
Richard M. Stallman <rms@gnu.org>
parents: 17280
diff changeset
157
8546df4cb304 Reserve some function keys for users.
Richard M. Stallman <rms@gnu.org>
parents: 17280
diff changeset
158 @item
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
159 Do not bind @kbd{C-h} following any prefix character (including
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 @kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically available
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 as a help character for listing the subcommands of the prefix character.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163 @item
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
164 Do not bind a key sequence ending in @key{ESC} except following
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
165 another @key{ESC}. (That is, it is OK to bind a sequence ending in
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
166 @kbd{@key{ESC} @key{ESC}}.)
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 The reason for this rule is that a non-prefix binding for @key{ESC} in
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 any context prevents recognition of escape sequences as function keys in
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170 that context.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172 @item
22635
1e9786a5c63d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
173 Anything which acts like a temporary mode or state which the user can
24862
78aaef52e28f *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24799
diff changeset
174 enter and leave should define @kbd{@key{ESC} @key{ESC}} or
22635
1e9786a5c63d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
175 @kbd{@key{ESC} @key{ESC} @key{ESC}} as a way to escape.
1e9786a5c63d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
176
1e9786a5c63d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
177 For a state which accepts ordinary Emacs commands, or more generally any
1e9786a5c63d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
178 kind of state in which @key{ESC} followed by a function key or arrow key
1e9786a5c63d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
179 is potentially meaningful, then you must not define @kbd{@key{ESC}
1e9786a5c63d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
180 @key{ESC}}, since that would preclude recognizing an escape sequence
1e9786a5c63d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
181 after @key{ESC}. In these states, you should define @kbd{@key{ESC}
1e9786a5c63d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
182 @key{ESC} @key{ESC}} as the way to escape. Otherwise, define
1e9786a5c63d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
183 @kbd{@key{ESC} @key{ESC}} instead.
1e9786a5c63d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
184
1e9786a5c63d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
185 @item
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
186 Applications should not bind mouse events based on button 1 with the
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
187 shift key held down. These events include @kbd{S-mouse-1},
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
188 @kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on. They are reserved for
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
189 users.
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
190
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
191 @item
34305
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
192 @cindex mouse-2
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
193 @cindex references, following
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
194 Special major modes used for read-only text should usually redefine
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
195 @kbd{mouse-2} and @key{RET} to trace some sort of reference in the text.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
196 Modes such as Dired, Info, Compilation, and Occur redefine it in this
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
197 way.
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
198
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
199 @item
9393
0bec3b6bac2f Add a tip about enabling/disabling features.
Richard M. Stallman <rms@gnu.org>
parents: 8669
diff changeset
200 When a package provides a modification of ordinary Emacs behavior, it is
40561
ec17075b77aa (Coding Conventions): Fix typo.
Pavel Janík <Pavel@Janik.cz>
parents: 40517
diff changeset
201 good to include a command to enable and disable the feature, provide a
9393
0bec3b6bac2f Add a tip about enabling/disabling features.
Richard M. Stallman <rms@gnu.org>
parents: 8669
diff changeset
202 command named @code{@var{whatever}-mode} which turns the feature on or
0bec3b6bac2f Add a tip about enabling/disabling features.
Richard M. Stallman <rms@gnu.org>
parents: 8669
diff changeset
203 off, and make it autoload (@pxref{Autoload}). Design the package so
0bec3b6bac2f Add a tip about enabling/disabling features.
Richard M. Stallman <rms@gnu.org>
parents: 8669
diff changeset
204 that simply loading it has no visible effect---that should not enable
34305
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
205 the feature.@footnote{Consider that the package may be loaded
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
206 arbitrarily by Custom for instance.} Users will request the feature by
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
207 invoking the command.
9393
0bec3b6bac2f Add a tip about enabling/disabling features.
Richard M. Stallman <rms@gnu.org>
parents: 8669
diff changeset
208
0bec3b6bac2f Add a tip about enabling/disabling features.
Richard M. Stallman <rms@gnu.org>
parents: 8669
diff changeset
209 @item
0bec3b6bac2f Add a tip about enabling/disabling features.
Richard M. Stallman <rms@gnu.org>
parents: 8669
diff changeset
210 It is a bad idea to define aliases for the Emacs primitives. Use the
0bec3b6bac2f Add a tip about enabling/disabling features.
Richard M. Stallman <rms@gnu.org>
parents: 8669
diff changeset
211 standard names instead.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 @item
34305
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
214 If a package needs to define an alias or a new function for
38344
f70837a465ac Fix a typo.
Gerd Moellmann <gerd@gnu.org>
parents: 38162
diff changeset
215 compatibility with some other version of Emacs, name it with the package
34305
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
216 prefix, not with the raw name with which it occurs in the other version.
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
217 Here is an example from Gnus, which provides many examples of such
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
218 compatibility issues.
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
219
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
220 @example
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
221 (defalias 'gnus-point-at-bol
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
222 (if (fboundp 'point-at-bol)
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
223 'point-at-bol
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
224 'line-beginning-position))
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
225 @end example
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
226
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
227 @item
17280
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
228 Redefining (or advising) an Emacs primitive is discouraged. It may do
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
229 the right thing for a particular program, but there is no telling what
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
230 other programs might break as a result.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233 If a file does replace any of the functions or library programs of
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234 standard Emacs, prominent comments at the beginning of the file should
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235 say which functions are replaced, and how the behavior of the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
236 replacements differs from that of the originals.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 Please keep the names of your Emacs Lisp source files to 13 characters
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240 or less. This way, if the files are compiled, the compiled files' names
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241 will be 14 characters or less, which is short enough to fit on all kinds
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242 of Unix systems.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 Don't use @code{next-line} or @code{previous-line} in programs; nearly
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 always, @code{forward-line} is more convenient as well as more
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 predictable and robust. @xref{Text Lines}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249 @item
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6959
diff changeset
250 Don't call functions that set the mark, unless setting the mark is one
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6959
diff changeset
251 of the intended features of your program. The mark is a user-level
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6959
diff changeset
252 feature, so it is incorrect to change the mark except to supply a value
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6959
diff changeset
253 for the user's benefit. @xref{The Mark}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
255 In particular, don't use any of these functions:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
256
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
257 @itemize @bullet
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259 @code{beginning-of-buffer}, @code{end-of-buffer}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 @code{replace-string}, @code{replace-regexp}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 @end itemize
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 If you just want to move point, or replace a certain string, without any
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265 of the other features intended for interactive users, you can replace
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 these functions with one or two lines of simple Lisp code.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 @item
8669
62d1138d10de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7601
diff changeset
269 Use lists rather than vectors, except when there is a particular reason
62d1138d10de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7601
diff changeset
270 to use a vector. Lisp has more facilities for manipulating lists than
62d1138d10de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7601
diff changeset
271 for vectors, and working with lists is usually more convenient.
62d1138d10de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7601
diff changeset
272
62d1138d10de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7601
diff changeset
273 Vectors are advantageous for tables that are substantial in size and are
62d1138d10de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7601
diff changeset
274 accessed in random order (not searched front to back), provided there is
62d1138d10de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7601
diff changeset
275 no need to insert or delete elements (only lists allow that).
62d1138d10de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7601
diff changeset
276
62d1138d10de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7601
diff changeset
277 @item
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 The recommended way to print a message in the echo area is with
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 the @code{message} function, not @code{princ}. @xref{The Echo Area}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282 When you encounter an error condition, call the function @code{error}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 (or @code{signal}). The function @code{error} does not return.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284 @xref{Signaling Errors}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 Do not use @code{message}, @code{throw}, @code{sleep-for},
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 or @code{beep} to report errors.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 @item
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
290 An error message should start with a capital letter but should not end
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
291 with a period.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
292
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
293 @item
38043
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
294 In @code{interactive}, if you use a Lisp expression to produce a list
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
295 of arguments, don't try to provide the ``correct'' default values for
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
296 region or position arguments. Instead, provide @code{nil} for those
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
297 arguments if they were not specified, and have the function body
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
298 compute the default value when the argument is @code{nil}. For
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
299 instance, write this:
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
300
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
301 @example
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
302 (defun foo (pos)
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
303 (interactive
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
304 (list (if @var{specified} @var{specified-pos})))
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
305 (unless pos (setq pos @var{default-pos}))
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
306 ...)
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
307 @end example
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
308
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
309 @noindent
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
310 rather than this:
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
311
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
312 @example
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
313 (defun foo (pos)
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
314 (interactive
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
315 (list (if @var{specified} @var{specified-pos}
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
316 @var{default-pos})))
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
317 ...)
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
318 @end example
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
319
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
320 @noindent
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
321 This is so that repetition of the command will recompute
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
322 these defaults based on the current circumstances.
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
323
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
324 You do not need to take such precautions when you use interactive
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
325 specs @samp{d}, @samp{m} and @samp{r}, because they make special
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
326 arrangements to recompute the argument values on repetition of the
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
327 command.
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
328
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
329 @item
13893
2576d1142ed3 Explain style of "done" messages.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
330 Many commands that take a long time to execute display a message that
38043
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
331 says something like @samp{Operating...} when they start, and change it to
13893
2576d1142ed3 Explain style of "done" messages.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
332 @samp{Operating...done} when they finish. Please keep the style of
2576d1142ed3 Explain style of "done" messages.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
333 these messages uniform: @emph{no} space around the ellipsis, and
38043
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
334 @emph{no} period after @samp{done}.
13893
2576d1142ed3 Explain style of "done" messages.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
335
2576d1142ed3 Explain style of "done" messages.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
336 @item
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
337 Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e}
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
338 command does: use a new local keymap that contains one command defined
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
339 to switch back to the old local keymap. Or do what the
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
340 @code{edit-options} command does: switch to another buffer and let the
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
341 user switch back at will. @xref{Recursive Editing}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 In some other systems there is a convention of choosing variable names
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345 that begin and end with @samp{*}. We don't use that convention in Emacs
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
346 Lisp, so please don't use it in your programs. (Emacs uses such names
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
347 only for special-purpose buffers.) The users will find Emacs more
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
348 coherent if all libraries use the same conventions.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 @item
14028
e8d6c760f796 Explain eliminating compiler warnings about undefined variables.
Richard M. Stallman <rms@gnu.org>
parents: 13893
diff changeset
351 Try to avoid compiler warnings about undefined free variables, by adding
15198
fd47674bb3a7 Fix minor typo.
Erik Naggum <erik@naggum.no>
parents: 14394
diff changeset
352 @code{defvar} definitions for these variables.
14028
e8d6c760f796 Explain eliminating compiler warnings about undefined variables.
Richard M. Stallman <rms@gnu.org>
parents: 13893
diff changeset
353
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
354 Sometimes adding a @code{require} for another package is useful to avoid
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
355 compilation warnings for variables and functions defined in that
26211
df0efa93750b Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
356 package. If you do this, often it is better if the @code{require} acts
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
357 only at compile time. Here's how to do that:
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
358
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
359 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
360 (eval-when-compile
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
361 (require 'foo)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
362 (defvar bar-baz))
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
363 @end example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
364
14028
e8d6c760f796 Explain eliminating compiler warnings about undefined variables.
Richard M. Stallman <rms@gnu.org>
parents: 13893
diff changeset
365 If you bind a variable in one function, and use it or set it in another
e8d6c760f796 Explain eliminating compiler warnings about undefined variables.
Richard M. Stallman <rms@gnu.org>
parents: 13893
diff changeset
366 function, the compiler warns about the latter function unless the
e8d6c760f796 Explain eliminating compiler warnings about undefined variables.
Richard M. Stallman <rms@gnu.org>
parents: 13893
diff changeset
367 variable has a definition. But often these variables have short names,
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
368 and it is not clean for Lisp packages to define such variable names.
14028
e8d6c760f796 Explain eliminating compiler warnings about undefined variables.
Richard M. Stallman <rms@gnu.org>
parents: 13893
diff changeset
369 Therefore, you should rename the variable to start with the name prefix
e8d6c760f796 Explain eliminating compiler warnings about undefined variables.
Richard M. Stallman <rms@gnu.org>
parents: 13893
diff changeset
370 used for the other functions and variables in your package.
e8d6c760f796 Explain eliminating compiler warnings about undefined variables.
Richard M. Stallman <rms@gnu.org>
parents: 13893
diff changeset
371
e8d6c760f796 Explain eliminating compiler warnings about undefined variables.
Richard M. Stallman <rms@gnu.org>
parents: 13893
diff changeset
372 @item
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374 default indentation parameters.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377 Don't make a habit of putting close-parentheses on lines by themselves;
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378 Lisp programmers find this disconcerting. Once in a while, when there
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 is a sequence of many consecutive close-parentheses, it may make sense
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
380 to split the sequence in one or two significant places.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383 Please put a copyright notice on the file if you give copies to anyone.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
384 Use a message like this one:
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
385
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
386 @smallexample
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
387 ;; Copyright (C) @var{year} @var{name}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
388
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
389 ;; This program is free software; you can redistribute it and/or
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
390 ;; modify it under the terms of the GNU General Public License as
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
391 ;; published by the Free Software Foundation; either version 2 of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
392 ;; the License, or (at your option) any later version.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
393
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
394 ;; This program is distributed in the hope that it will be
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
395 ;; useful, but WITHOUT ANY WARRANTY; without even the implied
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
396 ;; warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
397 ;; PURPOSE. See the GNU General Public License for more details.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
398
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
399 ;; You should have received a copy of the GNU General Public
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
400 ;; License along with this program; if not, write to the Free
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
401 ;; Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
402 ;; MA 02111-1307 USA
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
403 @end smallexample
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
404
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
405 If you have signed papers to assign the copyright to the Foundation,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
406 then use @samp{Free Software Foundation, Inc.} as @var{name}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
407 Otherwise, use your name.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408 @end itemize
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410 @node Compilation Tips
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 @section Tips for Making Compiled Code Fast
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 @cindex execution speed
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 @cindex speedups
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 Here are ways of improving the execution speed of byte-compiled
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
416 Lisp programs.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418 @itemize @bullet
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 @cindex profiling
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 @cindex timing programs
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
422 @cindex @file{elp.el}
44654
774d49397ece (Tips for Making Compiled Code Fast): Don't advertise profile.el.
Eli Zaretskii <eliz@gnu.org>
parents: 42979
diff changeset
423 Profile your program with the @file{elp} library. See the file
774d49397ece (Tips for Making Compiled Code Fast): Don't advertise profile.el.
Eli Zaretskii <eliz@gnu.org>
parents: 42979
diff changeset
424 @file{elp.el} for instructions.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 Use iteration rather than recursion whenever possible.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 Function calls are slow in Emacs Lisp even when a compiled function
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429 is calling another compiled function.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431 @item
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
432 Using the primitive list-searching functions @code{memq}, @code{member},
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
433 @code{assq}, or @code{assoc} is even faster than explicit iteration. It
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
434 can be worth rearranging a data structure so that one of these primitive
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
435 search functions can be used.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437 @item
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44733
diff changeset
438 Certain built-in functions are handled specially in byte-compiled code,
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439 avoiding the need for an ordinary function call. It is a good idea to
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440 use these functions rather than alternatives. To see whether a function
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 is handled specially by the compiler, examine its @code{byte-compile}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 property. If the property is non-@code{nil}, then the function is
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 handled specially.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 For example, the following input will show you that @code{aref} is
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
446 compiled specially (@pxref{Array Functions}):
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
448 @example
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 (get 'aref 'byte-compile)
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 @result{} byte-compile-two-args
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 @end group
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
453 @end example
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455 @item
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
456 If calling a small function accounts for a substantial part of your
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 program's running time, make the function inline. This eliminates
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 the function call overhead. Since making a function inline reduces
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 the flexibility of changing the program, don't do it unless it gives
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
460 a noticeable speedup in something slow enough that users care about
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 the speed. @xref{Inline Functions}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 @end itemize
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 @node Documentation Tips
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 @section Tips for Documentation Strings
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
467 @findex checkdoc-minor-mode
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
468 Here are some tips and conventions for the writing of documentation
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
469 strings. You can check many of these conventions by running the command
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
470 @kbd{M-x checkdoc-minor-mode}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 @itemize @bullet
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473 @item
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6959
diff changeset
474 Every command, function, or variable intended for users to know about
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475 should have a documentation string.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 @item
10225
2e5dcd5f3090 Recommend doc strings for all functions and variables.
Richard M. Stallman <rms@gnu.org>
parents: 9807
diff changeset
478 An internal variable or subroutine of a Lisp program might as well have
2e5dcd5f3090 Recommend doc strings for all functions and variables.
Richard M. Stallman <rms@gnu.org>
parents: 9807
diff changeset
479 a documentation string. In earlier Emacs versions, you could save space
2e5dcd5f3090 Recommend doc strings for all functions and variables.
Richard M. Stallman <rms@gnu.org>
parents: 9807
diff changeset
480 by using a comment instead of a documentation string, but that is no
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
481 longer the case---documentation strings now take up very little space in
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
482 a running Emacs.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484 @item
42979
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
485 Format the documentation string so that it fits in an Emacs window on an
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
486 80-column screen. It is a good idea for most lines to be no wider than
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
487 60 characters. The first line should not be wider than 67 characters
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
488 or it will look bad in the output of @code{apropos}.
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
489
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
490 You can fill the text if that looks good. However, rather than blindly
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
491 filling the entire documentation string, you can often make it much more
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
492 readable by choosing certain line breaks with care. Use blank lines
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
493 between topics if the documentation string is long.
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
494
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
495 @item
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496 The first line of the documentation string should consist of one or two
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6959
diff changeset
497 complete sentences that stand on their own as a summary. @kbd{M-x
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
498 apropos} displays just the first line, and if that line's contents don't
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
499 stand on their own, the result looks bad. In particular, start the
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
500 first line with a capital letter and end with a period.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
501
40970
fb31125d0d7b Say what questions first line of doc string should answer.
Richard M. Stallman <rms@gnu.org>
parents: 40561
diff changeset
502 For a function, the first line should briefly answer the question,
fb31125d0d7b Say what questions first line of doc string should answer.
Richard M. Stallman <rms@gnu.org>
parents: 40561
diff changeset
503 ``What does this function do?'' For a variable, the first line should
fb31125d0d7b Say what questions first line of doc string should answer.
Richard M. Stallman <rms@gnu.org>
parents: 40561
diff changeset
504 briefly answer the question, ``What does this value mean?''
fb31125d0d7b Say what questions first line of doc string should answer.
Richard M. Stallman <rms@gnu.org>
parents: 40561
diff changeset
505
fb31125d0d7b Say what questions first line of doc string should answer.
Richard M. Stallman <rms@gnu.org>
parents: 40561
diff changeset
506 Don't limit the documentation string to one line; use as many lines as
fb31125d0d7b Say what questions first line of doc string should answer.
Richard M. Stallman <rms@gnu.org>
parents: 40561
diff changeset
507 you need to explain the details of how to use the function or
fb31125d0d7b Say what questions first line of doc string should answer.
Richard M. Stallman <rms@gnu.org>
parents: 40561
diff changeset
508 variable. Please use complete sentences for the rest of the text too.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
509
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
510 @item
49960
10a8aba3dfc7 First line of function doc string should mention the most important
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
511 The first line should mention all the important arguments of the
10a8aba3dfc7 First line of function doc string should mention the most important
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
512 function, and should mention them in the order that they are written
10a8aba3dfc7 First line of function doc string should mention the most important
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
513 in a function call. If the function has many arguments, then it is
10a8aba3dfc7 First line of function doc string should mention the most important
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
514 not feasible to mention them all in the first line; in that case, the
10a8aba3dfc7 First line of function doc string should mention the most important
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
515 first line should mention the first few arguments, including the most
10a8aba3dfc7 First line of function doc string should mention the most important
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
516 important arguments.
10a8aba3dfc7 First line of function doc string should mention the most important
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
517
10a8aba3dfc7 First line of function doc string should mention the most important
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
518 @item
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
519 For consistency, phrase the verb in the first sentence of a function's
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
520 documentation string as an imperative--for instance, use ``Return the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
521 cons of A and B.'' in preference to ``Returns the cons of A and B@.''
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
522 Usually it looks good to do likewise for the rest of the first
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
523 paragraph. Subsequent paragraphs usually look better if each sentence
42979
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
524 is indicative and has a proper subject.
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
525
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
526 @item
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 Write documentation strings in the active voice, not the passive, and in
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
528 the present tense, not the future. For instance, use ``Return a list
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529 containing A and B.'' instead of ``A list containing A and B will be
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
530 returned.''
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
531
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
532 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
533 Avoid using the word ``cause'' (or its equivalents) unnecessarily.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534 Instead of, ``Cause Emacs to display text in boldface,'' write just
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 ``Display text in boldface.''
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537 @item
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
538 When a command is meaningful only in a certain mode or situation,
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
539 do mention that in the documentation string. For example,
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
540 the documentation of @code{dired-find-file} is:
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
541
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
542 @example
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
543 In Dired, visit the file or directory named on this line.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
544 @end example
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
545
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
546 @item
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 Do not start or end a documentation string with whitespace.
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44733
diff changeset
548
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550 @strong{Do not} indent subsequent lines of a documentation string so
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 that the text is lined up in the source code with the text of the first
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552 line. This looks nice in the source code, but looks bizarre when users
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553 view the documentation. Remember that the indentation before the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554 starting double-quote is not part of the string!
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556 @item
16671
9fa09185bca0 Explain how disabled commands' doc strings are displayed.
Richard M. Stallman <rms@gnu.org>
parents: 15198
diff changeset
557 When the user tries to use a disabled command, Emacs displays just the
9fa09185bca0 Explain how disabled commands' doc strings are displayed.
Richard M. Stallman <rms@gnu.org>
parents: 15198
diff changeset
558 first paragraph of its documentation string---everything through the
9fa09185bca0 Explain how disabled commands' doc strings are displayed.
Richard M. Stallman <rms@gnu.org>
parents: 15198
diff changeset
559 first blank line. If you wish, you can choose which information to
9fa09185bca0 Explain how disabled commands' doc strings are displayed.
Richard M. Stallman <rms@gnu.org>
parents: 15198
diff changeset
560 include before the first blank line so as to make this display useful.
9fa09185bca0 Explain how disabled commands' doc strings are displayed.
Richard M. Stallman <rms@gnu.org>
parents: 15198
diff changeset
561
9fa09185bca0 Explain how disabled commands' doc strings are displayed.
Richard M. Stallman <rms@gnu.org>
parents: 15198
diff changeset
562 @item
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 A variable's documentation string should start with @samp{*} if the
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
564 variable is one that users would often want to set interactively. If
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6959
diff changeset
565 the value is a long list, or a function, or if the variable would be set
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6959
diff changeset
566 only in init files, then don't start the documentation string with
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567 @samp{*}. @xref{Defining Variables}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
568
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570 The documentation string for a variable that is a yes-or-no flag should
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
571 start with words such as ``Non-nil means@dots{}'', to make it clear that
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
572 all non-@code{nil} values are equivalent and indicate explicitly what
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
573 @code{nil} and non-@code{nil} mean.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 @item
40517
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
576 The documentation string for a function that is a yes-or-no predicate
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
577 should start with words such as ``Return t if @dots{}'', to indicate
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
578 explicitly what constitutes ``truth''. The word ``return'' avoids
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
579 starting the sentence with lower-case ``t'', which is somewhat
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
580 distracting.
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
581
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
582 @item
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583 When a function's documentation string mentions the value of an argument
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584 of the function, use the argument name in capital letters as if it were
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585 a name for that value. Thus, the documentation string of the function
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
586 @code{eval} refers to its second argument as @samp{FORM}, because the
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
587 actual argument name is @code{form}:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
589 @example
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
590 Evaluate FORM and return its value.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
591 @end example
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
592
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
593 Also write metasyntactic variables in capital letters, such as when you
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
594 show the decomposition of a list or vector into subunits, some of which
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
595 may vary. @samp{KEY} and @samp{VALUE} in the following example
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
596 illustrate this practice:
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
597
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
598 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
599 The argument TABLE should be an alist whose elements
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
600 have the form (KEY . VALUE). Here, KEY is ...
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
601 @end example
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
603 @item
40517
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
604 Never change the case of a Lisp symbol when you mention it in a doc
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
605 string. If the symbol's name is @code{foo}, write ``foo'', not
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
606 ``Foo'' (which is a different symbol).
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
607
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
608 This might appear to contradict the policy of writing function
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
609 argument values, but there is no real contradiction; the argument
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
610 @emph{value} is not the same thing as the @emph{symbol} which the
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
611 function uses to hold the value.
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
612
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
613 If this puts a lower-case letter at the beginning of a sentence
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
614 and that annoys you, rewrite the sentence so that the symbol
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
615 is not at the start of it.
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
616
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
617 @item
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
618 If a line in a documentation string begins with an open-parenthesis,
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
619 write a backslash before the open-parenthesis, like this:
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
620
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
621 @example
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
622 The argument FOO can be either a number
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
623 \(a buffer position) or a string (a file name).
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
624 @end example
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
625
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
626 This prevents the open-parenthesis from being treated as the start of a
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
627 defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
628
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
629 @item
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630 @iftex
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
631 When a documentation string refers to a Lisp symbol, write it as it
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632 would be printed (which usually means in lower case), with single-quotes
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633 around it. For example: @samp{`lambda'}. There are two exceptions:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 write @code{t} and @code{nil} without single-quotes.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635 @end iftex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
636 @ifnottex
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637 When a documentation string refers to a Lisp symbol, write it as it
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638 would be printed (which usually means in lower case), with single-quotes
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639 around it. For example: @samp{lambda}. There are two exceptions: write
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
640 t and nil without single-quotes. (In this manual, we use a different
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
641 convention, with single-quotes for all symbols.)
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
642 @end ifnottex
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
643
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
644 Help mode automatically creates a hyperlink when a documentation string
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
645 uses a symbol name inside single quotes, if the symbol has either a
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
646 function or a variable definition. You do not need to do anything
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
647 special to make use of this feature. However, when a symbol has both a
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
648 function definition and a variable definition, and you want to refer to
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
649 just one of them, you can specify which one by writing one of the words
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
650 @samp{variable}, @samp{option}, @samp{function}, or @samp{command},
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
651 immediately before the symbol name. (Case makes no difference in
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
652 recognizing these indicator words.) For example, if you write
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
653
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
654 @example
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
655 This function sets the variable `buffer-file-name'.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
656 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
657
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
658 @noindent
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
659 then the hyperlink will refer only to the variable documentation of
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
660 @code{buffer-file-name}, and not to its function documentation.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
661
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
662 If a symbol has a function definition and/or a variable definition, but
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
663 those are irrelevant to the use of the symbol that you are documenting,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
664 you can write the word @samp{symbol} before the symbol name to prevent
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
665 making any hyperlink. For example,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
666
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
667 @example
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
668 If the argument KIND-OF-RESULT is the symbol `list',
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
669 this function returns a list of all the objects
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
670 that satisfy the criterion.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
671 @end example
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
672
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
673 @noindent
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
674 does not make a hyperlink to the documentation, irrelevant here, of the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
675 function @code{list}.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
676
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
677 To make a hyperlink to Info documentation, write the name of the Info
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
678 node in single quotes, preceded by @samp{info node} or @samp{Info
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
679 node}. The Info file name defaults to @samp{emacs}. For example,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
680
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
681 @smallexample
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
682 See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
683 @end smallexample
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
684
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
686 Don't write key sequences directly in documentation strings. Instead,
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
687 use the @samp{\\[@dots{}]} construct to stand for them. For example,
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 16671
diff changeset
688 instead of writing @samp{C-f}, write the construct
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 16671
diff changeset
689 @samp{\\[forward-char]}. When Emacs displays the documentation string,
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 16671
diff changeset
690 it substitutes whatever key is currently bound to @code{forward-char}.
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 16671
diff changeset
691 (This is normally @samp{C-f}, but it may be some other character if the
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 16671
diff changeset
692 user has moved key bindings.) @xref{Keys in Documentation}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
694 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
695 In documentation strings for a major mode, you will want to refer to the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
696 key bindings of that mode's local map, rather than global ones.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
697 Therefore, use the construct @samp{\\<@dots{}>} once in the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
698 documentation string to specify which key map to use. Do this before
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
699 the first use of @samp{\\[@dots{}]}. The text inside the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
700 @samp{\\<@dots{}>} should be the name of the variable containing the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
701 local keymap for the major mode.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
702
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
703 It is not practical to use @samp{\\[@dots{}]} very many times, because
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
704 display of the documentation string will become slow. So use this to
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705 describe the most important commands in your major mode, and then use
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
706 @samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
707 @end itemize
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
709 @node Comment Tips
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
710 @section Tips on Writing Comments
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
711
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
712 We recommend these conventions for where to put comments and how to
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
713 indent them:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
714
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
715 @table @samp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
716 @item ;
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
717 Comments that start with a single semicolon, @samp{;}, should all be
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
718 aligned to the same column on the right of the source code. Such
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719 comments usually explain how the code on the same line does its job. In
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720 Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment})
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
721 command automatically inserts such a @samp{;} in the right place, or
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
722 aligns such a comment if it is already present.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6959
diff changeset
724 This and following examples are taken from the Emacs sources.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726 @smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728 (setq base-version-list ; there was a base
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 (assoc (substring fn 0 start-vn) ; version to which
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730 file-version-assoc-list)) ; this looks like
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731 ; a subversion
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733 @end smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
735 @item ;;
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
736 Comments that start with two semicolons, @samp{;;}, should be aligned to
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
737 the same level of indentation as the code. Such comments usually
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
738 describe the purpose of the following lines or the state of the program
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
739 at that point. For example:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
740
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
741 @smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
742 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
743 (prog1 (setq auto-fill-function
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744 @dots{}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
745 @dots{}
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
746 ;; update mode line
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
747 (force-mode-line-update)))
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
748 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
749 @end smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
750
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
751 We also normally use two semicolons for comments outside functions.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
752
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
753 @smallexample
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
754 @group
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
755 ;; This Lisp code is run in Emacs
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
756 ;; when it is to operate as a server
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
757 ;; for other processes.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
758 @end group
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
759 @end smallexample
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
760
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
761 Every function that has no documentation string (presumably one that is
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
762 used only internally within the package it belongs to), should instead
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
763 have a two-semicolon comment right before the function, explaining what
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
764 the function does and how to call it properly. Explain precisely what
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
765 each argument means and how the function interprets its possible values.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
766
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
767 @item ;;;
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
768 Comments that start with three semicolons, @samp{;;;}, should start at
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
769 the left margin. These are used, occasionally, for comments within
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
770 functions that should start at the margin. We also use them sometimes
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
771 for comments that are between functions---whether to use two or three
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
772 semicolons there is a matter of style.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
773
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6959
diff changeset
774 Another use for triple-semicolon comments is for commenting out lines
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
775 within a function. We use three semicolons for this precisely so that
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
776 they remain at the left margin.
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
777
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
778 @smallexample
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
779 (defun foo (a)
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
780 ;;; This is no longer necessary.
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
781 ;;; (force-mode-line-update)
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
782 (message "Finished with %s" a))
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
783 @end smallexample
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
784
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
785 @item ;;;;
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
786 Comments that start with four semicolons, @samp{;;;;}, should be aligned
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
787 to the left margin and are used for headings of major sections of a
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
788 program. For example:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
789
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
790 @smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791 ;;;; The kill ring
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
792 @end smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
793 @end table
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
794
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
795 @noindent
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796 The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
797 (@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}),
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
798 automatically indent comments according to these conventions,
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6959
diff changeset
799 depending on the number of semicolons. @xref{Comments,,
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
800 Manipulating Comments, emacs, The GNU Emacs Manual}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
802 @node Library Headers
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
803 @section Conventional Headers for Emacs Libraries
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
804 @cindex header comments
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
805 @cindex library header comments
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
806
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
807 Emacs has conventions for using special comments in Lisp libraries
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
808 to divide them into sections and give information such as who wrote
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
809 them. This section explains these conventions.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
810
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
811 We'll start with an example, a package that is included in the Emacs
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
812 distribution.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
813
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
814 Parts of this example reflect its status as part of Emacs; for
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
815 example, the copyright notice lists the Free Software Foundation as the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
816 copyright holder, and the copying permission says the file is part of
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
817 Emacs. When you write a package and post it, the copyright holder would
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
818 be you (unless your employer claims to own it instead), and you should
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
819 get the suggested copying permission from the end of the GNU General
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
820 Public License itself. Don't say your file is part of Emacs
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
821 if we haven't installed it in Emacs yet!
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
822
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
823 With that warning out of the way, on to the example:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
824
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
825 @smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
826 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
827 ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829 ;; Copyright (C) 1992 Free Software Foundation, Inc.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
832 ;; Author: Eric S. Raymond <esr@@snark.thyrsus.com>
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
833 ;; Maintainer: Eric S. Raymond <esr@@snark.thyrsus.com>
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
834 ;; Created: 14 Jul 1992
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835 ;; Version: 1.2
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837 ;; Keywords: docs
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839 ;; This file is part of GNU Emacs.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
840 @dots{}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
841 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
842 ;; Boston, MA 02111-1307, USA.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
844 @end smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
845
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
846 The very first line should have this format:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
847
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
848 @example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
849 ;;; @var{filename} --- @var{description}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
850 @end example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
851
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
852 @noindent
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853 The description should be complete in one line.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855 After the copyright notice come several @dfn{header comment} lines,
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
856 each beginning with @samp{;; @var{header-name}:}. Here is a table of
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
857 the conventional possibilities for @var{header-name}:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
858
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859 @table @samp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 @item Author
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861 This line states the name and net address of at least the principal
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862 author of the library.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
863
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
864 If there are multiple authors, you can list them on continuation lines
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
865 led by @code{;;} and a tab character, like this:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
866
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
867 @smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
868 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
869 ;; Author: Ashwin Ram <Ram-Ashwin@@cs.yale.edu>
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
870 ;; Dave Sill <de5@@ornl.gov>
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
871 ;; Dave Brennan <brennan@@hal.com>
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
872 ;; Eric Raymond <esr@@snark.thyrsus.com>
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
873 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
874 @end smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
875
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
876 @item Maintainer
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
877 This line should contain a single name/address as in the Author line, or
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
878 an address only, or the string @samp{FSF}. If there is no maintainer
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
879 line, the person(s) in the Author field are presumed to be the
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
880 maintainers. The example above is mildly bogus because the maintainer
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
881 line is redundant.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
882
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
883 The idea behind the @samp{Author} and @samp{Maintainer} lines is to make
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
884 possible a Lisp function to ``send mail to the maintainer'' without
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
885 having to mine the name out by hand.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
886
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
887 Be sure to surround the network address with @samp{<@dots{}>} if
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
888 you include the person's full name as well as the network address.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
889
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
890 @item Created
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
891 This optional line gives the original creation date of the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
892 file. For historical interest only.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
893
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
894 @item Version
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
895 If you wish to record version numbers for the individual Lisp program, put
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
896 them in this line.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
897
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
898 @item Adapted-By
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
899 In this header line, place the name of the person who adapted the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
900 library for installation (to make it fit the style conventions, for
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
901 example).
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
902
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
903 @item Keywords
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
904 This line lists keywords for the @code{finder-by-keyword} help command.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
905 Please use that command to see a list of the meaningful keywords.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
906
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
907 This field is important; it's how people will find your package when
10229
634f36d4b2ae Give syntax of keywords.
Richard M. Stallman <rms@gnu.org>
parents: 10225
diff changeset
908 they're looking for things by topic area. To separate the keywords, you
634f36d4b2ae Give syntax of keywords.
Richard M. Stallman <rms@gnu.org>
parents: 10225
diff changeset
909 can use spaces, commas, or both.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
910 @end table
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
911
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
912 Just about every Lisp library ought to have the @samp{Author} and
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
913 @samp{Keywords} header comment lines. Use the others if they are
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
914 appropriate. You can also put in header lines with other header
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
915 names---they have no standard meanings, so they can't do any harm.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
916
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
917 We use additional stylized comments to subdivide the contents of the
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
918 library file. These should be separated by blank lines from anything
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
919 else. Here is a table of them:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
920
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
921 @table @samp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
922 @item ;;; Commentary:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
923 This begins introductory comments that explain how the library works.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
924 It should come right after the copying permissions, terminated by a
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
925 @samp{Change Log}, @samp{History} or @samp{Code} comment line. This
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
926 text is used by the Finder package, so it should make sense in that
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
927 context.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
928
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
929 @item ;;; Documentation
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
930 This has been used in some files in place of @samp{;;; Commentary:},
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
931 but @samp{;;; Commentary:} is preferred.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
932
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
933 @item ;;; Change Log:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
934 This begins change log information stored in the library file (if you
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
935 store the change history there). For Lisp files distributed with Emacs,
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
936 the change history is kept in the file @file{ChangeLog} and not in the
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
937 source file at all; these files generally do not have a @samp{;;; Change
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
938 Log:} line. @samp{History} is an alternative to @samp{Change Log}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
939
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940 @item ;;; Code:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
941 This begins the actual code of the program.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
942
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
943 @item ;;; @var{filename} ends here
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944 This is the @dfn{footer line}; it appears at the very end of the file.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
945 Its purpose is to enable people to detect truncated versions of the file
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
946 from the lack of a footer line.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
947 @end table