annotate lispref/tips.texi @ 78377:8a9d5af6fdf2

Fix parent groups link
author Vinicius Jose Latorre <viniciusjl@ig.com.br>
date Wed, 01 Aug 2007 01:18:37 +0000
parents 665e86db2a21
children a3be21a96dd1 f55f9811f5d7
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.
75250
6d19c76d81c5 Update copyright for years from Emacs 21 to present (mainly adding
Glenn Morris <rgm@gnu.org>
parents: 75222
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998, 1999, 2001, 2002,
6d19c76d81c5 Update copyright for years from Emacs 21 to present (mainly adding
Glenn Morris <rgm@gnu.org>
parents: 75222
diff changeset
4 @c 2003, 2004, 2005, 2006, 2007 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
76993
55c9ef5f1559 Improve index entries.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
9 @cindex tips for writing Lisp
6552
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.
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
26 * Key Binding Conventions:: Which keys should be bound by which programs.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
27 * Programming Tips:: Making Emacs code fit smoothly in Emacs.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 * Compilation Tips:: Making compiled code run fast.
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
29 * Warning Tips:: Turning off compiler warnings.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 * Documentation Tips:: Writing readable documentation strings.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 * Comment Tips:: Conventions for writing comments.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 * Library Headers:: Standard headers for library packages.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33 @end menu
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 @node Coding Conventions
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
36 @section Emacs Lisp Coding Conventions
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37
70969
044c7ca7a4ff (Coding Conventions): Advise against using eval-after-load in packages.
Eli Zaretskii <eliz@gnu.org>
parents: 70090
diff changeset
38 @cindex coding conventions in Emacs Lisp
17280
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
39 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
40 code intended for widespread use:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 @itemize @bullet
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 @item
62331
551071b66329 (Coding Conventions): Explain how important it is
Richard M. Stallman <rms@gnu.org>
parents: 61056
diff changeset
44 Simply loading the package should not change Emacs's editing behavior.
551071b66329 (Coding Conventions): Explain how important it is
Richard M. Stallman <rms@gnu.org>
parents: 61056
diff changeset
45 Include a command or commands to enable and disable the feature,
551071b66329 (Coding Conventions): Explain how important it is
Richard M. Stallman <rms@gnu.org>
parents: 61056
diff changeset
46 or to invoke it.
551071b66329 (Coding Conventions): Explain how important it is
Richard M. Stallman <rms@gnu.org>
parents: 61056
diff changeset
47
551071b66329 (Coding Conventions): Explain how important it is
Richard M. Stallman <rms@gnu.org>
parents: 61056
diff changeset
48 This convention is mandatory for any file that includes custom
551071b66329 (Coding Conventions): Explain how important it is
Richard M. Stallman <rms@gnu.org>
parents: 61056
diff changeset
49 definitions. If fixing such a file to follow this convention requires
551071b66329 (Coding Conventions): Explain how important it is
Richard M. Stallman <rms@gnu.org>
parents: 61056
diff changeset
50 an incompatible change, go ahead and make the incompatible change;
551071b66329 (Coding Conventions): Explain how important it is
Richard M. Stallman <rms@gnu.org>
parents: 61056
diff changeset
51 don't postpone it.
551071b66329 (Coding Conventions): Explain how important it is
Richard M. Stallman <rms@gnu.org>
parents: 61056
diff changeset
52
551071b66329 (Coding Conventions): Explain how important it is
Richard M. Stallman <rms@gnu.org>
parents: 61056
diff changeset
53 @item
38162
40606e2d6b31 Minor change.
Richard M. Stallman <rms@gnu.org>
parents: 38043
diff changeset
54 Since all global variables share the same name space, and all
40606e2d6b31 Minor change.
Richard M. Stallman <rms@gnu.org>
parents: 38043
diff changeset
55 functions share another name space, you should choose a short word to
70969
044c7ca7a4ff (Coding Conventions): Advise against using eval-after-load in packages.
Eli Zaretskii <eliz@gnu.org>
parents: 70090
diff changeset
56 distinguish your program from other Lisp programs@footnote{The
38162
40606e2d6b31 Minor change.
Richard M. Stallman <rms@gnu.org>
parents: 38043
diff changeset
57 benefits of a Common Lisp-style package system are considered not to
70969
044c7ca7a4ff (Coding Conventions): Advise against using eval-after-load in packages.
Eli Zaretskii <eliz@gnu.org>
parents: 70090
diff changeset
58 outweigh the costs.}. Then take care to begin the names of all global
38162
40606e2d6b31 Minor change.
Richard M. Stallman <rms@gnu.org>
parents: 38043
diff changeset
59 variables, constants, and functions in your program with the chosen
70090
67a078792729 (Coding Conventions): Explain when the package's
Richard M. Stallman <rms@gnu.org>
parents: 69590
diff changeset
60 prefix. This helps avoid name conflicts.
67a078792729 (Coding Conventions): Explain when the package's
Richard M. Stallman <rms@gnu.org>
parents: 69590
diff changeset
61
67a078792729 (Coding Conventions): Explain when the package's
Richard M. Stallman <rms@gnu.org>
parents: 69590
diff changeset
62 Occasionally, for a command name intended for users to use, it is more
67a078792729 (Coding Conventions): Explain when the package's
Richard M. Stallman <rms@gnu.org>
parents: 69590
diff changeset
63 convenient if some words come before the package's name prefix. And
67a078792729 (Coding Conventions): Explain when the package's
Richard M. Stallman <rms@gnu.org>
parents: 69590
diff changeset
64 constructs that define functions, variables, etc., work better if they
67a078792729 (Coding Conventions): Explain when the package's
Richard M. Stallman <rms@gnu.org>
parents: 69590
diff changeset
65 start with @samp{defun} or @samp{defvar}, so put the name prefix later
67a078792729 (Coding Conventions): Explain when the package's
Richard M. Stallman <rms@gnu.org>
parents: 69590
diff changeset
66 on in the name.
6552
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 This recommendation applies even to names for traditional Lisp
60273
a0cca815ceaa (Coding Conventions): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 58323
diff changeset
69 primitives that are not primitives in Emacs Lisp---such as
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
70 @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
71 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
72 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
73 instead.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 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
76 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
77 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
78 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
79 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
80
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
81 If one prefix is insufficient, your package can use two or three
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82 alternative common prefixes, so long as they make sense.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 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
85 @samp{-}. This will be consistent with Emacs itself and with most Emacs
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86 Lisp programs.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88 @item
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
89 Put a call to @code{provide} at the end of each separate Lisp file.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91 @item
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
92 If a file requires certain other Lisp programs to be loaded
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
93 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
94 so. Also, use @code{require} to make sure they are loaded.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
95
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
96 @item
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97 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
98 @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
99 macro:
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
100
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
101 @example
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
102 (eval-when-compile (require '@var{bar}))
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
103 @end example
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
104
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
105 @noindent
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
106 (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
107 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
108 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
109 @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
110 compiled code that won't work right. @xref{Compiling Macros}.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
111
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
112 Using @code{eval-when-compile} avoids loading @var{bar} when
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
113 the compiled version of @var{foo} is @emph{used}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115 @item
24799
7f38d541d411 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22635
diff changeset
116 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
117 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
118 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
119 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
120
71770
8837b6008e64 Modify last change.
Nick Roberts <nickrob@snap.net.nz>
parents: 71769
diff changeset
121 However, there is no problem with using the @code{cl} package at
71855
0fa817d8a084 (Coding Conventions): Explain why use cl at compile time.
Richard M. Stallman <rms@gnu.org>
parents: 71770
diff changeset
122 compile time, with @code{(eval-when-compile (require 'cl))}. That's
0fa817d8a084 (Coding Conventions): Explain why use cl at compile time.
Richard M. Stallman <rms@gnu.org>
parents: 71770
diff changeset
123 sufficient for using the macros in the @code{cl} package, because the
0fa817d8a084 (Coding Conventions): Explain why use cl at compile time.
Richard M. Stallman <rms@gnu.org>
parents: 71770
diff changeset
124 compiler expands them before generating the byte-code.
24799
7f38d541d411 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22635
diff changeset
125
7f38d541d411 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22635
diff changeset
126 @item
17280
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
127 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
128 conventions. @xref{Major Mode Conventions}.
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
129
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
130 @item
96762d1abb7c (Coding Conventions): Node renamed from Style Tips.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
131 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
132 conventions. @xref{Minor Mode Conventions}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 @item
9807
d5fa87d62d62 Add function and variable name conventions.
Richard M. Stallman <rms@gnu.org>
parents: 9393
diff changeset
135 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
136 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
137 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
138 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
139
d5fa87d62d62 Add function and variable name conventions.
Richard M. Stallman <rms@gnu.org>
parents: 9393
diff changeset
140 @item
d5fa87d62d62 Add function and variable name conventions.
Richard M. Stallman <rms@gnu.org>
parents: 9393
diff changeset
141 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
142 name that ends in @samp{-flag}.
d5fa87d62d62 Add function and variable name conventions.
Richard M. Stallman <rms@gnu.org>
parents: 9393
diff changeset
143
d5fa87d62d62 Add function and variable name conventions.
Richard M. Stallman <rms@gnu.org>
parents: 9393
diff changeset
144 @item
52769
00608f913b6f (Coding Conventions): Mention naming conventions for hooks.
Lute Kamstra <lute@gnu.org>
parents: 52401
diff changeset
145 If the purpose of a variable is to store a single function, give it a
00608f913b6f (Coding Conventions): Mention naming conventions for hooks.
Lute Kamstra <lute@gnu.org>
parents: 52401
diff changeset
146 name that ends in @samp{-function}. If the purpose of a variable is
00608f913b6f (Coding Conventions): Mention naming conventions for hooks.
Lute Kamstra <lute@gnu.org>
parents: 52401
diff changeset
147 to store a list of functions (i.e., the variable is a hook), please
00608f913b6f (Coding Conventions): Mention naming conventions for hooks.
Lute Kamstra <lute@gnu.org>
parents: 52401
diff changeset
148 follow the naming conventions for hooks. @xref{Hooks}.
00608f913b6f (Coding Conventions): Mention naming conventions for hooks.
Lute Kamstra <lute@gnu.org>
parents: 52401
diff changeset
149
00608f913b6f (Coding Conventions): Mention naming conventions for hooks.
Lute Kamstra <lute@gnu.org>
parents: 52401
diff changeset
150 @item
76993
55c9ef5f1559 Improve index entries.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
151 @cindex unloading packages, preparing for
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
152 If loading the file adds functions to hooks, define a function
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
153 @code{@var{feature}-unload-hook}, where @var{feature} is the name of
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
154 the feature the package provides, and make it undo any such changes.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
155 Using @code{unload-feature} to unload the file will run this function.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
156 @xref{Unloading}.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
157
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
158 @item
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
159 It is a bad idea to define aliases for the Emacs primitives. Normally
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
160 you should use the standard names instead. The case where an alias
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
161 may be useful is where it facilitates backwards compatibility or
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
162 portability.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
163
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
164 @item
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
165 If a package needs to define an alias or a new function for
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
166 compatibility with some other version of Emacs, name it with the package
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
167 prefix, not with the raw name with which it occurs in the other version.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
168 Here is an example from Gnus, which provides many examples of such
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
169 compatibility issues.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
170
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
171 @example
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
172 (defalias 'gnus-point-at-bol
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
173 (if (fboundp 'point-at-bol)
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
174 'point-at-bol
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
175 'line-beginning-position))
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
176 @end example
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
177
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
178 @item
71036
2a973dfbccc2 (Coding Conventions): Better explain reasons not to
Richard M. Stallman <rms@gnu.org>
parents: 70969
diff changeset
179 Redefining (or advising) an Emacs primitive is a bad idea. It may do
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
180 the right thing for a particular program, but there is no telling what
71036
2a973dfbccc2 (Coding Conventions): Better explain reasons not to
Richard M. Stallman <rms@gnu.org>
parents: 70969
diff changeset
181 other programs might break as a result. In any case, it is a problem
71642
fa9d190c602e (Coding Conventions): Cleanup last change.
Richard M. Stallman <rms@gnu.org>
parents: 71638
diff changeset
182 for debugging, because the advised function doesn't do what its source
fa9d190c602e (Coding Conventions): Cleanup last change.
Richard M. Stallman <rms@gnu.org>
parents: 71638
diff changeset
183 code says it does. If the programmer investigating the problem is
fa9d190c602e (Coding Conventions): Cleanup last change.
Richard M. Stallman <rms@gnu.org>
parents: 71638
diff changeset
184 unaware that there is advice on the function, the experience can be
71036
2a973dfbccc2 (Coding Conventions): Better explain reasons not to
Richard M. Stallman <rms@gnu.org>
parents: 70969
diff changeset
185 very frustrating.
2a973dfbccc2 (Coding Conventions): Better explain reasons not to
Richard M. Stallman <rms@gnu.org>
parents: 70969
diff changeset
186
2a973dfbccc2 (Coding Conventions): Better explain reasons not to
Richard M. Stallman <rms@gnu.org>
parents: 70969
diff changeset
187 We hope to remove all the places in Emacs that advise primitives.
2a973dfbccc2 (Coding Conventions): Better explain reasons not to
Richard M. Stallman <rms@gnu.org>
parents: 70969
diff changeset
188 In the mean time, please don't add any more.
2a973dfbccc2 (Coding Conventions): Better explain reasons not to
Richard M. Stallman <rms@gnu.org>
parents: 70969
diff changeset
189
2a973dfbccc2 (Coding Conventions): Better explain reasons not to
Richard M. Stallman <rms@gnu.org>
parents: 70969
diff changeset
190 @item
2a973dfbccc2 (Coding Conventions): Better explain reasons not to
Richard M. Stallman <rms@gnu.org>
parents: 70969
diff changeset
191 It is likewise a bad idea for one Lisp package to advise a function
2a973dfbccc2 (Coding Conventions): Better explain reasons not to
Richard M. Stallman <rms@gnu.org>
parents: 70969
diff changeset
192 in another Lisp package.
70969
044c7ca7a4ff (Coding Conventions): Advise against using eval-after-load in packages.
Eli Zaretskii <eliz@gnu.org>
parents: 70090
diff changeset
193
044c7ca7a4ff (Coding Conventions): Advise against using eval-after-load in packages.
Eli Zaretskii <eliz@gnu.org>
parents: 70090
diff changeset
194 @item
044c7ca7a4ff (Coding Conventions): Advise against using eval-after-load in packages.
Eli Zaretskii <eliz@gnu.org>
parents: 70090
diff changeset
195 Likewise, avoid using @code{eval-after-load} (@pxref{Hooks for
044c7ca7a4ff (Coding Conventions): Advise against using eval-after-load in packages.
Eli Zaretskii <eliz@gnu.org>
parents: 70090
diff changeset
196 Loading}) in libraries and packages. This feature is meant for
71642
fa9d190c602e (Coding Conventions): Cleanup last change.
Richard M. Stallman <rms@gnu.org>
parents: 71638
diff changeset
197 personal customizations; using it in a Lisp program is unclean,
fa9d190c602e (Coding Conventions): Cleanup last change.
Richard M. Stallman <rms@gnu.org>
parents: 71638
diff changeset
198 because it modifies the behavior of another Lisp file in a way that's
fa9d190c602e (Coding Conventions): Cleanup last change.
Richard M. Stallman <rms@gnu.org>
parents: 71638
diff changeset
199 not visible in that file. This is an obstacle for debugging, much
fa9d190c602e (Coding Conventions): Cleanup last change.
Richard M. Stallman <rms@gnu.org>
parents: 71638
diff changeset
200 like advising a function in the other package.
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
201
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
202 @item
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
203 If a file does replace any of the functions or library programs of
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
204 standard Emacs, prominent comments at the beginning of the file should
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
205 say which functions are replaced, and how the behavior of the
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
206 replacements differs from that of the originals.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
207
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
208 @item
71375
706e41b8c07f (Coding Conventions): Better explain conventions for definition constructs.
Richard M. Stallman <rms@gnu.org>
parents: 71314
diff changeset
209 Constructs that define a function or variable should be macros,
706e41b8c07f (Coding Conventions): Better explain conventions for definition constructs.
Richard M. Stallman <rms@gnu.org>
parents: 71314
diff changeset
210 not functions, and their names should start with @samp{def}.
706e41b8c07f (Coding Conventions): Better explain conventions for definition constructs.
Richard M. Stallman <rms@gnu.org>
parents: 71314
diff changeset
211
706e41b8c07f (Coding Conventions): Better explain conventions for definition constructs.
Richard M. Stallman <rms@gnu.org>
parents: 71314
diff changeset
212 @item
75477
afd36ac582f5 (Coding Conventions): Clarify the tip about macros
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
213 A macro that defines a function or variable should have a name that
afd36ac582f5 (Coding Conventions): Clarify the tip about macros
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
214 starts with @samp{define-}. The macro should receive the name to be
71375
706e41b8c07f (Coding Conventions): Better explain conventions for definition constructs.
Richard M. Stallman <rms@gnu.org>
parents: 71314
diff changeset
215 defined as the first argument. That will help various tools find the
706e41b8c07f (Coding Conventions): Better explain conventions for definition constructs.
Richard M. Stallman <rms@gnu.org>
parents: 71314
diff changeset
216 definition automatically. Avoid constructing the names in the macro
706e41b8c07f (Coding Conventions): Better explain conventions for definition constructs.
Richard M. Stallman <rms@gnu.org>
parents: 71314
diff changeset
217 itself, since that would confuse these tools.
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
218
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
219 @item
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
220 Please keep the names of your Emacs Lisp source files to 13 characters
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
221 or less. This way, if the files are compiled, the compiled files' names
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
222 will be 14 characters or less, which is short enough to fit on all kinds
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
223 of Unix systems.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
224
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
225 @item
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
226 In some other systems there is a convention of choosing variable names
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
227 that begin and end with @samp{*}. We don't use that convention in Emacs
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
228 Lisp, so please don't use it in your programs. (Emacs uses such names
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
229 only for special-purpose buffers.) The users will find Emacs more
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
230 coherent if all libraries use the same conventions.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
231
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
232 @item
71307
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
233 If your program contains non-ASCII characters in string or character
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
234 constants, you should make sure Emacs always decodes these characters
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
235 the same way, regardless of the user's settings. There are two ways
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
236 to do that:
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
237
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
238 @itemize -
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
239 @item
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
240 Use coding system @code{emacs-mule}, and specify that for
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
241 @code{coding} in the @samp{-*-} line or the local variables list.
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
242
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
243 @example
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
244 ;; XXX.el -*- coding: emacs-mule; -*-
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
245 @end example
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
246
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
247 @item
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
248 Use one of the coding systems based on ISO 2022 (such as
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
249 iso-8859-@var{n} and iso-2022-7bit), and specify it with @samp{!} at
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
250 the end for @code{coding}. (The @samp{!} turns off any possible
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
251 character translation.)
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
252
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
253 @example
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
254 ;; XXX.el -*- coding: iso-latin-2!; -*-
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
255 @end example
71314
0ebac95569f4 (Coding Conventions): Add `@end itemize'.
Luc Teirlinck <teirllm@auburn.edu>
parents: 71307
diff changeset
256 @end itemize
71307
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
257
b4f82229f064 (Coding Conventions): Explain use of coding systems
Richard M. Stallman <rms@gnu.org>
parents: 71036
diff changeset
258 @item
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
259 Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
260 default indentation parameters.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
261
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
262 @item
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
263 Don't make a habit of putting close-parentheses on lines by themselves;
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
264 Lisp programmers find this disconcerting. Once in a while, when there
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
265 is a sequence of many consecutive close-parentheses, it may make sense
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
266 to split the sequence in one or two significant places.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
267
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
268 @item
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
269 Please put a copyright notice and copying permission notice on the
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
270 file if you distribute copies. Use a notice like this one:
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
271
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
272 @smallexample
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
273 ;; Copyright (C) @var{year} @var{name}
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
274
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
275 ;; This program is free software; you can redistribute it and/or
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
276 ;; modify it under the terms of the GNU General Public License as
78325
665e86db2a21 Update example license to use GPLv3.
Glenn Morris <rgm@gnu.org>
parents: 77642
diff changeset
277 ;; published by the Free Software Foundation; either version 3 of
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
278 ;; the License, or (at your option) any later version.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
279
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
280 ;; This program is distributed in the hope that it will be
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
281 ;; useful, but WITHOUT ANY WARRANTY; without even the implied
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
282 ;; warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
283 ;; PURPOSE. See the GNU General Public License for more details.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
284
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
285 ;; You should have received a copy of the GNU General Public
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
286 ;; License along with this program; if not, write to the Free
71638
3184a667d8db fix overfull/underfull boxes
Karl Berry <karl@gnu.org>
parents: 71375
diff changeset
287 ;; Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
3184a667d8db fix overfull/underfull boxes
Karl Berry <karl@gnu.org>
parents: 71375
diff changeset
288 ;; Boston, MA 02110-1301 USA
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
289 @end smallexample
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
290
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
291 If you have signed papers to assign the copyright to the Foundation,
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
292 then use @samp{Free Software Foundation, Inc.} as @var{name}.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
293 Otherwise, use your name. See also @xref{Library Headers}.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
294 @end itemize
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
295
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
296 @node Key Binding Conventions
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
297 @section Key Binding Conventions
76841
fc9d442f98d2 Improve indexing.
Eli Zaretskii <eliz@gnu.org>
parents: 75477
diff changeset
298 @cindex key binding, conventions for
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
299
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
300 @itemize @bullet
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
301 @item
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
302 @cindex mouse-2
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
303 @cindex references, following
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
304 Special major modes used for read-only text should usually redefine
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
305 @kbd{mouse-2} and @key{RET} to trace some sort of reference in the text.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
306 Modes such as Dired, Info, Compilation, and Occur redefine it in this
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
307 way.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
308
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
309 In addition, they should mark the text as a kind of ``link'' so that
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
310 @kbd{mouse-1} will follow it also. @xref{Links and Mouse-1}.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
311
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
312 @item
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
313 @cindex reserved keys
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
314 @cindex keys, reserved
60273
a0cca815ceaa (Coding Conventions): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 58323
diff changeset
315 Please do not define @kbd{C-c @var{letter}} as a key in Lisp programs.
a0cca815ceaa (Coding Conventions): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 58323
diff changeset
316 Sequences consisting of @kbd{C-c} and a letter (either upper or lower
a0cca815ceaa (Coding Conventions): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 58323
diff changeset
317 case) are reserved for users; they are the @strong{only} sequences
a0cca815ceaa (Coding Conventions): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 58323
diff changeset
318 reserved for users, so do not block them.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319
44733
d49f5ed1a977 Clarify which letters in C-c LETTER are reserved for users.
Richard M. Stallman <rms@gnu.org>
parents: 44654
diff changeset
320 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
321 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
322 waste, and inconvenience users. Please comply with it.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323
44733
d49f5ed1a977 Clarify which letters in C-c LETTER are reserved for users.
Richard M. Stallman <rms@gnu.org>
parents: 44654
diff changeset
324 @item
60273
a0cca815ceaa (Coding Conventions): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 58323
diff changeset
325 Function keys @key{F5} through @key{F9} without modifier keys are
a0cca815ceaa (Coding Conventions): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 58323
diff changeset
326 also reserved for users to define.
a0cca815ceaa (Coding Conventions): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 58323
diff changeset
327
a0cca815ceaa (Coding Conventions): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 58323
diff changeset
328 @item
a0cca815ceaa (Coding Conventions): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 58323
diff changeset
329 Applications should not bind mouse events based on button 1 with the
a0cca815ceaa (Coding Conventions): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 58323
diff changeset
330 shift key held down. These events include @kbd{S-mouse-1},
a0cca815ceaa (Coding Conventions): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 58323
diff changeset
331 @kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on. They are reserved for
a0cca815ceaa (Coding Conventions): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 58323
diff changeset
332 users.
a0cca815ceaa (Coding Conventions): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 58323
diff changeset
333
a0cca815ceaa (Coding Conventions): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 58323
diff changeset
334 @item
44733
d49f5ed1a977 Clarify which letters in C-c LETTER are reserved for users.
Richard M. Stallman <rms@gnu.org>
parents: 44654
diff changeset
335 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
336 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
337
e09e51d7c35a Describe uses of C-c followed by punctuation chars.
Richard M. Stallman <rms@gnu.org>
parents: 10229
diff changeset
338 @item
e09e51d7c35a Describe uses of C-c followed by punctuation chars.
Richard M. Stallman <rms@gnu.org>
parents: 10229
diff changeset
339 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
340 @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
341
e09e51d7c35a Describe uses of C-c followed by punctuation chars.
Richard M. Stallman <rms@gnu.org>
parents: 10229
diff changeset
342 @item
e09e51d7c35a Describe uses of C-c followed by punctuation chars.
Richard M. Stallman <rms@gnu.org>
parents: 10229
diff changeset
343 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
344 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
345 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
346 may be shadowed from time to time by minor modes.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 @item
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
349 Do not bind @kbd{C-h} following any prefix character (including
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 @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
351 as a help character for listing the subcommands of the prefix character.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353 @item
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
354 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
355 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
356 @kbd{@key{ESC} @key{ESC}}.)
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 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
359 any context prevents recognition of escape sequences as function keys in
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 that context.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362 @item
22635
1e9786a5c63d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
363 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
364 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
365 @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
366
1e9786a5c63d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
367 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
368 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
369 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
370 @key{ESC}}, since that would preclude recognizing an escape sequence
1e9786a5c63d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
371 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
372 @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
373 @kbd{@key{ESC} @key{ESC}} instead.
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
374 @end itemize
60273
a0cca815ceaa (Coding Conventions): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 58323
diff changeset
375
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
376 @node Programming Tips
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
377 @section Emacs Programming Tips
76841
fc9d442f98d2 Improve indexing.
Eli Zaretskii <eliz@gnu.org>
parents: 75477
diff changeset
378 @cindex programming conventions
34305
0c60b76ea2ee Why no package system.
Dave Love <fx@gnu.org>
parents: 30904
diff changeset
379
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
380 Following these conventions will make your program fit better
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
381 into Emacs when it runs.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
383 @itemize @bullet
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
384 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385 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
386 always, @code{forward-line} is more convenient as well as more
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387 predictable and robust. @xref{Text Lines}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 @item
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6959
diff changeset
390 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
391 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
392 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
393 for the user's benefit. @xref{The Mark}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
395 In particular, don't use any of these functions:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 @itemize @bullet
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 @code{beginning-of-buffer}, @code{end-of-buffer}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 @code{replace-string}, @code{replace-regexp}
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
402 @item
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
403 @code{insert-file}, @code{insert-buffer}
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404 @end itemize
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
406 If you just want to move point, or replace a certain string, or insert
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
407 a file or buffer's contents, without any of the other features
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
408 intended for interactive users, you can replace these functions with
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
409 one or two lines of simple Lisp code.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 @item
8669
62d1138d10de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7601
diff changeset
412 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
413 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
414 for vectors, and working with lists is usually more convenient.
62d1138d10de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7601
diff changeset
415
62d1138d10de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7601
diff changeset
416 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
417 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
418 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
419
62d1138d10de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7601
diff changeset
420 @item
64846
c73bec99da0b (Coding Conventions): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 64091
diff changeset
421 The recommended way to show a message in the echo area is with
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 the @code{message} function, not @code{princ}. @xref{The Echo Area}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 When you encounter an error condition, call the function @code{error}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426 (or @code{signal}). The function @code{error} does not return.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 @xref{Signaling Errors}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429 Do not use @code{message}, @code{throw}, @code{sleep-for},
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430 or @code{beep} to report errors.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432 @item
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
433 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
434 with a period.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
435
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
436 @item
65332
c2fb39cb93f0 (Programming Tips): Add conventions for minibuffer questions and prompts.
Richard M. Stallman <rms@gnu.org>
parents: 64916
diff changeset
437 A question asked in the minibuffer with @code{y-or-n-p} or
c2fb39cb93f0 (Programming Tips): Add conventions for minibuffer questions and prompts.
Richard M. Stallman <rms@gnu.org>
parents: 64916
diff changeset
438 @code{yes-or-no-p} should start with a capital letter and end with
c2fb39cb93f0 (Programming Tips): Add conventions for minibuffer questions and prompts.
Richard M. Stallman <rms@gnu.org>
parents: 64916
diff changeset
439 @samp{? }.
c2fb39cb93f0 (Programming Tips): Add conventions for minibuffer questions and prompts.
Richard M. Stallman <rms@gnu.org>
parents: 64916
diff changeset
440
c2fb39cb93f0 (Programming Tips): Add conventions for minibuffer questions and prompts.
Richard M. Stallman <rms@gnu.org>
parents: 64916
diff changeset
441 @item
c2fb39cb93f0 (Programming Tips): Add conventions for minibuffer questions and prompts.
Richard M. Stallman <rms@gnu.org>
parents: 64916
diff changeset
442 When you mention a default value in a minibuffer prompt,
c2fb39cb93f0 (Programming Tips): Add conventions for minibuffer questions and prompts.
Richard M. Stallman <rms@gnu.org>
parents: 64916
diff changeset
443 put it and the word @samp{default} inside parentheses.
c2fb39cb93f0 (Programming Tips): Add conventions for minibuffer questions and prompts.
Richard M. Stallman <rms@gnu.org>
parents: 64916
diff changeset
444 It should look like this:
c2fb39cb93f0 (Programming Tips): Add conventions for minibuffer questions and prompts.
Richard M. Stallman <rms@gnu.org>
parents: 64916
diff changeset
445
c2fb39cb93f0 (Programming Tips): Add conventions for minibuffer questions and prompts.
Richard M. Stallman <rms@gnu.org>
parents: 64916
diff changeset
446 @example
65386
95aa6fb80959 (Programming Tips): Correct the "default" prompt spec.
Richard M. Stallman <rms@gnu.org>
parents: 65344
diff changeset
447 Enter the answer (default 42):
65332
c2fb39cb93f0 (Programming Tips): Add conventions for minibuffer questions and prompts.
Richard M. Stallman <rms@gnu.org>
parents: 64916
diff changeset
448 @end example
c2fb39cb93f0 (Programming Tips): Add conventions for minibuffer questions and prompts.
Richard M. Stallman <rms@gnu.org>
parents: 64916
diff changeset
449
c2fb39cb93f0 (Programming Tips): Add conventions for minibuffer questions and prompts.
Richard M. Stallman <rms@gnu.org>
parents: 64916
diff changeset
450 @item
38043
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
451 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
452 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
453 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
454 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
455 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
456 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
457
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
458 @example
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
459 (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
460 (interactive
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
461 (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
462 (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
463 ...)
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
464 @end example
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
465
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
466 @noindent
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
467 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
468
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
469 @example
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
470 (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
471 (interactive
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
472 (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
473 @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
474 ...)
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
475 @end example
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
476
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
477 @noindent
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
478 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
479 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
480
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
481 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
482 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
483 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
484 command.
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
485
3577e0c41a1e Give advice about how to default position args and region args.
Richard M. Stallman <rms@gnu.org>
parents: 34305
diff changeset
486 @item
13893
2576d1142ed3 Explain style of "done" messages.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
487 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
488 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
489 @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
490 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
491 @emph{no} period after @samp{done}.
13893
2576d1142ed3 Explain style of "done" messages.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
492
2576d1142ed3 Explain style of "done" messages.
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
493 @item
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
494 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
495 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
496 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
497 @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
498 user switch back at will. @xref{Recursive Editing}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499 @end itemize
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
501 @node Compilation Tips
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
502 @section Tips for Making Compiled Code Fast
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
503 @cindex execution speed
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
504 @cindex speedups
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
506 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
507 Lisp programs.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
508
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
509 @itemize @bullet
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
510 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
511 @cindex profiling
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512 @cindex timing programs
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
513 @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
514 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
515 @file{elp.el} for instructions.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
516
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517 @item
61056
0b041af08b4a (Compilation Tips): Mention benchmark.el.
Richard M. Stallman <rms@gnu.org>
parents: 60273
diff changeset
518 @cindex @file{benchmark.el}
0b041af08b4a (Compilation Tips): Mention benchmark.el.
Richard M. Stallman <rms@gnu.org>
parents: 60273
diff changeset
519 @cindex benchmarking
0b041af08b4a (Compilation Tips): Mention benchmark.el.
Richard M. Stallman <rms@gnu.org>
parents: 60273
diff changeset
520 Check the speed of individual Emacs Lisp forms using the
0b041af08b4a (Compilation Tips): Mention benchmark.el.
Richard M. Stallman <rms@gnu.org>
parents: 60273
diff changeset
521 @file{benchmark} library. See the functions @code{benchmark-run} and
0b041af08b4a (Compilation Tips): Mention benchmark.el.
Richard M. Stallman <rms@gnu.org>
parents: 60273
diff changeset
522 @code{benchmark-run-compiled} in @file{benchmark.el}.
0b041af08b4a (Compilation Tips): Mention benchmark.el.
Richard M. Stallman <rms@gnu.org>
parents: 60273
diff changeset
523
0b041af08b4a (Compilation Tips): Mention benchmark.el.
Richard M. Stallman <rms@gnu.org>
parents: 60273
diff changeset
524 @item
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 Use iteration rather than recursion whenever possible.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 Function calls are slow in Emacs Lisp even when a compiled function
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 is calling another compiled function.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
528
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529 @item
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
530 Using the primitive list-searching functions @code{memq}, @code{member},
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11648
diff changeset
531 @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
532 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
533 search functions can be used.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 @item
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 44733
diff changeset
536 Certain built-in functions are handled specially in byte-compiled code,
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537 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
538 use these functions rather than alternatives. To see whether a function
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 is handled specially by the compiler, examine its @code{byte-compile}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540 property. If the property is non-@code{nil}, then the function is
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 handled specially.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543 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
544 compiled specially (@pxref{Array Functions}):
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
546 @example
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 (get 'aref 'byte-compile)
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 @result{} byte-compile-two-args
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550 @end group
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
551 @end example
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553 @item
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
554 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
555 program's running time, make the function inline. This eliminates
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556 the function call overhead. Since making a function inline reduces
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557 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
558 a noticeable speedup in something slow enough that users care about
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559 the speed. @xref{Inline Functions}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 @end itemize
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
562 @node Warning Tips
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
563 @section Tips for Avoiding Compiler Warnings
76841
fc9d442f98d2 Improve indexing.
Eli Zaretskii <eliz@gnu.org>
parents: 75477
diff changeset
564 @cindex byte compiler warnings, how to avoid
64916
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
565
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
566 @itemize @bullet
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
567 @item
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
568 Try to avoid compiler warnings about undefined free variables, by adding
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
569 dummy @code{defvar} definitions for these variables, like this:
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
570
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
571 @example
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
572 (defvar foo)
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
573 @end example
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
574
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
575 Such a definition has no effect except to tell the compiler
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
576 not to warn about uses of the variable @code{foo} in this file.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
577
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
578 @item
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
579 If you use many functions and variables from a certain file, you can
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
580 add a @code{require} for that package to avoid compilation warnings
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
581 for them. For instance,
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
582
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
583 @example
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
584 (eval-when-compile
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
585 (require 'foo))
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
586 @end example
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
587
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
588 @item
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
589 If you bind a variable in one function, and use it or set it in
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
590 another function, the compiler warns about the latter function unless
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
591 the variable has a definition. But adding a definition would be
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
592 unclean if the variable has a short name, since Lisp packages should
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
593 not define short variable names. The right thing to do is to rename
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
594 this variable to start with the name prefix used for the other
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
595 functions and variables in your package.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
596
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
597 @item
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
598 The last resort for avoiding a warning, when you want to do something
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
599 that usually is a mistake but it's not a mistake in this one case,
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
600 is to put a call to @code{with-no-warnings} around it.
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
601 @end itemize
d16e2016fc7d (Key Binding Conventions, Programming Tips, Warning Tips):
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
602
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
603 @node Documentation Tips
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
604 @section Tips for Documentation Strings
76841
fc9d442f98d2 Improve indexing.
Eli Zaretskii <eliz@gnu.org>
parents: 75477
diff changeset
605 @cindex documentation strings, conventions and tips
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
607 @findex checkdoc-minor-mode
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
608 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
609 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
610 @kbd{M-x checkdoc-minor-mode}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612 @itemize @bullet
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613 @item
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6959
diff changeset
614 Every command, function, or variable intended for users to know about
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615 should have a documentation string.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
616
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
617 @item
10225
2e5dcd5f3090 Recommend doc strings for all functions and variables.
Richard M. Stallman <rms@gnu.org>
parents: 9807
diff changeset
618 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
619 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
620 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
621 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
622 a running Emacs.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
623
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624 @item
42979
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
625 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
626 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
627 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
628 or it will look bad in the output of @code{apropos}.
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
629
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
630 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
631 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
632 readable by choosing certain line breaks with care. Use blank lines
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
633 between topics if the documentation string is long.
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
634
7359d6d75a9c Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 40970
diff changeset
635 @item
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636 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
637 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
638 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
639 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
640 first line with a capital letter and end with a period.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641
40970
fb31125d0d7b Say what questions first line of doc string should answer.
Richard M. Stallman <rms@gnu.org>
parents: 40561
diff changeset
642 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
643 ``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
644 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
645
fb31125d0d7b Say what questions first line of doc string should answer.
Richard M. Stallman <rms@gnu.org>
parents: 40561
diff changeset
646 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
647 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
648 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
649
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650 @item
77642
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
651 When the user tries to use a disabled command, Emacs displays just the
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
652 first paragraph of its documentation string---everything through the
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
653 first blank line. If you wish, you can choose which information to
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
654 include before the first blank line so as to make this display useful.
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
655
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
656 @item
49960
10a8aba3dfc7 First line of function doc string should mention the most important
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
657 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
658 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
659 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
660 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
661 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
662 important arguments.
10a8aba3dfc7 First line of function doc string should mention the most important
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
663
10a8aba3dfc7 First line of function doc string should mention the most important
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
664 @item
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
665 When a function's documentation string mentions the value of an argument
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
666 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
667 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
668 @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
669 actual argument name is @code{form}:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
671 @example
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
672 Evaluate FORM and return its value.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
673 @end example
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
674
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
675 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
676 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
677 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
678 illustrate this practice:
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
679
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
680 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
681 The argument TABLE should be an alist whose elements
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
682 have the form (KEY . VALUE). Here, KEY is ...
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
683 @end example
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
684
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685 @item
40517
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
686 Never change the case of a Lisp symbol when you mention it in a doc
71957
61cb5aae3bc3 Put period and comma inside quotes.
Richard M. Stallman <rms@gnu.org>
parents: 71855
diff changeset
687 string. If the symbol's name is @code{foo}, write ``foo,'' not
40517
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
688 ``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
689
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
690 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
691 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
692 @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
693 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
694
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
695 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
696 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
697 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
698
37a08b5afded Document textual convention for doc strings of predicates.
Richard M. Stallman <rms@gnu.org>
parents: 38344
diff changeset
699 @item
77642
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
700 Do not start or end a documentation string with whitespace.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
701
77642
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
702 @item
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
703 @strong{Do not} indent subsequent lines of a documentation string so
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
704 that the text is lined up in the source code with the text of the first
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
705 line. This looks nice in the source code, but looks bizarre when users
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
706 view the documentation. Remember that the indentation before the
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
707 starting double-quote is not part of the string!
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
708
53300
2cabf526af0e (Documentation Tips): Add anchor.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52912
diff changeset
709 @anchor{Docstring hyperlinks}
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
710 @item
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
711 @iftex
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
712 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
713 would be printed (which usually means in lower case), with single-quotes
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
714 around it. For example: @samp{`lambda'}. There are two exceptions:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
715 write @code{t} and @code{nil} without single-quotes.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
716 @end iftex
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
717 @ifnottex
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
718 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
719 would be printed (which usually means in lower case), with single-quotes
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720 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
721 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
722 convention, with single-quotes for all symbols.)
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
723 @end ifnottex
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
724
77642
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
725 @cindex hyperlinks in documentation strings
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
726 Help mode automatically creates a hyperlink when a documentation string
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
727 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
728 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
729 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
730 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
731 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
732 @samp{variable}, @samp{option}, @samp{function}, or @samp{command},
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
733 immediately before the symbol name. (Case makes no difference in
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
734 recognizing these indicator words.) For example, if you write
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
735
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
736 @example
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
737 This function sets the variable `buffer-file-name'.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
738 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
739
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
740 @noindent
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
741 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
742 @code{buffer-file-name}, and not to its function documentation.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
743
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
744 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
745 those are irrelevant to the use of the symbol that you are documenting,
69590
d9fdd137cff0 (Documentation Tips): One can now also write `program' in front of a
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
746 you can write the words @samp{symbol} or @samp{program} before the
d9fdd137cff0 (Documentation Tips): One can now also write `program' in front of a
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
747 symbol name to prevent making any hyperlink. For example,
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
748
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
749 @example
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
750 If the argument KIND-OF-RESULT is the symbol `list',
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
751 this function returns a list of all the objects
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
752 that satisfy the criterion.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
753 @end example
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
754
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
755 @noindent
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
756 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
757 function @code{list}.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
758
52912
2fdb8b16bceb (Documentation Tips): Document new behavior for face and variable
Luc Teirlinck <teirllm@auburn.edu>
parents: 52845
diff changeset
759 Normally, no hyperlink is made for a variable without variable
2fdb8b16bceb (Documentation Tips): Document new behavior for face and variable
Luc Teirlinck <teirllm@auburn.edu>
parents: 52845
diff changeset
760 documentation. You can force a hyperlink for such variables by
2fdb8b16bceb (Documentation Tips): Document new behavior for face and variable
Luc Teirlinck <teirllm@auburn.edu>
parents: 52845
diff changeset
761 preceding them with one of the words @samp{variable} or
2fdb8b16bceb (Documentation Tips): Document new behavior for face and variable
Luc Teirlinck <teirllm@auburn.edu>
parents: 52845
diff changeset
762 @samp{option}.
2fdb8b16bceb (Documentation Tips): Document new behavior for face and variable
Luc Teirlinck <teirllm@auburn.edu>
parents: 52845
diff changeset
763
2fdb8b16bceb (Documentation Tips): Document new behavior for face and variable
Luc Teirlinck <teirllm@auburn.edu>
parents: 52845
diff changeset
764 Hyperlinks for faces are only made if the face name is preceded or
2fdb8b16bceb (Documentation Tips): Document new behavior for face and variable
Luc Teirlinck <teirllm@auburn.edu>
parents: 52845
diff changeset
765 followed by the word @samp{face}. In that case, only the face
2fdb8b16bceb (Documentation Tips): Document new behavior for face and variable
Luc Teirlinck <teirllm@auburn.edu>
parents: 52845
diff changeset
766 documentation will be shown, even if the symbol is also defined as a
2fdb8b16bceb (Documentation Tips): Document new behavior for face and variable
Luc Teirlinck <teirllm@auburn.edu>
parents: 52845
diff changeset
767 variable or as a function.
2fdb8b16bceb (Documentation Tips): Document new behavior for face and variable
Luc Teirlinck <teirllm@auburn.edu>
parents: 52845
diff changeset
768
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
769 To make a hyperlink to Info documentation, write the name of the Info
53457
3bd5e3d6a230 (Documentation Tips): Update item on hyperlinks in documentation strings.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53300
diff changeset
770 node (or anchor) in single quotes, preceded by @samp{info node},
3bd5e3d6a230 (Documentation Tips): Update item on hyperlinks in documentation strings.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53300
diff changeset
771 @samp{Info node}, @samp{info anchor} or @samp{Info anchor}. The Info
3bd5e3d6a230 (Documentation Tips): Update item on hyperlinks in documentation strings.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53300
diff changeset
772 file name defaults to @samp{emacs}. For example,
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
773
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
774 @smallexample
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
775 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
776 @end smallexample
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
777
66516
62934d7c890f (Documentation Tips): Help mode now creates hyperlinks for URLs.
Bill Wohler <wohler@newt.com>
parents: 65386
diff changeset
778 Finally, to create a hyperlink to URLs, write the URL in single
62934d7c890f (Documentation Tips): Help mode now creates hyperlinks for URLs.
Bill Wohler <wohler@newt.com>
parents: 65386
diff changeset
779 quotes, preceded by @samp{URL}. For example,
62934d7c890f (Documentation Tips): Help mode now creates hyperlinks for URLs.
Bill Wohler <wohler@newt.com>
parents: 65386
diff changeset
780
62934d7c890f (Documentation Tips): Help mode now creates hyperlinks for URLs.
Bill Wohler <wohler@newt.com>
parents: 65386
diff changeset
781 @smallexample
62934d7c890f (Documentation Tips): Help mode now creates hyperlinks for URLs.
Bill Wohler <wohler@newt.com>
parents: 65386
diff changeset
782 The home page for the GNU project has more information (see URL
62934d7c890f (Documentation Tips): Help mode now creates hyperlinks for URLs.
Bill Wohler <wohler@newt.com>
parents: 65386
diff changeset
783 `http://www.gnu.org/').
62934d7c890f (Documentation Tips): Help mode now creates hyperlinks for URLs.
Bill Wohler <wohler@newt.com>
parents: 65386
diff changeset
784 @end smallexample
62934d7c890f (Documentation Tips): Help mode now creates hyperlinks for URLs.
Bill Wohler <wohler@newt.com>
parents: 65386
diff changeset
785
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
786 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
787 Don't write key sequences directly in documentation strings. Instead,
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
788 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
789 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
790 @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
791 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
792 (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
793 user has moved key bindings.) @xref{Keys in Documentation}.
6552
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 @item
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796 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
797 key bindings of that mode's local map, rather than global ones.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
798 Therefore, use the construct @samp{\\<@dots{}>} once in the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
799 documentation string to specify which key map to use. Do this before
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
800 the first use of @samp{\\[@dots{}]}. The text inside the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801 @samp{\\<@dots{}>} should be the name of the variable containing the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
802 local keymap for the major mode.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
803
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
804 It is not practical to use @samp{\\[@dots{}]} very many times, because
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
805 display of the documentation string will become slow. So use this to
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
806 describe the most important commands in your major mode, and then use
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
807 @samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
77642
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
808
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
809 @item
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
810 For consistency, phrase the verb in the first sentence of a function's
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
811 documentation string as an imperative---for instance, use ``Return the
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
812 cons of A and B.'' in preference to ``Returns the cons of A and B@.''
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
813 Usually it looks good to do likewise for the rest of the first
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
814 paragraph. Subsequent paragraphs usually look better if each sentence
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
815 is indicative and has a proper subject.
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
816
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
817 @item
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
818 The documentation string for a function that is a yes-or-no predicate
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
819 should start with words such as ``Return t if,'' to indicate
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
820 explicitly what constitutes ``truth.'' The word ``return'' avoids
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
821 starting the sentence with lower-case ``t,'' which could be somewhat
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
822 distracting.
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
823
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
824 @item
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
825 If a line in a documentation string begins with an open-parenthesis,
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
826 write a backslash before the open-parenthesis, like this:
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
827
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
828 @example
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
829 The argument FOO can be either a number
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
830 \(a buffer position) or a string (a file name).
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
831 @end example
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
832
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
833 This prevents the open-parenthesis from being treated as the start of a
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
834 defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
835
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
836 @item
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
837 Write documentation strings in the active voice, not the passive, and in
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
838 the present tense, not the future. For instance, use ``Return a list
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
839 containing A and B.'' instead of ``A list containing A and B will be
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
840 returned.''
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
841
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
842 @item
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
843 Avoid using the word ``cause'' (or its equivalents) unnecessarily.
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
844 Instead of, ``Cause Emacs to display text in boldface,'' write just
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
845 ``Display text in boldface.''
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
846
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
847 @item
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
848 When a command is meaningful only in a certain mode or situation,
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
849 do mention that in the documentation string. For example,
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
850 the documentation of @code{dired-find-file} is:
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
851
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
852 @example
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
853 In Dired, visit the file or directory named on this line.
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
854 @end example
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
855
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
856 @item
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
857 When you define a variable that users ought to set interactively, you
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
858 normally should use @code{defcustom}. However, if for some reason you
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
859 use @code{defvar} instead, start the doc string with a @samp{*}.
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
860 @xref{Defining Variables}.
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
861
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
862 @item
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
863 The documentation string for a variable that is a yes-or-no flag should
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
864 start with words such as ``Non-nil means,'' to make it clear that
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
865 all non-@code{nil} values are equivalent and indicate explicitly what
63ebf0b1cf38 (Documentation Tips): Rearrange items to place the more important ones first.
Eli Zaretskii <eliz@gnu.org>
parents: 76993
diff changeset
866 @code{nil} and non-@code{nil} mean.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
867 @end itemize
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
868
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
869 @node Comment Tips
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
870 @section Tips on Writing Comments
76993
55c9ef5f1559 Improve index entries.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
871 @cindex comments, Lisp convention for
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
872
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
873 We recommend these conventions for where to put comments and how to
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
874 indent them:
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 @table @samp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
877 @item ;
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
878 Comments that start with a single semicolon, @samp{;}, should all be
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
879 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
880 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
881 Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment})
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
882 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
883 aligns such a comment if it is already present.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
884
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6959
diff changeset
885 This and following examples are taken from the Emacs sources.
6552
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 @smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
888 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
889 (setq base-version-list ; there was a base
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
890 (assoc (substring fn 0 start-vn) ; version to which
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
891 file-version-assoc-list)) ; this looks like
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
892 ; a subversion
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
893 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
894 @end smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
895
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
896 @item ;;
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
897 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
898 the same level of indentation as the code. Such comments usually
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
899 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
900 at that point. For example:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
901
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
902 @smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
903 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
904 (prog1 (setq auto-fill-function
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
905 @dots{}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
906 @dots{}
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
907 ;; update mode line
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
908 (force-mode-line-update)))
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
909 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
910 @end smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
911
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
912 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
913
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
914 @smallexample
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
915 @group
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
916 ;; This Lisp code is run in Emacs
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
917 ;; when it is to operate as a server
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
918 ;; for other processes.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
919 @end group
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
920 @end smallexample
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 26211
diff changeset
921
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
922 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
923 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
924 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
925 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
926 each argument means and how the function interprets its possible values.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
927
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
928 @item ;;;
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
929 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
930 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
931 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
932 for comments that are between functions---whether to use two or three
53924
ed40e77a5176 (Comment Tips): Document the new conventions for commenting out code.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53457
diff changeset
933 semicolons depends on whether the comment should be considered a
ed40e77a5176 (Comment Tips): Document the new conventions for commenting out code.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53457
diff changeset
934 ``heading'' by Outline minor mode. By default, comments starting with
ed40e77a5176 (Comment Tips): Document the new conventions for commenting out code.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53457
diff changeset
935 at least three semicolons (followed by a single space and a
ed40e77a5176 (Comment Tips): Document the new conventions for commenting out code.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53457
diff changeset
936 non-whitespace character) are considered headings, comments starting
ed40e77a5176 (Comment Tips): Document the new conventions for commenting out code.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53457
diff changeset
937 with two or less are not.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
938
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6959
diff changeset
939 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
940 within a function. We use three semicolons for this precisely so that
53924
ed40e77a5176 (Comment Tips): Document the new conventions for commenting out code.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53457
diff changeset
941 they remain at the left margin. By default, Outline minor mode does
ed40e77a5176 (Comment Tips): Document the new conventions for commenting out code.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53457
diff changeset
942 not consider a comment to be a heading (even if it starts with at
ed40e77a5176 (Comment Tips): Document the new conventions for commenting out code.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53457
diff changeset
943 least three semicolons) if the semicolons are followed by at least two
ed40e77a5176 (Comment Tips): Document the new conventions for commenting out code.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53457
diff changeset
944 spaces. Thus, if you add an introductory comment to the commented out
ed40e77a5176 (Comment Tips): Document the new conventions for commenting out code.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53457
diff changeset
945 code, make sure to indent it by at least two spaces after the three
ed40e77a5176 (Comment Tips): Document the new conventions for commenting out code.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53457
diff changeset
946 semicolons.
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
947
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
948 @smallexample
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
949 (defun foo (a)
53924
ed40e77a5176 (Comment Tips): Document the new conventions for commenting out code.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53457
diff changeset
950 ;;; This is no longer necessary.
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
951 ;;; (force-mode-line-update)
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
952 (message "Finished with %s" a))
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
953 @end smallexample
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
954
53924
ed40e77a5176 (Comment Tips): Document the new conventions for commenting out code.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53457
diff changeset
955 When commenting out entire functions, use two semicolons.
ed40e77a5176 (Comment Tips): Document the new conventions for commenting out code.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53457
diff changeset
956
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
957 @item ;;;;
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
958 Comments that start with four semicolons, @samp{;;;;}, should be aligned
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
959 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
960 program. For example:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
961
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
962 @smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
963 ;;;; The kill ring
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
964 @end smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
965 @end table
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
966
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
967 @noindent
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
968 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
969 (@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}),
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
970 automatically indent comments according to these conventions,
7601
c5927c75b2b5 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6959
diff changeset
971 depending on the number of semicolons. @xref{Comments,,
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
972 Manipulating Comments, emacs, The GNU Emacs Manual}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
973
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
974 @node Library Headers
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
975 @section Conventional Headers for Emacs Libraries
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
976 @cindex header comments
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
977 @cindex library header comments
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
978
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 19361
diff changeset
979 Emacs has conventions for using special comments in Lisp libraries
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
980 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
981 them. This section explains these conventions.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
982
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
983 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
984 distribution.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
985
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
986 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
987 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
988 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
989 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
990 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
991 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
992 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
993 if we haven't installed it in Emacs yet!
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
994
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24862
diff changeset
995 With that warning out of the way, on to the example:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
996
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
997 @smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
998 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
999 ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1000
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1001 ;; Copyright (C) 1992 Free Software Foundation, Inc.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1002 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1003
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1004 ;; Author: Eric S. Raymond <esr@@snark.thyrsus.com>
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1005 ;; Maintainer: Eric S. Raymond <esr@@snark.thyrsus.com>
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1006 ;; Created: 14 Jul 1992
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1007 ;; Version: 1.2
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1008 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1009 ;; Keywords: docs
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1010
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1011 ;; This file is part of GNU Emacs.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1012 @dots{}
64091
6fb026ad601f Update FSF's address.
Lute Kamstra <lute@gnu.org>
parents: 64083
diff changeset
1013 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
6fb026ad601f Update FSF's address.
Lute Kamstra <lute@gnu.org>
parents: 64083
diff changeset
1014 ;; Boston, MA 02110-1301, USA.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1015 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1016 @end smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1017
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1018 The very first line should have this format:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1019
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1020 @example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1021 ;;; @var{filename} --- @var{description}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1022 @end example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1023
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1024 @noindent
52149
9928a29a3e80 (Library Headers): Explain where to put -*-.
Richard M. Stallman <rms@gnu.org>
parents: 49960
diff changeset
1025 The description should be complete in one line. If the file
9928a29a3e80 (Library Headers): Explain where to put -*-.
Richard M. Stallman <rms@gnu.org>
parents: 49960
diff changeset
1026 needs a @samp{-*-} specification, put it after @var{description}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1027
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1028 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
1029 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
1030 the conventional possibilities for @var{header-name}:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1031
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1032 @table @samp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1033 @item Author
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1034 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
1035 author of the library.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1036
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1037 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
1038 led by @code{;;} and a tab character, like this:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1039
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1040 @smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1041 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1042 ;; Author: Ashwin Ram <Ram-Ashwin@@cs.yale.edu>
6959
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
1043 ;; Dave Sill <de5@@ornl.gov>
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
1044 ;; Dave Brennan <brennan@@hal.com>
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
1045 ;; Eric Raymond <esr@@snark.thyrsus.com>
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1046 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1047 @end smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1048
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1049 @item Maintainer
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1050 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
1051 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
1052 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
1053 maintainers. The example above is mildly bogus because the maintainer
3b19456b877a *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6552
diff changeset
1054 line is redundant.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1055
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1056 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
1057 possible a Lisp function to ``send mail to the maintainer'' without
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1058 having to mine the name out by hand.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1059
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1060 Be sure to surround the network address with @samp{<@dots{}>} if
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061 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
1062
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1063 @item Created
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1064 This optional line gives the original creation date of the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1065 file. For historical interest only.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1066
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1067 @item Version
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1068 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
1069 them in this line.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1070
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1071 @item Adapted-By
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1072 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
1073 library for installation (to make it fit the style conventions, for
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1074 example).
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1075
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1076 @item Keywords
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1077 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
1078 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
1079
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1080 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
1081 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
1082 can use spaces, commas, or both.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1083 @end table
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1084
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1085 Just about every Lisp library ought to have the @samp{Author} and
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1086 @samp{Keywords} header comment lines. Use the others if they are
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1087 appropriate. You can also put in header lines with other header
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1088 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
1089
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1090 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
1091 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
1092 else. Here is a table of them:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1093
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1094 @table @samp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1095 @item ;;; Commentary:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1096 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
1097 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
1098 @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
1099 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
1100 context.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1101
52814
df5527dde8fb (Library Headers): Fix typo.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52808
diff changeset
1102 @item ;;; Documentation:
52845
1826a112381b (Library Headers): Clean up Documentation.
Richard M. Stallman <rms@gnu.org>
parents: 52814
diff changeset
1103 This was used in some files in place of @samp{;;; Commentary:},
1826a112381b (Library Headers): Clean up Documentation.
Richard M. Stallman <rms@gnu.org>
parents: 52814
diff changeset
1104 but it is deprecated.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1105
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1106 @item ;;; Change Log:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1107 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
1108 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
1109 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
1110 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
1111 Log:} line. @samp{History} is an alternative to @samp{Change Log}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1112
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1113 @item ;;; Code:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1114 This begins the actual code of the program.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1115
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1116 @item ;;; @var{filename} ends here
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1117 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
1118 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
1119 from the lack of a footer line.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1120 @end table
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52149
diff changeset
1121
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52149
diff changeset
1122 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52149
diff changeset
1123 arch-tag: 9ea911c2-6b1d-47dd-88b7-0a94e8b27c2e
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52149
diff changeset
1124 @end ignore