@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/tips
@node Tips, GNU Emacs Internals, System Interface, Top
@c @appendix Tips and Conventions
@appendix $B%R%s%H$H47=,(B
@c @cindex tips
@c @cindex standards of coding style
@c @cindex coding standards
@cindex $B%R%s%H(B
@cindex $B%3!<%G%#%s%0%9%?%$%k$NI8=`(B
@cindex $B%3!<%G%#%s%0%9%?%$%k(B

@c   This chapter describes no additional features of Emacs Lisp.  Instead
@c it gives advice on making effective use of the features described in the
@c previous chapters, and describes conventions Emacs Lisp programmers
@c should follow.
$BK\>O$G$O!"(BEmacs Lisp$B$N5!G=$K$D$$$F$5$i$K=R$Y$k$3$H$O$7$^$;$s!#(B
$B$+$o$j$K!"A0>O$^$G$K=R$Y$F$-$?5!G=$r8zN($h$/;H$&$?$a$N=u8@$d(B
Emacs Lisp$B%W%m%0%i%^$,=>$&$Y$-47=,$K$D$$$F=R$Y$^$9!#(B

@menu
* Coding Conventions::        Conventions for clean and robust programs.
* Compilation Tips::          Making compiled code run fast.
* Documentation Tips::        Writing readable documentation strings.
* Comment Tips::	      Conventions for writing comments.
* Library Headers::           Standard headers for library packages.
@end menu

@node Coding Conventions
@c @section Emacs Lisp Coding Conventions
@section Emacs Lisp$B$N%3!<%G%#%s%0$N47=,(B

@c   Here are conventions that you should follow when writing Emacs Lisp
@c code intended for widespread use:
$B$3$3$G$O!"FI<T$,9-$/;H$o$l$k$3$H$r0U?^$7$?(B
Emacs Lisp$B%3!<%I$r=q$/>l9g$K=>$&$Y$-47=,$K$D$$$F=R$Y$^$9!#(B

@itemize @bullet
@item
@c Since all global variables share the same name space, and all functions
@c share another name space, you should choose a short word to distinguish
@c your program from other Lisp programs.  Then take care to begin the
@c names of all global variables, constants, and functions with the chosen
@c prefix.  This helps avoid name conflicts.
$B$9$Y$F$N%0%m!<%P%kJQ?t$OF1$8L>A06u4V$r6&M-$7!"(B
$B$9$Y$F$N4X?t$bJL$NL>A06u4V$r6&M-$9$k$?$a!"(B
$BFI<T$N%W%m%0%i%`$rJL$N(BLisp$B%W%m%0%i%`$H6hJL$9$k$?$a$NC;$$C18l$rA*$V$Y$-$G$"$k!#(B
$B$=$7$F!"$9$Y$F$N%0%m!<%P%kJQ?t!"Dj?t!"4X?t$NL>A0$r(B
$BA*$s$G$*$$$?@\F,<-$G;O$a$k$h$&$KCm0U$9$k!#(B

@c This recommendation applies even to names for traditional Lisp
@c primitives that are not primitives in Emacs Lisp---even to
@c @code{copy-list}.  Believe it or not, there is more than one plausible
@c way to define @code{copy-list}.  Play it safe; append your name prefix
@c to produce a name like @code{foo-copy-list} or @code{mylib-copy-list}
@c instead.
Emacs Lisp$B$G$O4pK\4X?t$G$O$J$$$,(BLisp$B$NEAE}E*$J4pK\4X?t$NL>A0$K$5$($b(B
$B$3$N4+9p$OE,MQ$5$l$k!#(B
$B$?$H$((B@code{copy-list}$B$K$5$($b$G$"$k!#(B
$B?.$8$k$+$I$&$+$OJL$K$7$F!"(B
@code{copy-list}$B$N$b$C$H$b$i$7$$Dj5AJ}K!$OJ#?t$"$k!#(B
$B0BA4$G$"$k$?$a$K$O!"FI<T$N@\F,<-$rIU$1$F(B
@code{foo-copy-list}$B$d(B@code{mylib-copy-list}$B$N$h$&$JL>A0$K$9$k!#(B

@c If you write a function that you think ought to be added to Emacs under
@c a certain name, such as @code{twiddle-files}, don't call it by that name
@c in your program.  Call it @code{mylib-twiddle-files} in your program,
@c and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add
@c it to Emacs.  If and when we do, we can change the name easily enough.
$BFI<T$,!"(B@code{twiddle-files}$B$N$h$&$JFCDj$NL>A0$G(BEmacs$B$K(B
$BDI2C$9$Y$-4X?t$r=q$$$?>l9g$K$O!"FI<T$N%W%m%0%i%`$G$O(B
$B$=$NL>A0$G8F$P$J$$$h$&$K$9$k!#(B
$BFI<T$N%W%m%0%i%`$G$O(B@code{mylib-twiddle-files}$B$H$7$F$*$-!"(B
Emacs$B$KL>A0$rDI2C$9$k$h$&$KDs0F$9$k%a%$%k$r(B
@samp{bug-gnu-emacs@@gnu.org}$B$XAw$k!#(B
$B$o$l$o$l$,$=$N$h$&$K$9$k$3$H$r7hDj$7$?$H$-$K$O!"(B
$BL>A0$r$H$F$b4JC1$KJQ99$G$-$k!#(B

@c If one prefix is insufficient, your package may use two or three
@c alternative common prefixes, so long as they make sense.
1$B$D$N@\F,<-$G$OIT==J,$J>l9g$K$O!"(B
$B0UL#$,$"$k8B$j$O!"(B
2$B$D$+(B3$B$D$N6&DL$9$kJL$N@\F,<-$rFI<T$N%Q%C%1!<%8$G;H$C$F$b$h$$!#(B

@c Separate the prefix from the rest of the symbol name with a hyphen,
@c @samp{-}.  This will be consistent with Emacs itself and with most Emacs
@c Lisp programs.
$B@\F,<-$H%7%s%\%kL>$N;D$j$NItJ,$H$O%O%$%U%s(B@samp{-}$B$GJ,$1$k!#(B
$B$3$l$O(BEmacs$B<+?H$d$[$H$s$I$N(BEmacs Lisp$B%W%m%0%i%`$H0l4S@-$,$"$k!#(B

@item
@c It is often useful to put a call to @code{provide} in each separate
@c library program, at least if there is more than one entry point to the
@c program.
$B%W%m%0%i%`$K>/$J$/$H$bJ#?t$NF~$j8}$,$"$k>l9g$K$O!"(B
$B3F%i%$%V%i%j%W%m%0%i%`$K(B@code{provide}$B$N8F$S=P$7$,$"$k$H$7$P$7$PM-MQ$G$"$k!#(B

@item
@c If a file requires certain other library programs to be loaded
@c beforehand, then the comments at the beginning of the file should say
@c so.  Also, use @code{require} to make sure they are loaded.
$BJL$N%i%$%V%i%j%W%m%0%i%`$r$"$i$+$8$a%m!<%I$7$F$*$/I,MW$,$"$k%U%!%$%k$G$O!"(B
$B%U%!%$%k$N@hF,$N%3%^%s%I$K$=$N$h$&$K5-=R$7$F$*$/$3$H!#(B
$B$5$i$K!"I,MW$J$b$N$,3N<B$K%m!<%I$5$l$F$*$/$h$&$K(B@code{require}$B$r;H$&!#(B

@item
@c If one file @var{foo} uses a macro defined in another file @var{bar},
@c @var{foo} should contain this expression before the first use of the
@c macro:
$BJL$N%U%!%$%k(B@var{bar}$B$GDj5A$5$l$k%^%/%m$r(B
$B%U%!%$%k(B@var{foo}$B$G;H$C$F$$$k>l9g$K$O!"(B
@var{foo}$B$G$=$N%^%/%m$r;O$a$F;H$&$^$($K(B@var{foo}$B$K$D$.$N<0$,$"$k$3$H!#(B

@example
(eval-when-compile (require '@var{bar}))
@end example

@noindent
@c (And the library @var{bar} should contain @code{(provide '@var{bar})},
@c to make the @code{require} work.)  This will cause @var{bar} to be
@c loaded when you byte-compile @var{foo}.  Otherwise, you risk compiling
@c @var{foo} without the necessary macro loaded, and that would produce
@c compiled code that won't work right.  @xref{Compiling Macros}.
$B!J$5$i$K!"(B@code{require}$B$,F/$/$h$&$K!"(B
$B%i%$%V%i%j(B@var{bar}$B$K$O(B@code{(provide '@var{bar})}$B$,$"$k$3$H!#!K(B
$B$3$N<0$K$h$j!"(B@var{foo}$B$r%P%$%H%3%s%Q%$%k$9$k$H$-$K(B
@var{bar}$B$r%m!<%I$9$k$3$H$K$J$k!#(B
$B$5$b$J$$$H!"I,MW$J%^%/%m$r%m!<%I$;$:$K(B@var{foo}$B$r%3%s%Q%$%k$9$k4m81$r?/$7!"(B
$B@5$7$/F0:n$7$J$$%3%s%Q%$%k:Q$_%3!<%I$r@8@.$9$k$3$H$K$J$k!#(B
@pxref{Compiling Macros}$B!#(B

@c Using @code{eval-when-compile} avoids loading @var{bar} when
@c the compiled version of @var{foo} is @emph{used}.
@code{eval-when-compile}$B$r;H$&$3$H$G!"(B
@var{foo}$B$N%3%s%Q%$%k:Q$_$NHG$r(B@emph{$B;H$&(B}$B$H$-$K$O(B
@var{bar}$B$r%m!<%I$7$J$$!#(B

@item
@c When defining a major mode, please follow the major mode
@c conventions.  @xref{Major Mode Conventions}.
$B%a%8%c!<%b!<%I$rDj5A$9$k$H$-$K$O!"(B
$B%a%8%c!<%b!<%I$N47=,$K=>$&$3$H!#(B
@pxref{Major Mode Conventions}$B!#(B

@item
@c When defining a minor mode, please follow the minor mode
@c conventions.  @xref{Minor Mode Conventions}.
$B%^%$%J%b!<%I$rDj5A$9$k$H$-$K$O!"(B
$B%^%$%J%b!<%I$N47=,$K=>$&$3$H!#(B
@pxref{Minor Mode Conventions}$B!#(B

@item
@c If the purpose of a function is to tell you whether a certain condition
@c is true or false, give the function a name that ends in @samp{p}.  If
@c the name is one word, add just @samp{p}; if the name is multiple words,
@c add @samp{-p}.  Examples are @code{framep} and @code{frame-live-p}.
$B4X?t$NL\E*$,FCDj$N>r7o$rK~$?$9$+$I$&$+$rJs9p$9$k$N$G$"$l$P!"(B
$B$=$N4X?t$K$O(B@samp{p}$B$G=*$kL>A0$rIU$1$k!#(B
$BL>A0$,(B1$BC18l$G$"$k>l9g$K$O(B@samp{p}$B$@$1$rIU2C$9$k!#(B
$BJ#?t$NC18l$G$"$l$P(B@samp{-p}$B$rIU2C$9$k!#(B
$B$?$H$($P!"(B@code{framep}$B$d(B@code{frame-live-p}$B$G$"$k!#(B

@item
@c If a user option variable records a true-or-false condition, give it a
@c name that ends in @samp{-flag}.
$B??56$N>r7o$r5-O?$9$k%f!<%6!<%*%W%7%g%sJQ?t$K$O!"(B
@samp{-flag}$B$G=*$kL>A0$rIU$1$k!#(B

@item
@c @cindex reserved keys
@c @cindex keys, reserved
@cindex $BM=Ls:Q$_%-!<(B
@cindex $B%-!<!"M=Ls:Q$_(B
@c Please do not define @kbd{C-c @var{letter}} as a key in your major
@c modes.  These sequences are reserved for users; they are the
@c @strong{only} sequences reserved for users, so do not block them.
$BFI<T$N%a%8%c!<%b!<%I$G$O!"(B
@kbd{C-c @var{letter}}$B$r%-!<$H$7$FDj5A$7$J$$$3$H!#(B
$B$3$l$i$N%-!<Ns$O%f!<%6!<8~$1$KM=Ls:Q$_$G$"$k!#(B
$B$=$l$i(B@strong{$B$@$1(B}$B$,%f!<%6!<8~$1$KM=Ls$5$l$?%-!<Ns$G$"$j!"(B
$B$=$l$i$r6X;_$7$J$$$3$H!#(B

@c Instead, define sequences consisting of @kbd{C-c} followed by a control
@c character, a digit, or certain punctuation characters.  These sequences
@c are reserved for major modes.
$B$+$o$j$K!"(B@kbd{C-c}$B$N$"$H$K%3%s%H%m!<%kJ8;z$+?t;zJ8;z$+FCDj$N6gFIE@J8;z$,B3$/(B
$B%-!<Ns$rDj5A$9$k!#(B
$B$3$l$i$N%-!<Ns$O!"%a%8%c!<%b!<%IMQ$KM=Ls$7$F$"$k!#(B

@c Changing all the Emacs major modes to follow this convention was a lot
@c of work.  Abandoning this convention would make that work go to waste,
@c and inconvenience users.
Emacs$B$N$9$Y$F$N%b!<%I$r$3$N47=,$K=>$&$h$&$KJQ49$9$k$N$O(B
$B$?$$$X$s$J:n6HNL$G$"$C$?!#(B
$B$3$N47=,$r<N$F$5$k$H$=$N:n6H$r$`$@$K$7$F$7$^$$!"%f!<%6!<$K$bITJX$G$"$k!#(B

@item
@c Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
@c @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes.
@kbd{C-c}$B$N$"$H$K(B@kbd{@{}$B!"(B@kbd{@}}$B!"(B@kbd{<}$B!"(B@kbd{>}$B!"(B@kbd{:}$B!"(B@kbd{;}$B$N(B
$B$$$:$l$+$,B3$/%-!<Ns$b%a%8%c!<%b!<%IMQ$KM=Ls$7$F$"$k!#(B

@item
@c Sequences consisting of @kbd{C-c} followed by any other punctuation
@c character are allocated for minor modes.  Using them in a major mode is
@c not absolutely prohibited, but if you do that, the major mode binding
@c may be shadowed from time to time by minor modes.
@kbd{C-c}$B$N$"$H$K$3$l$i0J30$N6gFIE@J8;z$,B3$/%-!<Ns$O!"(B
$B%^%$%J%b!<%IMQ$K3d$jEv$F$F$"$k!#(B
$B$3$l$i$r%a%8%c!<%b!<%I$G;H$&$3$H$O@dBP6X;_$G$O$J$$$,!"(B
$B$3$l$i$r;H$&$H!"%a%8%c!<%b!<%I$N%P%$%s%G%#%s%0$,(B
$B%^%$%J%b!<%I$G$H$-$I$-1#$5$l$F$7$^$&!#(B

@item
@c Function keys @key{F5} through @key{F9} without modifier keys are
@c reserved for users to define.
$B=$>~%-!<$r;H$o$J$$%U%!%s%/%7%g%s%-!<(B@key{F5}$B$+$i(B@key{F9}$B$O!"(B
$B%f!<%6!<$,Dj5A$9$k$h$&$KM=Ls$7$F$"$k!#(B

@item
@c Do not bind @kbd{C-h} following any prefix character (including
@c @kbd{C-c}).  If you don't bind @kbd{C-h}, it is automatically available
@c as a help character for listing the subcommands of the prefix character.
$B!J(B@kbd{C-c}$B$r4^$`!KG$0U$N%W%l%U%#%C%/%9J8;z$KB3$/(B
@kbd{C-h}$B$r%P%$%s%I$7$J$$$3$H!#(B
@kbd{C-h}$B$r%P%$%s%I$7$J$1$l$P!"$3$l$O<+F0E*$K(B
$B%W%l%U%#%C%/%9J8;z$N%5%V%3%^%s%I0lMw$rI=<($9$k%X%k%WJ8;z$K$J$k!#(B

@item
@c Do not bind a key sequence ending in @key{ESC} except following
@c another @key{ESC}.  (That is, it is OK to bind a sequence ending in
@c @kbd{@key{ESC} @key{ESC}}.)
@key{ESC}$B$KB3$/(B@key{ESC}$B0J30$K$O!"(B
@key{ESC}$B$G=*$k%-!<Ns$r%P%$%s%I$7$J$$$3$H!#(B
$B!J$D$^$j!"(B@kbd{@key{ESC} @key{ESC}}$B$G=*$k%-!<Ns$r%P%$%s%I$9$k$N$O$h$$!#!K(B

@c The reason for this rule is that a non-prefix binding for @key{ESC} in
@c any context prevents recognition of escape sequences as function keys in
@c that context.
$B$3$N5,B'$NM}M3$O!"G$0U$NJ8L.$K$*$$$F(B
@key{ESC}$B$KBP$9$k%W%l%U%#%C%/%9$G$J$$%P%$%s%G%#%s%0$,$"$k$3$H$G!"(B
$B%(%9%1!<%W%7!<%1%s%9$r$=$NJ8L.$K$*$1$k%U%!%s%/%7%g%s%-!<$H(B
$BG'<1$9$k$3$H$rKI$2$k!#(B

@item
@c Anything which acts like a temporary mode or state which the user can
@c enter and leave should define @kbd{@key{ESC} @key{ESC}} of
@c = $B8m?"(B?                                                 or
@c @kbd{@key{ESC} @key{ESC} @key{ESC}} as a way to escape.
$B%f!<%6!<$,=PF~$j$G$-$k0l;~E*$J%b!<%I$d>uBV$N$h$&$KF/$/$b$N$G$O!"(B
$BC&=P<jCJ$H$7$F(B@kbd{@key{ESC} @key{ESC}}$B$d(B
@kbd{@key{ESC} @key{ESC} @key{ESC}}$B$rDj5A$9$k!#(B

@c For a state which accepts ordinary Emacs commands, or more generally any
@c kind of state in which @key{ESC} followed by a function key or arrow key
@c is potentially meaningful, then you must not define @kbd{@key{ESC}
@c @key{ESC}}, since that would preclude recognizing an escape sequence
@c after @key{ESC}.  In these states, you should define @kbd{@key{ESC}
@c @key{ESC} @key{ESC}} as the way to escape.  Otherwise, define
@c @kbd{@key{ESC} @key{ESC}} instead.
Emacs$B$NIaDL$N%3%^%s%I$r<u$1IU$1$k>uBV!"!"$"$k$$$O!"(B
$B$h$j0lHLE*$K$O(B@key{ESC}$B$KB3$1$F%U%!%s%/%7%g%s%-!<$dLp0u%-!<$,(B
$B0UL#$r;}$D2DG=@-$,$"$kG$0U$N>uBV$G$O!"(B
@key{ESC}$B$KB3$/%(%9%1!<%W%7!<%1%s%9$NG'<1$rK8$2$k(B
@kbd{@key{ESC} @key{ESC}}$B$rDj5A$9$k$Y$-$G$O$J$$!#(B
$B$=$N$h$&$J>uBV$G$O!"C&=P<jCJ$H$7$F(B@kbd{@key{ESC} @key{ESC} @key{ESC}}$B$r(B
$BDj5A$9$k!#(B
$B$5$b$J$1$l$PC&=P<jCJ$H$7$F(B@kbd{@key{ESC} @key{ESC}}$B$rDj5A$9$k!#(B

@item
@c Applications should not bind mouse events based on button 1 with the
@c shift key held down.  These events include @kbd{S-mouse-1},
@c @kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on.  They are reserved for
@c users.
$B%"%W%j%1!<%7%g%s$G$O!"%7%U%H%-!<$r2!$72<$2$?%\%?%s(B1$B4XO"$N%^%&%9%$%Y%s%H$r(B
$B%P%$%s%I$9$Y$-$G$O$J$$!#(B
$B$3$l$i$N%$%Y%s%H$K$O!"(B@kbd{S-mouse-1}$B!"(B@kbd{M-S-mouse-1}$B!"(B
@kbd{C-S-mouse-1}$B$J$I$,4^$^$l$k!#(B
$B$3$l$i$O%f!<%6!<8~$1$KM=Ls$7$F$"$k!#(B

@item
@c Special major modes used for read-only text should usually redefine
@c @kbd{mouse-2} and @key{RET} to trace some sort of reference in the text.
@c Modes such as Dired, Info, Compilation, and Occur redefine it in this
@c way.
$BFI$_=P$7@lMQ$N%F%-%9%H8~$1$NFCJL$J%a%8%c!<%b!<%I$G$O!"IaDL!"(B
@kbd{mouse-2}$B$H(B@key{RET}$B$r%F%-%9%HFb$N$"$k<o$N;2>H$r(B
$BC)$k$h$&$K:FDj5A$9$k$Y$-$G$"$k!#(B
dired$B!"(Binfo$B!"%3%s%Q%$%k!J(Bcompilation$B!K!"=P8=!J(Boccur$B!K$J$I$N%b!<%I$O(B
$B$3$N$h$&$K:FDj5A$7$F$$$k!#(B

@item
@c When a package provides a modification of ordinary Emacs behavior, it is
@c good to include a command to enable and disable the feature, Provide a
@c command named @code{@var{whatever}-mode} which turns the feature on or
@c off, and make it autoload (@pxref{Autoload}).  Design the package so
@c that simply loading it has no visible effect---that should not enable
@c the feature.  Users will request the feature by invoking the command.
Emacs$B$NIaDL$N$U$k$^$$$rJQ99$9$k$h$&$J%Q%C%1!<%8$G$O!"(B
$B$=$N5!G=$r%*%s!?%*%U$9$k%3%^%s%I$r4^$a$k$H$h$$!#(B
$B$=$N5!G=$r%*%s!?%*%U$9$k(B@code{@var{whatever}-mode}$B$H$$$&(B
$BL>A0$N%3%^%s%I$rMQ0U$7!"<+F0%m!<%I!J(B@pxref{Autoload}$B!K$9$k$h$&$K$9$k!#(B
$B%Q%C%1!<%8$r%m!<%I$7$?$@$1$G$O8+$?$a$K$O8z2L$,$J$$!"(B
$B$D$^$j!"$=$N5!G=$r%*%s$K$7$J$$$h$&$K%Q%C%1!<%8$r@_7W$9$k$3$H!#(B
$B%f!<%6!<$O%3%^%s%I$r5/F0$7$F$=$N5!G=$r%*%s$K$9$k!#(B

@item
@c It is a bad idea to define aliases for the Emacs primitives.  Use the
@c standard names instead.
Emacs$B$N4pK\4X?t$NJLL>$rDj5A$9$k$3$H$O0-$$9M$($G$"$k!#(B
$B$=$N$+$o$j$KI8=`$NL>A0$r;H$&!#(B

@item
@c Redefining (or advising) an Emacs primitive is discouraged.  It may do
@c the right thing for a particular program, but there is no telling what
@c other programs might break as a result.
Emacs$B$N4pK\4X?t$r:FDj5A!J$"$k$$$O%"%I%P%$%9!K$9$k$3$H$O6`$`$Y$-$G$"$k!#(B
$BFCDj$N%W%m%0%i%`$KBP$7$F$O@5$7$/F0:n$9$k$G$"$m$&$,!"(B
$BB>$N%W%m%0%i%`$,$=$N7k2L$I$&$J$k$+$O$o$+$i$J$$!#(B

@item
@c If a file does replace any of the functions or library programs of
@c standard Emacs, prominent comments at the beginning of the file should
@c say which functions are replaced, and how the behavior of the
@c replacements differs from that of the originals.
Emacs$B$NI8=`$N4X?t$d%i%$%V%i%j%W%m%0%i%`$rCV$-49$($k$h$&$J%U%!%$%k$G$O!"(B
$B$=$N%U%!%$%k$N@hF,$NL\N)$D%3%a%s%H$K(B
$B$I$N4X?t$rCV$-49$(85$N$U$k$^$$$H$NAj0cE@$r5-=R$9$k$3$H!#(B

@item
@c Please keep the names of your Emacs Lisp source files to 13 characters
@c or less.  This way, if the files are compiled, the compiled files' names
@c will be 14 characters or less, which is short enough to fit on all kinds
@c of Unix systems.
$BFI<T$N(BEmacs Lisp$B$N%=!<%9%U%!%$%k$NL>A0$O(B13$BJ8;z0J2<$K$9$k$3$H!#(B
$B$3$&$9$k$H!"%U%!%$%k$r%3%s%Q%$%k$7$F$b!"(B
$B%3%s%Q%$%k:Q$_$N%U%!%$%kL>$O(B14$BJ8;z0J2<$K$J$j!"(B
$B$I$s$J<oN`$N(BUNIX$B%7%9%F%`$K$b<}$^$k$@$1$NC;$5$G$"$k!#(B

@item
@c Don't use @code{next-line} or @code{previous-line} in programs; nearly
@c always, @code{forward-line} is more convenient as well as more
@c predictable and robust.  @xref{Text Lines}.
$B%W%m%0%i%`$G$O(B@code{next-line}$B$d(B@code{previous-line}$B$r;H$o$J$$$3$H!#(B
$B$[$H$s$I$N>l9g!"(B@code{forward-line}$B$N$[$&$,$h$jJXMx$G$"$j!"(B
$BM=B,2DG=$G7xO4$G$b$"$k!#(B
@pxref{Text Lines}$B!#(B

@item
@c Don't call functions that set the mark, unless setting the mark is one
@c of the intended features of your program.  The mark is a user-level
@c feature, so it is incorrect to change the mark except to supply a value
@c for the user's benefit.  @xref{The Mark}.
$B%^!<%/$r@_Dj$9$k$3$H$,FI<T$N%W%m%0%i%`$N0U?^$7$?5!G=$N0lIt$G$J$1$l$P!"(B
$B%^!<%/$r@_Dj$9$k4X?t$O8F$S=P$5$J$$$3$H!#(B
$B%^!<%/$O%f!<%6!<%l%Y%k$N5!G=$G$"$j!"(B
$B%f!<%6!<$NJX59$N$?$a$KCM$r;XDj$9$k0J30$K$O!"(B
$B%^!<%/$rJQ99$9$k$N$O@5$7$/$J$$!#(B
@pxref{The Mark}$B!#(B

@c In particular, don't use any of these functions:
$BFC$K!"0J2<$N$$$:$l$N4X?t$b;H$o$J$$$3$H!#(B

@itemize @bullet
@item
@code{beginning-of-buffer}, @code{end-of-buffer}
@item
@code{replace-string}, @code{replace-regexp}
@end itemize

@c If you just want to move point, or replace a certain string, without any
@c of the other features intended for interactive users, you can replace
@c these functions with one or two lines of simple Lisp code.
$BBPOCE*$J%f!<%6!<8~$1$NB>$N5!G=$rI,MW$H$;$:$K(B
$BC1$K%]%$%s%H$r0\F0$7$?$jFCDj$NJ8;zNs$rCV49$9$k$K$O!"(B
$B$3$l$i$N4X?t$O(B1$B9T$+(B2$B9T$NC1=c$J(BLisp$B%3!<%I$GCV$-49$($i$l$k!#(B

@item
@c Use lists rather than vectors, except when there is a particular reason
@c to use a vector.  Lisp has more facilities for manipulating lists than
@c for vectors, and working with lists is usually more convenient.
$B%Y%/%H%k$r;H$&FCJL$JM}M3$,$J$$8B$j$O!"%Y%/%H%k$G$O$J$/%j%9%H$r;H$&!#(B
Lisp$B$K$O!"%Y%/%H%k$KBP$9$k$h$j$b%j%9%H$rA`:n$9$k5!G=$N$[$&$,B?$/$"$j!"(B
$B%j%9%H$r07$&$[$&$,IaDL$O$h$j4JJX$G$"$k!#(B

@c Vectors are advantageous for tables that are substantial in size and are
@c accessed in random order (not searched front to back), provided there is
@c no need to insert or delete elements (only lists allow that).
$B!J%j%9%H$@$1$,5v$9!KMWAG$rA^F~$7$?$j:o=|$9$kI,MW$,$J$$$N$G$"$l$P!"(B
$B$"$kDxEY$N%5%$%:$,$"$j(B
$B!J@hF,$+$iKvHx$K8~$1$F$NC5:w$G$O$J$/!K%i%s%@%`$K;2>H$9$kI=$K$O(B
$B%Y%/%H%k$N$[$&$,E,$7$F$$$k!#(B

@item
@c The recommended way to print a message in the echo area is with
@c the @code{message} function, not @code{princ}.  @xref{The Echo Area}.
$B%(%3!<NN0h$K%a%C%;!<%8$rI=<($9$k?d>)J}K!$O!"(B
@code{princ}$B$G$O$J$/4X?t(B@code{message}$B$r;H$&$3$H$G$"$k!#(B
@pxref{The Echo Area}$B!#(B

@item
@c When you encounter an error condition, call the function @code{error}
@c (or @code{signal}).  The function @code{error} does not return.
@c @xref{Signaling Errors}.
$B%(%i!<>r7o$K=P2q$C$?$H$-$K$O!"(B
$B4X?t(B@code{error}$B!J$"$k$$$O(B@code{signal}$B!K$r8F$S=P$9!#(B
$B4X?t(B@code{error}$B$OLa$C$F$3$J$$!#(B
@pxref{Signaling Errors}$B!#(B

@c Do not use @code{message}, @code{throw}, @code{sleep-for},
@c or @code{beep} to report errors.
$B%(%i!<$rJs9p$9$k$?$a$K!"(B
@code{message}$B!"(B@code{throw}$B!"(B@code{sleep-for}$B!"(B@code{beep}$B$O;H$o$J$$$3$H!#(B

@item
@c An error message should start with a capital letter but should not end
@c with a period.
$B%(%i!<%a%C%;!<%8$OBg1QJ8;z$G;O$a!"%T%j%*%I$G=*$($J$$$3$H!#(B

@item
@c Many commands that take a long time to execute display a message that
@c says @samp{Operating...} when they start, and change it to
@c @samp{Operating...done} when they finish.  Please keep the style of
@c these messages uniform: @emph{no} space around the ellipsis, and
@c @emph{no} period at the end.
$B<B9T$K;~4V$rMW$9$kB?$/$N%3%^%s%I$G$O!"(B
$B3+;O;~$K$O(B@samp{Operating...}$B$N%a%C%;!<%8$rI=<($7!"(B
$B=*N;;~$K$O$=$l$r(B@samp{Operating...done}$B$HJQ$($k!#(B
$B$3$l$i$N%a%C%;!<%8$N7A$rF1$8$K$7$F$*$/$3$H!#(B
@code{...}$B$N<~$j$K6uGr$O(B@emph{$B$J$/(B}$B!"KvHx$K%T%j%*%I$b(B@emph{$B$J$$(B}$B!#(B

@item
@c Try to avoid using recursive edits.  Instead, do what the Rmail @kbd{e}
@c command does: use a new local keymap that contains one command defined
@c to switch back to the old local keymap.  Or do what the
@c @code{edit-options} command does: switch to another buffer and let the
@c user switch back at will.  @xref{Recursive Editing}.
$B:F5"JT=8$N;HMQ$OHr$1$k$h$&$KEX$a$k$3$H!#(B
$B$=$N$+$o$j$K(Brmail$B$N%3%^%s%I(B@kbd{e}$B$N$h$&$K$9$k!#(B
$B$D$^$j!"8E$$%m!<%+%k%-!<%^%C%W$KLa$k$?$a$N%3%^%s%I$r<}$a$?(B
$B?7$7$$%m!<%+%k%-!<%^%C%W$r;H$&!#(B
$B$"$k$$$O!"%3%^%s%I(B@code{edit-options}$B$N$h$&$K$9$k!#(B
$BJL$N%P%C%U%!$K@Z$jBX$(!"La$k$N$O%f!<%6!<$KG$$;$k!#(B
@pxref{Recursive Editing}$B!#(B

@item
@c In some other systems there is a convention of choosing variable names
@c that begin and end with @samp{*}.  We don't use that convention in Emacs
@c Lisp, so please don't use it in your programs.  (Emacs uses such names
@c only for special-purpose buffers.)  The users will find Emacs more
@c coherent if all libraries use the same conventions.
$BJQ?tL>$r(B@samp{*}$B$G;O$a$?$j=*$($k47=,$,$"$k%7%9%F%`$b$"$k!#(B
Emacs Lisp$B$G$O$3$N47=,$r;H$o$J$$$N$G!"FI<T$N%W%m%0%i%`$G$b;H$o$J$$$3$H!#(B
$B!J(BEmacs$B$G$O!"FCJL$JL\E*$N%P%C%U%!$K$N$_$=$N$h$&$JL>A0$r;H$&!#!K(B
$B$9$Y$F$N%i%$%V%i%j$GF1$847=,$r;H$&$H!"(B
$B%f!<%6!<$K$O(BEmacs$B$,$h$j@09g$7$F8+$($k!#(B

@item
@c Try to avoid compiler warnings about undefined free variables, by adding
@c @code{defvar} definitions for these variables.
$B<+M3JQ?t$K$O(B@code{defvar}$B$NDj5A$rDI2C$7$F!"(B
$B%3%s%Q%$%k;~$NL$Dj5A$J<+M3JQ?t$KBP$9$k7Y9p$rHr$1$k$h$&$KEX$a$k$3$H!#(B

@c If you bind a variable in one function, and use it or set it in another
@c function, the compiler warns about the latter function unless the
@c variable has a definition.  But often these variables have short names,
@c and it is not clean for Lisp packages to define such variable names.
@c Therefore, you should rename the variable to start with the name prefix
@c used for the other functions and variables in your package.
$B$"$k4X?t$GJQ?t$rB+G{$7$=$NJQ?t$rJL$N4X?t$G;H$C$?$j@_Dj$9$k$H!"(B
$B$=$NJQ?t$rDj5A$7$J$$8B$j%3%s%Q%$%i$O8e<T$N4X?t$K$D$$$F7Y9p$r=P$9!#(B
$B$7$+$7!"$7$P$7$P$3$l$i$NJQ?t$OC;$$L>A0$G!"(B
Lisp$B%Q%C%1!<%8$G$=$N$h$&$JJQ?tL>$rDj5A$9$Y$-$+$I$&$+L@$i$+$G$J$$!#(B
$B$7$?$,$C$F!"$=$N$h$&$JJQ?t$NL>A0$O!"(B
$BFI<T$N%Q%C%1!<%8$NB>$N4X?t$dJQ?t$K;H$C$F$$$k@\F,<-$G(B
$B;O$^$kL>A0$K2~L>$9$Y$-$G$"$k!#(B

@item
@c Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
@c default indentation parameters.
$B%G%U%)%k%H$N;z2<$2%Q%i%a!<%?$r;H$C$F!"(B
$B3F4X?t$r(B@kbd{C-M-q}$B!J(B@code{indent-sexp}$B!K$G;z2<$2$9$k$3$H!#(B

@item
@c Don't make a habit of putting close-parentheses on lines by themselves;
@c Lisp programmers find this disconcerting.  Once in a while, when there
@c is a sequence of many consecutive close-parentheses, it may make sense
@c to split the sequence in one or two significant places.
$BJD$83g8L$@$1$N9T$K$9$kJJ$r$D$1$J$$$3$H!#(B
Lisp$B%W%m%0%i%^$O$3$l$KEvOG$9$k!#(B
$B$?$^$K$O!"JD$83g8L$,B??t8DO"B3$9$k$H$-$K(B
$B$=$l$i$r(B1$B$D$+(B2$B$D$N2t$KJ,$1$k$3$H$O0UL#$,$"$k!#(B

@item
@c Please put a copyright notice on the file if you give copies to anyone.
@c Use a message like this one:
$B%3%T!<$rG[I[$9$k>l9g$K$O!"%U%!%$%k$KCx:n8"I=<($rF~$l$k$3$H!#(B
$B$D$.$N$h$&$JJ8LL$r;H$&!#(B

@smallexample
;; Copyright (C) @var{year} @var{name}

;; This program is free software; you can redistribute it and/or
;; modify it under the terms of the GNU General Public License as
;; published by the Free Software Foundation; either version 2 of
;; the License, or (at your option) any later version.

;; This program is distributed in the hope that it will be
;; useful, but WITHOUT ANY WARRANTY; without even the implied
;; warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
;; PURPOSE.  See the GNU General Public License for more details.

;; You should have received a copy of the GNU General Public
;; License along with this program; if not, write to the Free
;; Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
;; MA 02111-1307 USA
@end smallexample

@c If you have signed papers to assign the copyright to the Foundation,
@c then use @samp{Free Software Foundation, Inc.} as @var{name}.
@c Otherwise, use your name.
$BFI<T$,%U%j!<%=%U%H%&%'%"%U%!%&%s%G!<%7%g%s$KCx:n8"$r0Q>y$9$k7@Ls$r(B
$B7k$s$G$$$k$H$-$K$O!"(B
@var{name}$B$H$7$F(B@samp{Free Software Foundation, Inc.}$B$r;H$&!#(B
$B$5$b$J$1$l$PFI<T<+?H$NL>A0$r;H$&!#(B
@end itemize

@node Compilation Tips
@c @section Tips for Making Compiled Code Fast
@section $B%3%s%Q%$%k:Q$_%3!<%I$rB.$/$9$k%R%s%H(B
@c @cindex execution speed
@c @cindex speedups
@cindex $B<B9TB.EY(B
@cindex $BB.EY8~>e(B

@c   Here are ways of improving the execution speed of byte-compiled
@c Lisp programs.
$B%P%$%H%3%s%Q%$%k$7$?(BLisp$B%W%m%0%i%`$N<B9TB.EY$r2~NI$9$kJ}K!$r<($7$^$9!#(B

@itemize @bullet
@item
@c @cindex profiling
@c @cindex timing programs
@cindex $B%W%m%U%!%$%k(B
@cindex $B%W%m%0%i%`$r7W;~$9$k(B
@cindex @file{profile.el}
@cindex @file{elp.el}
@c Profile your program with the @file{profile} library or the @file{elp}
@c library.  See the files @file{profile.el} and @file{elp.el} for
@c instructions.
$B%i%$%V%i%j(B@file{profile}$B$d%i%$%V%i%j(B@file{elp}$B$G!"(B
$BFI<T$N%W%m%0%i%`$r7WB,$9$k!#(B
$BA`:nJ}K!$K$D$$$F$O%U%!%$%k(B@file{profile.el}$B$H(B@file{elp.el}$B$r;2>H!#(B

@item
@c Use iteration rather than recursion whenever possible.
@c Function calls are slow in Emacs Lisp even when a compiled function
@c is calling another compiled function.
$B2DG=$J>l9g$K$O:F5"$G$O$J$/7+$jJV$7$r;H$&!#(B
$B%3%s%Q%$%k:Q$_$N4X?t$,JL$N%3%s%Q%$%k:Q$_4X?t$r8F$S=P$9>l9g$G$"$C$F$b(B
Emacs Lisp$B$G$O4X?t8F$S=P$7$OCY$$!#(B

@item
@c Using the primitive list-searching functions @code{memq}, @code{member},
@c @code{assq}, or @code{assoc} is even faster than explicit iteration.  It
@c can be worth rearranging a data structure so that one of these primitive
@c search functions can be used.
@code{memq}$B!"(B@code{member}$B!"(B@code{assq}$B!"(B@code{assoc}$B$N%j%9%HC5:w4pK\4X?t$r(B
$B;H$&$[$&$,L@<(E*$J7+$jJV$7$h$j$bB.$$!#(B
$B$3$l$i$NC5:w4pK\4X?t$N(B1$B$D$r;H$($k$h$&$K%G!<%?9=B$$rJQ99$9$k2ACM$O$"$k!#(B

@item
@c Certain built-in functions are handled specially in byte-compiled code, 
@c avoiding the need for an ordinary function call.  It is a good idea to
@c use these functions rather than alternatives.  To see whether a function
@c is handled specially by the compiler, examine its @code{byte-compile}
@c property.  If the property is non-@code{nil}, then the function is
@c handled specially.
$B$"$k<o$NAH$_9~$_4X?t$O!"%P%$%H%3%s%Q%$%k:Q$_$N%3!<%I$G$O(B
$BIaDL$N4X?t8F$S=P$7$rHr$1$k$h$&$KFCJL$K07$o$l$k!#(B
$B$3$l$i$N4X?t$r;H$&$N$O$h$$$3$H$G$"$k!#(B
$B%3%s%Q%$%i$,4X?t$rFCJL$K07$&$+$I$&$+$rD4$Y$k$K$O!"(B
$B$=$NB0@-(B@code{byte-compile}$B$rD4$Y$k!#(B
$BB0@-$,(B@code{nil}$B0J30$G$"$l$P!"$=$N4X?t$OFCJL$K07$o$l$k!#(B

@c For example, the following input will show you that @code{aref} is
@c compiled specially (@pxref{Array Functions}):
$B$?$H$($P!"$D$.$NF~NO$O!"(B@code{aref}$B$,FCJL$K%3%s%Q%$%k$5$l$k$3$H$r<($9(B
$B!J(B@pxref{Array Functions}$B!K!#(B

@example
@group
(get 'aref 'byte-compile)
     @result{} byte-compile-two-args
@end group
@end example

@item
@c If calling a small function accounts for a substantial part of your
@c program's running time, make the function inline.  This eliminates
@c the function call overhead.  Since making a function inline reduces
@c the flexibility of changing the program, don't do it unless it gives
@c a noticeable speedup in something slow enough that users care about
@c the speed.  @xref{Inline Functions}.
$BFI<T$N%W%m%0%i%`$N<B9T;~4V$N$+$J$j$NItJ,$r>.$5$J4X?t$N8F$S=P$7$,(B
$B@j$a$k$H$-$K$O!"$=$N4X?t$r%$%s%i%$%s$K$9$k!#(B
$B$3$l$K$h$j4X?t8F$S=P$7$N%*!<%P%X%C%I$r:o=|$G$-$k!#(B
$B4X?t$r%$%s%i%$%s$K$9$k$H%W%m%0%i%`JQ99$N=@Fp@-$r8:$8$k$N$G!"(B
$B%f!<%6!<$,B.EY$r5$$K$9$k$[$ICY$$ItJ,$N==J,$JB.EY8~>e$,F@$i$l$J$$8B$j!"(B
$B$3$N$h$&$K$7$J$$$3$H!#(B
@pxref{Inline Functions}$B!#(B
@end itemize

@node Documentation Tips
@c @section Tips for Documentation Strings
@section $B@bL@J8;zNs$K4X$9$k%R%s%H(B

@tindex checkdoc-minor-mode
@findex checkdoc-minor-mode
@c   Here are some tips and conventions for the writing of documentation
@c strings.  You can check many of these conventions by running the command
@c @kbd{M-x checkdoc-minor-mode}.
$B@bL@J8;zNs$r=q$/$&$($G$N%R%s%H$d47=,$r=R$Y$^$9!#(B
$B%3%^%s%I(B@kbd{M-x checkdoc-minor-mode}$B$r<B9T$7$F!"(B
$B$3$l$i$N47=,$NB?$/$r3NG'$G$-$^$9!#(B

@itemize @bullet
@item
@c Every command, function, or variable intended for users to know about
@c should have a documentation string.
$B%f!<%6!<$,CN$C$F$*$/$3$H$r0U?^$7$?3F%3%^%s%I!"4X?t!"JQ?t$K$O!"(B
$B@bL@J8;zNs$rIU$1$k$3$H!#(B

@item
@c An internal variable or subroutine of a Lisp program might as well have
@c a documentation string.  In earlier Emacs versions, you could save space
@c by using a comment instead of a documentation string, but that is no
@c longer the case.
Lisp$B%W%m%0%i%`$NFbItJQ?t$d%5%V%k!<%F%#%s$K$b@bL@J8;zNs$rIU$1$k!#(B
Emacs$B$N=i4|$NHG$G$O!"@bL@J8;zNs$N$+$o$j$K%3%a%s%H$r;H$&$HMFNL$r@aLs$G$-$?$,!"(B
$B:#$O$3$l$O$"$F$O$^$i$J$$!#(B

@item
@c The first line of the documentation string should consist of one or two
@c complete sentences that stand on their own as a summary.  @kbd{M-x
@c apropos} displays just the first line, and if it doesn't stand on its
@c own, the result looks bad.  In particular, start the first line with a
@c capital letter and end with a period.
$B@bL@J8;zNs$N:G=i$N9T$O!"(B1$B$D$+(B2$B$D$N40A4$JJ8$G$"$j!"(B
$B$=$l$@$1$G35MW$rI=$7$F$$$k$3$H!#(B
@kbd{M-x apropos}$B$O@bL@J8;zNs$N:G=i$N9T$@$1$rI=<($9$k$?$a!"(B
$B$=$l$@$1$G==J,$KI=$;$J$$$HI=<(7k2L$,0-$/$J$k!#(B
$BFC$K!":G=i$N9T$OBgJ8;z$G;O$a!"%T%j%*%I$G=*$($k$3$H!#(B

@c The documentation string can have additional lines that expand on the
@c details of how to use the function or variable.  The additional lines
@c should be made up of complete sentences also, but they may be filled if
@c that looks good.
$B@bL@J8;zNs$K$O!"4X?t$dJQ?t$N;H$$J}$N>\:Y$r=R$Y$kDI2C$N9T$,$"$C$F$h$$!#(B
$B$=$l$i$N9T$b40A4$JJ8$+$i@.$k$Y$-$G$"$k$,!"8+$?$a$r$h$/$9$k$?$a$K(B
$BE,Ev$K5M$a$F$h$$!#(B

@item
@c For consistency, phrase the verb in the first sentence of a
@c function's documentation string as an infinitive with ``to'' omitted.  For
@c instance, use ``Return the cons of A and B.'' in preference to ``Returns
@c the cons of A and B@.''  Usually it looks good to do likewise for the
@c rest of the first paragraph.  Subsequent paragraphs usually look better
@c if they have proper subjects.
$B0l4S@-$,$"$k$h$&$K!"4X?t$N@bL@J8;zNs$N:G=i$NJ8$NF0;l$O(B
$B!X(Bto$B!Y$r>J$$$?ITDj;l$K$9$k!#(B
$B$?$H$($P!"!X(BReturns the cons of A and B@.$B!Y$G$O$J$/(B
$B!X(BReturn the cons of A and B.$B!Y$H$9$k!#(B
$B:G=i$N9T$N;D$j$NJ8$K$D$$$F$bF1MM$K$9$k$H$h$$!#(B
$B0J9_$NJ8@a$G$OE,@Z$J<g8l$,$"$k$[$&$,0lHL$K$O$h$$!#(B

@item
@c Write documentation strings in the active voice, not the passive, and in
@c the present tense, not the future.  For instance, use ``Return a list
@c containing A and B.'' instead of ``A list containing A and B will be
@c returned.''
$B@bL@J8;zNs$O<uF0BV$G$O$J$/G=F0BV$G=q$-!"L$Mh7A$G$O$J$/8=:_7A$G=q$/!#(B
$B$?$H$($P!"!X(BA list containing A and B will be returned.$B!Y$G$O$J$/(B
$B!X(BReturn a list containing A and B.$B!Y$H=q$/!#(B

@item
@c Avoid using the word ``cause'' (or its equivalents) unnecessarily.
@c Instead of, ``Cause Emacs to display text in boldface,'' write just
@c ``Display text in boldface.''
$BITI,MW$KC18l!X(Bcause$B!Y!J$*$h$SF15A8l!K$r;H$o$J$$$3$H!#(B
$B!X(BCause Emacs to display text in boldface,$B!Y$G$O$J$/(B
$BC1$K!X(BDisplay text in boldface.$B!Y$H=q$/!#(B

@item
@c Do not start or end a documentation string with whitespace.
$B@bL@J8;zNs$O!"GrJ8;z$G;O$a$?$j=*$($J$$$3$H!#(B

@item
@c Format the documentation string so that it fits in an Emacs window on an
@c 80-column screen.  It is a good idea for most lines to be no wider than
@c 60 characters.  The first line can be wider if necessary to fit the 
@c information that ought to be there.
80$B%3%i%`$N%9%/%j!<%s>e$N(BEmacs$B$N%&%#%s%I%&$K<}$^$k$h$&$K(B
$B@bL@J8;zNs$r@07A$9$k!#(B
$B$[$H$s$I$N9T$r(B60$BJ8;z$r1[$($J$$$h$&$K$9$k$H$h$$!#(B
$BI,MW$J>pJs$rF~$l$k$?$a$J$i$P:G=i$N9T$,D9$/$J$C$F$b$h$$!#(B

@c However, rather than simply filling the entire documentation string, you
@c can make it much more readable by choosing line breaks with care.
@c Use blank lines between topics if the documentation string is long.
$B$7$+$7!"@bL@J8;zNsA4BN$rC1=c$K@07A$9$k$h$j$O!"(B
$BCm0U?<$/9TJ,$1$9$k$HFI$_$d$9$/$J$k!#(B
$B@bL@J8;zNs$,D9$$>l9g$K$O!"OCBj$4$H$K6u9T$G6h@Z$k!#(B
 
@item
@c @strong{Do not} indent subsequent lines of a documentation string so
@c that the text is lined up in the source code with the text of the first
@c line.  This looks nice in the source code, but looks bizarre when users
@c view the documentation.  Remember that the indentation before the
@c starting double-quote is not part of the string!
$B%=!<%9%3!<%I>e$G@bL@J8;zNs$N:G=i$N9T$KB7$($k$?$a$K(B
$B@bL@J8;zNs$N;D$j$N9T$r;z2<$2(B@strong{$B$7$J$$$3$H(B}$B!#(B
$B%=!<%9%3!<%I>e$G$O8+$?$a$,$h$/$F$b!"(B
$B%f!<%6!<$,@bL@J8;z$r8+$k$H$-$K$O4qL/$K8+$($k!#(B
$BJ8;zNs$r;O$a$k%@%V%k%/%)!<%H$N$^$($K$"$k;z2<$2$O(B
$BJ8;zNs$N0lIt$G$O$J$$$3$H$KCm0U!*(B

@item
@c When the user tries to use a disabled command, Emacs displays just the
@c first paragraph of its documentation string---everything through the
@c first blank line.  If you wish, you can choose which information to
@c include before the first blank line so as to make this display useful.
$B%f!<%6!<$,6X;_%3%^%s%I$r<B9T$7$h$&$H$9$k$H!"(B
Emacs$B$OEv3:%3%^%s%I$N@bL@J8;zNs$N:G=i$NJ8@a!"(B
$B$D$^$j!":G=i$N6u9T$^$G$rI=<($9$k!#(B
$BI,MW$J$i$P!":G=i$N6u9T$N$^$($KF~$l$k$Y$->pJs$rA*$s$G!"(B
$B$3$N$h$&$JI=<($,M-MQ$G$"$k$h$&$K$9$k!#(B

@item
@c A variable's documentation string should start with @samp{*} if the
@c variable is one that users would often want to set interactively.  If
@c the value is a long list, or a function, or if the variable would be set
@c only in init files, then don't start the documentation string with
@c @samp{*}.  @xref{Defining Variables}.
$B%f!<%6!<$,BPOCE*$K@_Dj$7$?$,$k$h$&$JJQ?t$G$O!"(B
$B$=$NJQ?t$N@bL@J8;zNs$O(B@samp{*}$B$G;O$a$k!#(B
$BJQ?t$NCM$,!"D9$$%j%9%H$d4X?t$G$"$k$H$-!"$"$k$$$O!"(B
$B=i4|2=%U%!%$%k$G$N$_@_Dj$9$k$h$&$JJQ?t$G$"$k$H$-$K$O!"(B
$B$=$N@bL@J8;zNs$r(B@samp{*}$B$G;O$a$J$$$3$H!#(B
@pxref{Defining Variables}$B!#(B

@item
@c The documentation string for a variable that is a yes-or-no flag should
@c start with words such as ``Non-nil means@dots{}'', to make it clear that
@c all non-@code{nil} values are equivalent and indicate explicitly what
@c @code{nil} and non-@code{nil} mean.
yes/no$B$N%U%i%0$rI=$9JQ?t$N@bL@J8;zNs$O!X(BNon-nil means@dots{}$B!Y$N$h$&$J(B
$BC18l$G;O$a$F!"(B@code{nil}$B0J30$NCM$O$9$Y$FF1CM$G$"$k$3$H$rL@$i$+$K$7!"(B
@code{nil}$B$H(B@code{nil}$B0J30$N0UL#$rL@3N$K<($9$3$H!#(B

@item
@c When a function's documentation string mentions the value of an argument
@c of the function, use the argument name in capital letters as if it were
@c a name for that value.  Thus, the documentation string of the function
@c @code{/} refers to its second argument as @samp{DIVISOR}, because the
@c actual argument name is @code{divisor}.
$B4X?t$N@bL@J8;zNs$G$=$N0z?t$K$D$$$F=R$Y$k$H$-$K$O!"(B
$B$=$N0z?t$NCM$rI=$9L>A0$K$OBgJ8;z$G=q$$$?0z?tL>$r;H$&!#(B
$B$7$?$,$C$F!"4X?t(B@code{/}$B$N@bL@J8;zNs$G$O!"(B
$B$=$NBh(B2$B0z?t$NL>A0$O(B@code{divisor}$B$J$N$G!"(B@samp{DIVISOR}$B$HI=$9!#(B

@c Also use all caps for meta-syntactic variables, such as when you show
@c the decomposition of a list or vector into subunits, some of which may
@c vary.
$B$^$?!"%j%9%H$d%Y%/%H%k$r!J$=$N0lIt$,JQ2=$9$k$+$b$7$l$J$$!K9=@.ItJ,$K(B
$BJ,2r$7$?$b$N$r<($9$H$-$J$I$N%a%?JQ?t$K$O!"$9$Y$FBgJ8;z$r;H$&!#(B

@item
@iftex
@c When a documentation string refers to a Lisp symbol, write it as it
@c would be printed (which usually means in lower case), with single-quotes
@c around it.  For example: @samp{`lambda'}.  There are two exceptions:
@c write @code{t} and @code{nil} without single-quotes.
$B@bL@J8;zNs$G(BLisp$B%7%s%\%k$r;2>H$9$k$H$-$K$O!"(B
$B$=$l$,I=<($5$l$k$H$-!J$D$^$jIaDL$O$9$Y$F>.J8;z!K$N$h$&$K(B
$B%7%s%0%k%/%)!<%H$G0O$C$F=q$/!#(B
$B$3$l$K$O(B2$B$DNc30$,$"$j!"(B@code{t}$B$H(B@code{nil}$B$O(B
$B%7%s%0%k%/%)!<%H$G0O$^$J$$!#(B
@end iftex
@ifinfo
@c When a documentation string refers to a Lisp symbol, write it as it
@c would be printed (which usually means in lower case), with single-quotes
@c around it.  For example: @samp{lambda}.  There are two exceptions: write
@c t and nil without single-quotes.  (In this manual, we use a different
@c convention, with single-quotes for all symbols.)
$B@bL@J8;zNs$G(BLisp$B%7%s%\%k$r;2>H$9$k$H$-$K$O!"(B
$B$=$l$,I=<($5$l$k$H$-!J$D$^$jIaDL$O$9$Y$F>.J8;z!K$N$h$&$K(B
$B%7%s%0%k%/%)!<%H$G0O$C$F=q$/!#(B
$B$?$H$($P!"(B@samp{lambda}$B$G$"$k!#(B
$B$3$l$K$O(B2$B$DNc30$,$"$j!"(Bt$B$H(Bnil$B$O%7%s%0%k%/%)!<%H$G0O$^$:$K=q$/!#(B
$B!JK\=q$G$O!"$9$Y$F$N%7%s%\%k$r%7%s%0%k%/%)!<%H$G0O$`JL$N47=,$rMQ$$$F$$$k!#!K(B
@end ifinfo

@c Help mode automatically creates a hyperlink when a documentation string
@c uses a symbol name inside single quotes, if the symbol has either a
@c function or a variable definition.  You do not need to do anything
@c special to make use of this feature.  However, when a symbol has both a
@c function definition and a variable definition, and you want to refer to
@c just one of them, you can specify which one by writing one of the words
@c @samp{variable}, @samp{option}, @samp{function}, or @samp{command},
@c immediately before the symbol name.  (Case makes no difference in
@c recognizing these indicator words.)  For example, if you write
$B%X%k%W%b!<%I$G$O!"@bL@J8;zNs$G%7%s%0%k%/%)!<%H$G0O$C$?%7%s%\%k$r;H$&$H!"(B
$B$=$N%7%s%\%k$K4X?tDj5A$dJQ?tDj5A$,$"$k$H$-$K$O<+F0E*$K(B
$B%O%$%Q!<%j%s%/$r:n@.$9$k!#(B
$B$3$N5!G=$rMxMQ$9$k$?$a$KFCJL$J$3$H$r$9$kI,MW$O$J$$!#(B
$B$7$+$7!"%7%s%\%k$K4X?tDj5A$HJQ?tDj5A$NN>J}$,$"$j!"(B
$B$I$A$i$+0lJ}$N$_$r;2>H$7$?$$>l9g$K$O!"(B
$B%7%s%\%k$NL>A0$N$^$($K(B
@samp{variable}$B!"(B@samp{option}$B!"(B@samp{function}$B!"(B@samp{command}$B$N(B
$B$$$:$l$+$NC18l$r=q$/$@$1$G$I$A$i$G$"$k$+$r;XDj$G$-$k!#(B
$B!J$3$l$i$NC18l$rG'<1$9$k$H$-$K$OBgJ8;z>.J8;z$O6hJL$7$J$$!#!K(B
$B$?$H$($P$D$.$N$h$&$K=q$/$H!"(B

@example
This function sets the variable `buffer-file-name'.
@end example

@noindent
@c then the hyperlink will refer only to the variable documentation of
@c @code{buffer-file-name}, and not to its function documentation.
$B%O%$%Q!<%j%s%/$O!"JQ?t(B@code{buffer-file-name}$B$N@bL@J8;zNs$r;X$7!"(B
$B$=$N4X?t$N@bL@J8;zNs$O;X$5$J$$!#(B

@c If a symbol has a function definition and/or a variable definition, but
@c those are irrelevant to the use of the symbol that you are documenting,
@c you can write the word @samp{symbol} before the symbol name to prevent
@c making any hyperlink.  For example,
$B%7%s%\%k$K4X?tDj5A$dJQ?tDj5A$,$"$C$F$b!"(B
$B@bL@J8;zNs$G$N%7%s%\%k$N;H$$J}$K$OL54X78$J>l9g$K$O!"(B
$B%7%s%\%k$NL>A0$N$^$($KC18l(B@samp{symbol}$B$r=q$1$P!"(B
$B%O%$%Q!<%j%s%/$r:n$i$J$$$h$&$K$G$-$k!#(B
$B$?$H$($P!"$D$.$N$h$&$K$9$k$H!"(B

@example
If the argument KIND-OF-RESULT is the symbol `list',
this function returns a list of all the objects
that satisfy the criterion.
@end example

@noindent
@c does not make a hyperlink to the documentation, irrelevant here, of the
@c function @code{list}.
$B$3$3$G$O(B@code{list}$B$N4X?t!?JQ?tDj5A$OL54X78$J$N$G!"(B
$B4X?t(B@code{list}$B$N@bL@J8;zNs$r;X$9%O%$%Q!<%j%s%/$O:n$i$l$J$$!#(B

@item
@c Don't write key sequences directly in documentation strings.  Instead,
@c use the @samp{\\[@dots{}]} construct to stand for them.  For example,
@c instead of writing @samp{C-f}, write the construct
@c @samp{\\[forward-char]}.  When Emacs displays the documentation string,
@c it substitutes whatever key is currently bound to @code{forward-char}.
@c (This is normally @samp{C-f}, but it may be some other character if the
@c user has moved key bindings.)  @xref{Keys in Documentation}.
$B@bL@J8;zNs$KD>@\%-!<Ns$r=q$-9~$^$J$$$3$H!#(B
$B$=$N$+$o$j$K!"$=$l$NI8=`E*$J%-!<Ns$r:n@.$9$k(B
@samp{\\[@dots{}]}$B$N=q$-J}$r;H$&!#(B
$B$?$H$($P!"(B@samp{C-f}$B$H=q$/$+$o$j$K!"(B@samp{\\[forward-char]}$B$H=q$/!#(B
Emacs$B$,@bL@J8;zNs$rI=<($9$k$H$-$K!"(B
@code{forward-char}$B$K8=:_%P%$%s%I$5$l$F$$$k%-!<$K(BEmacs$B$,CV$-49$($k!#(B
$B!JIaDL$O(B@samp{C-f}$B$G$"$k$,!"%f!<%6!<$,%-!<%P%$%s%G%#%s%0$rJQ99$7$F$$$l$P!"(B
$BJL$NJ8;z$K$J$k!#!K(B
@pxref{Keys in Documentation}$B!#(B

@item
@c In documentation strings for a major mode, you will want to refer to the
@c key bindings of that mode's local map, rather than global ones.
@c Therefore, use the construct @samp{\\<@dots{}>} once in the
@c documentation string to specify which key map to use.  Do this before
@c the first use of @samp{\\[@dots{}]}.  The text inside the
@c @samp{\\<@dots{}>} should be the name of the variable containing the
@c local keymap for the major mode.
$B%a%8%c!<%b!<%I$N@bL@J8;zNs$G$O!"(B
$B%0%m!<%P%k$J%-!<%^%C%W$G$O$J$/$=$N%b!<%I$N%m!<%+%k$J%-!<%^%C%W$G$N(B
$B%-!<%P%$%s%G%#%s%0$r;2>H$7$?$$$@$m$&!#(B
$B$=$l$K$O!";HMQ$9$k%-!<%^%C%W$r;XDj$9$k9=J8(B@samp{\\<@dots{}>}$B$r(B
$B@bL@J8;zNs$NCf$K=q$/!#(B
$B:G=i$K(B@samp{\\[@dots{}]}$B$r;H$&$^$($K$3$&$7$F$*$/$3$H!#(B
@samp{\\<@dots{}>}$B$NFbB&$N%F%-%9%H$O!"(B
$B%a%8%c!<%b!<%I8~$1$N%m!<%+%k%-!<%^%C%W$rJ];}$9$kJQ?t$NL>A0$G$"$k$3$H!#(B

@c It is not practical to use @samp{\\[@dots{}]} very many times, because
@c display of the documentation string will become slow.  So use this to
@c describe the most important commands in your major mode, and then use
@c @samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
$B@bL@J8;zNs$NI=<($rCY$/$7$F$7$^$&$N$G!"(B
@samp{\\[@dots{}]}$B$r2?2s$b;H$&$N$O<BMQE*$G$O$J$$!#(B
$B$7$?$,$C$F!"FI<T$N%a%8%c!<%b!<%I$N$b$C$H$b=EMW$J%3%^%s%I$N5-=R$K$3$l$r;H$$!"(B
$B%b!<%I$N%-!<%^%C%W$N;D$j$rI=<($9$k$K$O(B@samp{\\@{@dots{}@}}$B$r;H$&!#(B
@end itemize

@node Comment Tips
@c @section Tips on Writing Comments
@section $B%3%a%s%H$N=q$-J}$N%R%s%H(B

@c   We recommend these conventions for where to put comments and how to
@c indent them:
$B%3%a%s%H$rCV$/>l=j$H$=$l$i$N;z2<$2J}K!$K$D$$$F$O0J2<$N$h$&$J47=,$r?d>)$7$^$9!#(B

@table @samp
@item ;
@c Comments that start with a single semicolon, @samp{;}, should all be
@c aligned to the same column on the right of the source code.  Such
@c comments usually explain how the code on the same line does its job.  In
@c Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment})
@c command automatically inserts such a @samp{;} in the right place, or
@c aligns such a comment if it is already present.
1$B$D$N%;%_%3%m%s(B@samp{;}$B$G;O$^$k%3%a%s%H$O!"(B
$B%=!<%9%3!<%I$N1&B&$GF1$8%3%i%`0LCV$KB7$($k$3$H!#(B
$B$=$N$h$&$J%3%a%s%H$O!"$=$N9T$N%3!<%I$NF0:n$r@bL@$9$k!#(B
lisp$B%b!<%I$d$=$N4XO"$9$k%b!<%I$G$O!"(B
$B%3%^%s%I(B@kbd{M-;}$B!J(B@code{indent-for-comment}$B!K$G(B
$B<+F0E*$K1&B&$N@5$7$$0LCV$K(B@samp{;}$B$rA^F~$7$?$j!"(B
$B$=$N$h$&$J%3%a%s%H$,4{B8$J$i$P@0Ns$G$-$k!#(B

@c This and following examples are taken from the Emacs sources.
$B$D$.$H$=$N2<$NNc$O!"(BEmacs$B$N%=!<%9$+$i;}$C$F$-$?$b$N$G$"$k!#(B

@smallexample
@group
(setq base-version-list                 ; there was a base
      (assoc (substring fn 0 start-vn)  ; version to which
             file-version-assoc-list))  ; this looks like
                                        ; a subversion
@end group
@end smallexample

@item ;;
@c Comments that start with two semicolons, @samp{;;}, should be aligned to
@c the same level of indentation as the code.  Such comments usually
@c describe the purpose of the following lines or the state of the program
@c at that point.  For example:
2$B$D$N%;%_%3%m%s(B@samp{;;}$B$G;O$^$k%3%a%s%H$O!"(B
$B$=$NItJ,$N%3!<%I$N;z2<$2$KB7$($k$3$H!#(B
$B$=$N$h$&$J%3%a%s%H$O!"$=$N8eB3$N9T$NL\E*$d(B
$B$=$N2U=j$G$N%W%m%0%i%`$N>uBV$r5-=R$9$k!#(B

@smallexample
@group
(prog1 (setq auto-fill-function
             @dots{}
             @dots{}
  ;; update mode line
  (force-mode-line-update)))
@end group
@end smallexample

@c Every function that has no documentation string (presumably one that is
@c used only internally within the package it belongs to), should have
@c instead a two-semicolon comment right before the function, explaining
@c what the function does and how to call it properly.  Explain precisely
@c what each argument means and how the function interprets its possible
@c values.
$B@bL@J8;zNs$r;}$?$J$$3F4X?t(B
$B!J=jB0$9$k%Q%C%1!<%8$GFbIt8~$1$K$N$_;HMQ$5$l$k4X?t!K$G$O!"(B
$B4X?t$,9T$&$3$H$H@5$7$$8F$S=P$7J}$r5-=R$7$?(B
2$B$D$N%;%_%3%m%s$G;O$^$k%3%a%s%H$r4X?t$N$^$($K=q$/$3$H!#(B
$B3F0z?t$N0UL#$H$=$N2DG=$JCM$r4X?t$,$I$N$h$&$K2r<a$9$k$+$r@53N$K@bL@$9$k$3$H!#(B

@item ;;;
@c Comments that start with three semicolons, @samp{;;;}, should start at
@c the left margin.  Such comments are used outside function definitions to
@c make general statements explaining the design principles of the program.
@c For example:
3$B$D$N%;%_%3%m%s(B@samp{;;;}$B$G;O$^$k%3%a%s%H$O!":8C<$KB7$($k$3$H!#(B
$B$=$N$h$&$J%3%a%s%H$O!"4X?tDj5A$N30B&$G;H$$!"(B
$B%W%m%0%i%`$N@_7W86M}$r@bL@$9$k0lHLE*$JI=L@$G$"$k!#(B
$B$?$H$($P$D$.$N$H$*$j!#(B

@smallexample
@group
;;; This Lisp code is run in Emacs
;;; when it is to operate as a server
;;; for other processes.
@end group
@end smallexample

@c Another use for triple-semicolon comments is for commenting out lines
@c within a function.  We use triple-semicolons for this precisely so that
@c they remain at the left margin.
3$B$D$N%;%_%3%m%s$G;O$^$k%3%a%s%H$NJL$N;H$$J}$O!"(B
$B4X?tFb$N9T$r%3%a%s%H$K$9$k>l9g$G$"$k!#(B
$B$=$N$h$&$J9T$,:8C<$KN1$^$k$h$&$K(B3$B$D$N%;%_%3%m%s$r;H$&$N$G$"$k!#(B

@smallexample
(defun foo (a)
;;; This is no longer necessary.
;;;  (force-mode-line-update)
  (message "Finished with %s" a))
@end smallexample

@item ;;;;
@c Comments that start with four semicolons, @samp{;;;;}, should be aligned
@c to the left margin and are used for headings of major sections of a
@c program.  For example:
4$B$D$N%;%_%3%m%s(B@samp{;;;;}$B$G;O$^$k%3%a%s%H$O!"(B
$B:8C<$KB7$($F!"%W%m%0%i%`$N<gMW$JItJ,$N%X%C%@$K;H$&!#(B
$B$?$H$($P$D$.$N$H$*$j!#(B

@smallexample
;;;; The kill ring
@end smallexample
@end table

@noindent
@c The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;}
@c (@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}),
@c automatically indent comments according to these conventions,
@c depending on the number of semicolons.  @xref{Comments,,
@c Manipulating Comments, emacs, The GNU Emacs Manual}.
@kbd{M-;}$B!J(B@code{indent-for-comment}$B!K$d(B
@key{TAB}$B!J(B@code{lisp-indent-line}$B!K$J$I$N(B
Emacs$B$N(Blisp$B%b!<%I$N;z2<$2%3%^%s%I$O!"(B
$B$3$l$i$N47=,$K$7$?$,$C$F<+F0E*$K%3%a%s%H$r;z2<$2$7$^$9!#(B
@xref{Comments,, $B%3%a%s%H$NA`:n(B, emacs, GNU Emacs $B%^%K%e%"%k(B}$B!#(B

@node Library Headers
@c @section Conventional Headers for Emacs Libraries
@section Emacs$B%i%$%V%i%j$N%X%C%@$N47=,(B
@c @cindex header comments
@c @cindex library header comments
@cindex $B%X%C%@%3%a%s%H(B
@cindex $B%i%$%V%i%j%X%C%@%3%a%s%H(B

@c   Emacs has conventions for using special comments in Lisp libraries
@c to divide them into sections and give information such as who wrote
@c them.  This section explains these conventions.  First, an example:
Emacs$B$K$O!"%3%a%s%H$r$$$/$D$+$NItJ,$KJ,$1$F:n<T$J$I$N>pJs$rM?$($k$?$a$K!"(B
Lisp$B%i%$%V%i%j$NFCJL$J%3%a%s%H$KBP$9$k47=,$,$"$j$^$9!#(B
$BK\@a$G$O$=$l$i$N47=,$K$D$$$F=R$Y$^$9!#(B
$B$^$:!"Nc$r<($7$^$9!#(B

@smallexample
@group
;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers

;; Copyright (C) 1992 Free Software Foundation, Inc.
@end group

;; Author: Eric S. Raymond <esr@@snark.thyrsus.com>
;; Maintainer: Eric S. Raymond <esr@@snark.thyrsus.com>
;; Created: 14 Jul 1992
;; Version: 1.2
@group
;; Keywords: docs

;; This file is part of GNU Emacs.
@dots{}
;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.
@end group
@end smallexample

@c   The very first line should have this format:
$B:G=i$N9T$O$D$.$N7A<0$G$"$k$Y$-$G$9!#(B

@example
;;; @var{filename} --- @var{description}
@end example

@noindent
@c The description should be complete in one line.
$B$3$N5-=R$O(B1$B9T$G40A4$K$J$k$h$&$K$7$^$9!#(B

@c   After the copyright notice come several @dfn{header comment} lines,
@c each beginning with @samp{;; @var{header-name}:}.  Here is a table of
@c the conventional possibilities for @var{header-name}:
$BCx:n8"I=<($N$"$H$K$O!"(B@samp{;; @var{header-name}:}$B$G;O$^$k(B
$B$$$/$D$+$N(B@dfn{$B%X%C%@%3%a%s%H(B}$B!J(Bheader comment$B!K9T$,B3$-$^$9!#(B
@var{header-name}$B$K;H$&2DG=@-$N$"$k47=,$N0lMw$r0J2<$K<($7$^$9!#(B

@table @samp
@item Author
@c This line states the name and net address of at least the principal
@c author of the library.
$B$3$N9T$G$O!">/$J$/$H$b%i%$%V%i%j$N<g:n<T$N(B
$B;aL>$H%M%C%H%o!<%/%"%I%l%9$rL@5-$9$k!#(B

@c If there are multiple authors, you can list them on continuation lines
@c led by @code{;;} and a tab character, like this:
$BJ#?t$N:n<T$,$$$k>l9g$K$O!"0J2<$N$h$&$K!"(B
@code{;;}$B$H%?%VJ8;z$G;O$a$?7QB39T$K(B
$B$=$N?MC#$rNs5s$9$k!#(B

@smallexample
@group
;; Author: Ashwin Ram <Ram-Ashwin@@cs.yale.edu>
;;      Dave Sill <de5@@ornl.gov>
;;      Dave Brennan <brennan@@hal.com>
;;      Eric Raymond <esr@@snark.thyrsus.com>
@end group
@end smallexample

@item Maintainer
@c This line should contain a single name/address as in the Author line, or
@c an address only, or the string @samp{FSF}.  If there is no maintainer
@c line, the person(s) in the Author field are presumed to be the
@c maintainers.  The example above is mildly bogus because the maintainer
@c line is redundant.
$B$3$N9T$K$O!":n<T9T!J(B@samp{Author}$B!K$N$h$&$K(B1$B?M$N;aL>$H%"%I%l%9!"(B
$B%"%I%l%9$N$_!"J8;zNs(B@samp{FSF}$B$N$$$:$l$+$r=q$/!#(B
$BJ]<i<T9T!J(B@samp{Maintainer}$B!K$,$J$$>l9g$K$O!"(B
$B:n<T9T$N?MC#$,J]<i$7$F$$$k$H2>Dj$9$k!#(B
$B>e$NNc$O!"J]<i<T9T$,>iD9$G$"$j!">/!9$$$s$A$-$G$"$k!#(B

@c The idea behind the @samp{Author} and @samp{Maintainer} lines is to make
@c possible a Lisp function to ``send mail to the maintainer'' without
@c having to mine the name out by hand.
$B:n<T9T!J(B@samp{Author}$B!K$HJ]<i<T9T!J(B@samp{Maintainer}$B!K$N9M$($O!"(B
$B<j:n6H$GL>A0$rC5$5$:$K!XJ]<i<T$K%a%$%k$rAw$k!Y$h$&$J(BLisp$B4X?t$r(B
$B:n$l$k$h$&$K$9$k$?$a$G$"$k!#(B

@c Be sure to surround the network address with @samp{<@dots{}>} if
@c you include the person's full name as well as the network address.
$B%M%C%H%o!<%/%"%I%l%9$K2C$($F?M$N;aL>$b=q$/>l9g$K$O!"(B
$B%M%C%H%o!<%/%"%I%l%9$r(B@samp{<@dots{}>}$B$GI,$:0O$`$3$H!#(B

@item Created
@c This optional line gives the original creation date of the
@c file.  For historical interest only.
$B$3$N9T$O>JN,$G$-$k$,!"%U%!%$%k$N:n@.F|;~$r=q$/!#(B
$BNr;KE*$J0UL#$@$1$G$"$k!#(B

@item Version
@c If you wish to record version numbers for the individual Lisp program, put
@c them in this line.
$B3F(BLisp$B%W%m%0%i%`$NHGHV9f$r5-O?$7$F$*$-$?$$>l9g$K!"(B
$B$3$N9T$KHGHV9f$r=q$/!#(B

@item Adapted-By
@c In this header line, place the name of the person who adapted the
@c library for installation (to make it fit the style conventions, for
@c example).
$B$3$N%X%C%@9T$G$O!"!J$?$H$($P!"%9%?%$%k$N47=,$KE,9g$9$k$h$&$KJQ99$7$?$J$I$N!K(B
$B%$%s%9%H!<%k$N$?$a$K%i%$%V%i%j$r<uM}$7$??M$NL>A0$r=q$/!#(B

@item Keywords
@c This line lists keywords for the @code{finder-by-keyword} help command.
@c Please use that command to see a list of the meaningful keywords.
$B$3$N9T$K$O!"%X%k%W%3%^%s%I(B@code{finder-by-keyword}$B8~$1$N(B
$B%-!<%o!<%I$r=q$/!#(B
$B0UL#$N$"$k%-!<%o!<%I$rM}2r$9$k$?$a$K$3$N%3%^%s%I$r;n$7$F$[$7$$!#(B

@c This field is important; it's how people will find your package when
@c they're looking for things by topic area.  To separate the keywords, you
@c can use spaces, commas, or both.
$B$3$NItJ,$O=EMW$G$"$k!#(B
$B?M!9$,FCDj$NOCBj$GC5$7$FFI<T$N%Q%C%1!<%8$r$_$D$1$k$G$"$m$&!#(B
$B%-!<%o!<%I$O6uGr$d%+%s%^$G6h@Z$k!#(B
@end table

@c   Just about every Lisp library ought to have the @samp{Author} and
@c @samp{Keywords} header comment lines.  Use the others if they are
@c appropriate.  You can also put in header lines with other header
@c names---they have no standard meanings, so they can't do any harm.
$B$[$H$s$I$N(BLisp$B%i%$%V%i%j$K$O!"(B
@samp{Author}$B$H(B@samp{Keywords}$B$N%X%C%@%3%a%s%H9T$,I,MW$G$9!#(B
$B;D$j$N$b$N$OI,MW$K1~$8$F;H$$$^$9!#(B
$BJL$NL>A0$N%X%C%@9T$,$"$C$F$b$+$^$$$^$;$s!#(B
$B$=$l$i$K$OI8=`E*$J0UL#$O$"$j$^$;$s$,!"32$K$J$k$3$H$b$"$j$^$;$s!#(B

@c   We use additional stylized comments to subdivide the contents of the
@c library file.  Here is a table of them:
$B%i%$%V%i%j%U%!%$%k$NFbMF$rJ,3d$9$k$?$a$K7A<0$rDj$a$?%3%a%s%H$b;H$$$^$9!#(B
$B$=$l$i$r0J2<$K<($7$^$9!#(B

@table @samp
@item ;;; Commentary:
@c This begins introductory comments that explain how the library works.
@c It should come right after the copying permissions, terminated by a
@c @samp{Change Log}, @samp{History} or @samp{Code} comment line.  This
@c text is used by the Finder package, so it should make sense in that
@c context.
$B%i%$%V%i%j$NF0:n$r@bL@$9$kF~LgE*$J%3%a%s%H$r;O$a$k!#(B
$BCx:n8"I=<($ND>8e$K$-$F!"(B
@samp{Change Log}$B!"(B@samp{History}$B!"(B@samp{Code}$B$N$$$:$l$+$N%3%a%s%H9T$G=*$k!#(B
$B$3$N%F%-%9%H$O%Q%C%1!<%8(Bfinder$B$,;H$&$N$G!"(B
$B$=$NJ8L.$G0UL#$,$"$k$h$&$K$9$k$3$H!#(B

@item ;;; Documentation
@c This has been used in some files in place of @samp{;;; Commentary:},
@c but @samp{;;; Commentary:} is preferred.
@samp{;;; Commentary:}$B$N$+$o$j$K;H$C$F$$$k%U%!%$%k$b$"$k$,!"(B
@samp{;;; Commentary:}$B$N$[$&$,9%$^$7$$!#(B

@item ;;; Change Log:
@c This begins change log information stored in the library file (if you
@c store the change history there).  For most of the Lisp
@c files distributed with Emacs, the change history is kept in the file
@c @file{ChangeLog} and not in the source file at all; these files do
@c not have a @samp{;;; Change Log:} line.
$B!JJQ99MzNr$r%i%$%V%i%j$K<}$a$k>l9g$N!K(B
$B%i%$%V%i%j%U%!%$%k$K<}$a$?JQ995-O?>pJs$r;O$a$k!#(B
Emacs$B$GG[I[$5$l$k$[$H$s$I$N(BLisp$B%U%!%$%k$G$O!"(B
$BJQ99MzNr$O%U%!%$%k(B@file{ChangeLog}$B$K<}$a$F$"$j!"(B
$B%=!<%9%U%!%$%k$K$O<}$a$J$$!#(B
$B$=$l$i$N%U%!%$%k$K$O(B@samp{;;; Change Log:}$B9T$O$J$$!#(B

@item ;;; Code:
@c This begins the actual code of the program.
$B%W%m%0%i%`$N<B:]$N%3!<%I$r;O$a$k!#(B

@item ;;; @var{filename} ends here
@c This is the @dfn{footer line}; it appears at the very end of the file.
@c Its purpose is to enable people to detect truncated versions of the file
@c from the lack of a footer line.
$B$3$l$O(B@dfn{$B:G=*9T(B}$B!J(Bfooter line$B!K$G$"$j!"%U%!%$%k$NKvHx$K8=$l$k!#(B
$B$=$NL\E*$O!":G=*9T$,7gG!$7$F$$$k$3$H$G%U%!%$%k$,@Z$j5M$a$i$l$F$$$k$3$H$,(B
$B$o$+$k$h$&$K$9$k$N$G$"$k!#(B
@end table