X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/00d96ada16d262d18da4dfaa23afb2b29d1a80c4..2bcdf6628b2e67d770605f1e37c25a2533e9460b:/lispref/tips.texi diff --git a/lispref/tips.texi b/lispref/tips.texi index 9c25274823..3f42800951 100644 --- a/lispref/tips.texi +++ b/lispref/tips.texi @@ -1,31 +1,39 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998, 1999 +@c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/tips -@node Tips, GNU Emacs Internals, Calendar, Top -@appendix Tips and Standards +@node Tips, GNU Emacs Internals, GPL, Top +@appendix Tips and Conventions @cindex tips @cindex standards of coding style @cindex coding standards - This chapter describes no additional features of Emacs Lisp. -Instead it gives advice on making effective use of the features described -in the previous chapters. + This chapter describes no additional features of Emacs Lisp. Instead +it gives advice on making effective use of the features described in the +previous chapters, and describes conventions Emacs Lisp programmers +should follow. + + You can automatically check some of the conventions described below by +running the command @kbd{M-x checkdoc RET} when visiting a Lisp file. +It cannot check all of the conventions, and not all the warnings it +gives necessarily correspond to problems, but it is worth examining them +all. @menu -* Style Tips:: Writing clean and robust programs. +* 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 Style Tips -@section Writing Clean Lisp Programs +@node Coding Conventions +@section Emacs Lisp Coding Conventions - Here are some tips for avoiding common errors in writing Lisp code -intended for widespread use: + Here are conventions that you should follow when writing Emacs Lisp +code intended for widespread use: @itemize @bullet @item @@ -36,15 +44,16 @@ names of all global variables, constants, and functions with the chosen prefix. This helps avoid name conflicts. This recommendation applies even to names for traditional Lisp -primitives that are not primitives in Emacs Lisp---even to @code{cadr}. -Believe it or not, there is more than one plausible way to define -@code{cadr}. Play it safe; append your name prefix to produce a name -like @code{foo-cadr} or @code{mylib-cadr} instead. +primitives that are not primitives in Emacs Lisp---even to +@code{copy-list}. Believe it or not, there is more than one plausible +way to define @code{copy-list}. Play it safe; append your name prefix +to produce a name like @code{foo-copy-list} or @code{mylib-copy-list} +instead. If you write a function that you think ought to be added to Emacs under a certain name, such as @code{twiddle-files}, don't call it by that name in your program. Call it @code{mylib-twiddle-files} in your program, -and send mail to @samp{bug-gnu-emacs@@prep.ai.mit.edu} suggesting we add +and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add it to Emacs. If and when we do, we can change the name easily enough. If one prefix is insufficient, your package may use two or three @@ -59,19 +68,50 @@ It is often useful to put a call to @code{provide} in each separate library program, at least if there is more than one entry point to the program. +@item +If a file requires certain other library programs to be loaded +beforehand, then the comments at the beginning of the file should say +so. Also, use @code{require} to make sure they are loaded. + @item If one file @var{foo} uses a macro defined in another file @var{bar}, -@var{foo} should contain @code{(require '@var{bar})} before the first -use of the macro. (And @var{bar} should contain @code{(provide -'@var{bar})}, to make the @code{require} work.) This will cause -@var{bar} to be loaded when you byte-compile @var{foo}. Otherwise, you -risk compiling @var{foo} without the necessary macro loaded, and that -would produce compiled code that won't work right. @xref{Compiling -Macros}. +@var{foo} should contain this expression before the first use of the +macro: + +@example +(eval-when-compile (require '@var{bar})) +@end example + +@noindent +(And the library @var{bar} should contain @code{(provide '@var{bar})}, +to make the @code{require} work.) This will cause @var{bar} to be +loaded when you byte-compile @var{foo}. Otherwise, you risk compiling +@var{foo} without the necessary macro loaded, and that would produce +compiled code that won't work right. @xref{Compiling Macros}. + +Using @code{eval-when-compile} avoids loading @var{bar} when +the compiled version of @var{foo} is @emph{used}. @item -If you define a major mode, make sure to run a hook variable using -@code{run-hooks}, just as the existing major modes do. @xref{Hooks}. +Please don't require the @code{cl} package of Common Lisp extensions at +run time. Use of this package is optional, and it is not part of the +standard Emacs namespace. If your package loads @code{cl} at run time, +that could cause name clashes for users who don't use that package. + +However, there is no problem with using the @code{cl} package at compile +time, for the sake of macros. You do that like this: + +@example +(eval-when-compile (require 'cl)) +@end example + +@item +When defining a major mode, please follow the major mode +conventions. @xref{Major Mode Conventions}. + +@item +When defining a minor mode, please follow the minor mode +conventions. @xref{Minor Mode Conventions}. @item If the purpose of a function is to tell you whether a certain condition @@ -84,17 +124,19 @@ If a user option variable records a true-or-false condition, give it a name that ends in @samp{-flag}. @item +@cindex reserved keys +@cindex keys, reserved Please do not define @kbd{C-c @var{letter}} as a key in your major modes. These sequences are reserved for users; they are the -@strong{only} sequences reserved for users, so we cannot do without -them. +@strong{only} sequences reserved for users, so do not block them. -Instead, define sequences consisting of @kbd{C-c} followed by a -non-letter. These sequences are reserved for major modes. +Instead, define sequences consisting of @kbd{C-c} followed by a control +character, a digit, or certain punctuation characters. These sequences +are reserved for major modes. -Changing all the major modes in Emacs 18 so they would follow this -convention was a lot of work. Abandoning this convention would make -that work go to waste, and inconvenience users. +Changing all the Emacs major modes to follow this convention was a lot +of work. Abandoning this convention would make that work go to waste, +and inconvenience users. @item Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}}, @@ -107,19 +149,36 @@ not absolutely prohibited, but if you do that, the major mode binding may be shadowed from time to time by minor modes. @item -You should not bind @kbd{C-h} following any prefix character (including +Function keys @key{F5} through @key{F9} without modifier keys are +reserved for users to define. + +@item +Do not bind @kbd{C-h} following any prefix character (including @kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically available as a help character for listing the subcommands of the prefix character. @item -You should not bind a key sequence ending in @key{ESC} except following -another @key{ESC}. (That is, it is ok to bind a sequence ending in +Do not bind a key sequence ending in @key{ESC} except following +another @key{ESC}. (That is, it is OK to bind a sequence ending in @kbd{@key{ESC} @key{ESC}}.) The reason for this rule is that a non-prefix binding for @key{ESC} in any context prevents recognition of escape sequences as function keys in that context. +@item +Anything which acts like a temporary mode or state which the user can +enter and leave should define @kbd{@key{ESC} @key{ESC}} or +@kbd{@key{ESC} @key{ESC} @key{ESC}} as a way to escape. + +For a state which accepts ordinary Emacs commands, or more generally any +kind of state in which @key{ESC} followed by a function key or arrow key +is potentially meaningful, then you must not define @kbd{@key{ESC} +@key{ESC}}, since that would preclude recognizing an escape sequence +after @key{ESC}. In these states, you should define @kbd{@key{ESC} +@key{ESC} @key{ESC}} as the way to escape. Otherwise, define +@kbd{@key{ESC} @key{ESC}} instead. + @item Applications should not bind mouse events based on button 1 with the shift key held down. These events include @kbd{S-mouse-1}, @@ -127,10 +186,10 @@ shift key held down. These events include @kbd{S-mouse-1}, users. @item -Modes should redefine @kbd{mouse-2} as a command to follow some sort of -reference in the text of a buffer, if users usually would not want to -alter the text in that buffer by hand. Modes such as Dired, Info, -Compilation, and Occur redefine it in this way. +Special major modes used for read-only text should usually redefine +@kbd{mouse-2} and @key{RET} to trace some sort of reference in the text. +Modes such as Dired, Info, Compilation, and Occur redefine it in this +way. @item When a package provides a modification of ordinary Emacs behavior, it is @@ -145,9 +204,9 @@ It is a bad idea to define aliases for the Emacs primitives. Use the standard names instead. @item -Redefining an Emacs primitive is an even worse idea. -It may do the right thing for a particular program, but -there is no telling what other programs might break as a result. +Redefining (or advising) an Emacs primitive is discouraged. It may do +the right thing for a particular program, but there is no telling what +other programs might break as a result. @item If a file does replace any of the functions or library programs of @@ -155,11 +214,6 @@ standard Emacs, prominent comments at the beginning of the file should say which functions are replaced, and how the behavior of the replacements differs from that of the originals. -@item -If a file requires certain standard library programs to be loaded -beforehand, then the comments at the beginning of the file should say -so. - @item Please keep the names of your Emacs Lisp source files to 13 characters or less. This way, if the files are compiled, the compiled files' names @@ -177,7 +231,7 @@ of the intended features of your program. The mark is a user-level feature, so it is incorrect to change the mark except to supply a value for the user's benefit. @xref{The Mark}. -In particular, don't use these functions: +In particular, don't use any of these functions: @itemize @bullet @item @@ -211,6 +265,17 @@ When you encounter an error condition, call the function @code{error} Do not use @code{message}, @code{throw}, @code{sleep-for}, or @code{beep} to report errors. +@item +An error message should start with a capital letter but should not end +with a period. + +@item +Many commands that take a long time to execute display a message that +says @samp{Operating...} when they start, and change it to +@samp{Operating...done} when they finish. Please keep the style of +these messages uniform: @emph{no} space around the ellipsis, and +@emph{no} period at the end. + @item Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e} command does: use a new local keymap that contains one command defined @@ -222,9 +287,31 @@ user switch back at will. @xref{Recursive Editing}. In some other systems there is a convention of choosing variable names that begin and end with @samp{*}. We don't use that convention in Emacs Lisp, so please don't use it in your programs. (Emacs uses such names -only for program-generated buffers.) The users will find Emacs more +only for special-purpose buffers.) The users will find Emacs more coherent if all libraries use the same conventions. +@item +Try to avoid compiler warnings about undefined free variables, by adding +@code{defvar} definitions for these variables. + +Sometimes adding a @code{require} for another package is useful to avoid +compilation warnings for variables and functions defined in that +package. If you do this, often it is better if the @code{require} acts +only at compile time. Here's how to do that: + +@example +(eval-when-compile + (require 'foo) + (defvar bar-baz)) +@end example + +If you bind a variable in one function, and use it or set it in another +function, the compiler warns about the latter function unless the +variable has a definition. But often these variables have short names, +and it is not clean for Lisp packages to define such variable names. +Therefore, you should rename the variable to start with the name prefix +used for the other functions and variables in your package. + @item Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the default indentation parameters. @@ -233,14 +320,34 @@ default indentation parameters. Don't make a habit of putting close-parentheses on lines by themselves; Lisp programmers find this disconcerting. Once in a while, when there is a sequence of many consecutive close-parentheses, it may make sense -to split them in one or two significant places. +to split the sequence in one or two significant places. @item Please put a copyright notice on the file if you give copies to anyone. -Use the same lines that appear at the top of the Lisp files in Emacs -itself. If you have not signed papers to assign the copyright to the -Foundation, then place your name in the copyright notice in place of the -Foundation's name. +Use a message like this one: + +@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 + +If you have signed papers to assign the copyright to the Foundation, +then use @samp{Free Software Foundation, Inc.} as @var{name}. +Otherwise, use your name. @end itemize @node Compilation Tips @@ -256,8 +363,10 @@ Lisp programs. @cindex profiling @cindex timing programs @cindex @file{profile.el} -Use the @file{profile} library to profile your program. See the file -@file{profile.el} for instructions. +@cindex @file{elp.el} +Profile your program with the @file{profile} library or the @file{elp} +library. See the files @file{profile.el} and @file{elp.el} for +instructions. @item Use iteration rather than recursion whenever possible. @@ -265,10 +374,10 @@ Function calls are slow in Emacs Lisp even when a compiled function is calling another compiled function. @item -Using the primitive list-searching functions @code{memq}, @code{assq}, or -@code{assoc} is even faster than explicit iteration. It may be worth -rearranging a data structure so that one of these primitive search -functions can be used. +Using the primitive list-searching functions @code{memq}, @code{member}, +@code{assq}, or @code{assoc} is even faster than explicit iteration. It +can be worth rearranging a data structure so that one of these primitive +search functions can be used. @item Certain built-in functions are handled specially in byte-compiled code, @@ -279,23 +388,17 @@ property. If the property is non-@code{nil}, then the function is handled specially. For example, the following input will show you that @code{aref} is -compiled specially (@pxref{Array Functions}) while @code{elt} is not -(@pxref{Sequence Functions}): +compiled specially (@pxref{Array Functions}): @example @group (get 'aref 'byte-compile) @result{} byte-compile-two-args @end group - -@group -(get 'elt 'byte-compile) - @result{} nil -@end group @end example @item -If calling a small function accounts for a substantial part of your +If calling a small function accounts for a substantial part of your program's running time, make the function inline. This eliminates the function call overhead. Since making a function inline reduces the flexibility of changing the program, don't do it unless it gives @@ -306,7 +409,10 @@ the speed. @xref{Inline Functions}. @node Documentation Tips @section Tips for Documentation Strings - Here are some tips for the writing of documentation strings. +@findex checkdoc-minor-mode + Here are some tips and conventions for the writing of documentation +strings. You can check many of these conventions by running the command +@kbd{M-x checkdoc-minor-mode}. @itemize @bullet @item @@ -317,27 +423,27 @@ should have a documentation string. An internal variable or subroutine of a Lisp program might as well have a documentation string. In earlier Emacs versions, you could save space by using a comment instead of a documentation string, but that is no -longer the case. +longer the case---documentation strings now take up very little space in +a running Emacs. @item The first line of the documentation string should consist of one or two complete sentences that stand on their own as a summary. @kbd{M-x -apropos} displays just the first line, and if it doesn't stand on its -own, the result looks bad. In particular, start the first line with a -capital letter and end with a period. +apropos} displays just the first line, and if that line's contents don't +stand on their own, the result looks bad. In particular, start the +first line with a capital letter and end with a period. -The documentation string can have additional lines that expand on the -details of how to use the function or variable. The additional lines -should be made up of complete sentences also, but they may be filled if -that looks good. +The documentation string is not limited to one line; use as many lines +as you need to explain the details of how to use the function or +variable. Please use complete sentences in the additional lines. @item -For consistency, phrase the verb in the first sentence of a -documentation string as an infinitive with ``to'' omitted. For -instance, use ``Return the cons of A and B.'' in preference to ``Returns -the cons of A and B@.'' Usually it looks good to do likewise for the -rest of the first paragraph. Subsequent paragraphs usually look better -if they have proper subjects. +For consistency, phrase the verb in the first sentence of a function's +documentation string as an imperative--for instance, use ``Return the +cons of A and B.'' in preference to ``Returns the cons of A and B@.'' +Usually it looks good to do likewise for the rest of the first +paragraph. Subsequent paragraphs usually look better if each sentence +has a proper subject. @item Write documentation strings in the active voice, not the passive, and in @@ -350,18 +456,28 @@ Avoid using the word ``cause'' (or its equivalents) unnecessarily. Instead of, ``Cause Emacs to display text in boldface,'' write just ``Display text in boldface.'' +@item +When a command is meaningful only in a certain mode or situation, +do mention that in the documentation string. For example, +the documentation of @code{dired-find-file} is: + +@example +In Dired, visit the file or directory named on this line. +@end example + @item Do not start or end a documentation string with whitespace. @item Format the documentation string so that it fits in an Emacs window on an 80-column screen. It is a good idea for most lines to be no wider than -60 characters. The first line can be wider if necessary to fit the -information that ought to be there. +60 characters. The first line should not be wider than 67 characters +or it will look bad in the output of @code{apropos}. -However, rather than simply filling the entire documentation string, you -can make it much more readable by choosing line breaks with care. -Use blank lines between topics if the documentation string is long. +You can fill the text if that looks good. However, rather than blindly +filling the entire documentation string, you can often make it much more +readable by choosing certain line breaks with care. Use blank lines +between topics if the documentation string is long. @item @strong{Do not} indent subsequent lines of a documentation string so @@ -370,6 +486,12 @@ line. This looks nice in the source code, but looks bizarre when users view the documentation. Remember that the indentation before the starting double-quote is not part of the string! +@item +When the user tries to use a disabled command, Emacs displays just the +first paragraph of its documentation string---everything through the +first blank line. If you wish, you can choose which information to +include before the first blank line so as to make this display useful. + @item A variable's documentation string should start with @samp{*} if the variable is one that users would often want to set interactively. If @@ -387,12 +509,34 @@ all non-@code{nil} values are equivalent and indicate explicitly what When a function's documentation string mentions the value of an argument of the function, use the argument name in capital letters as if it were a name for that value. Thus, the documentation string of the function -@code{/} refers to its second argument as @samp{DIVISOR}, because the -actual argument name is @code{divisor}. +@code{eval} refers to its second argument as @samp{FORM}, because the +actual argument name is @code{form}: + +@example +Evaluate FORM and return its value. +@end example + +Also write metasyntactic variables in capital letters, such as when you +show the decomposition of a list or vector into subunits, some of which +may vary. @samp{KEY} and @samp{VALUE} in the following example +illustrate this practice: -Also use all caps for meta-syntactic variables, such as when you show -the decomposition of a list or vector into subunits, some of which may -vary. +@example +The argument TABLE should be an alist whose elements +have the form (KEY . VALUE). Here, KEY is ... +@end example + +@item +If a line in a documentation string begins with an open-parenthesis, +write a backslash before the open-parenthesis, like this: + +@example +The argument FOO can be either a number +\(a buffer position) or a string (a file name). +@end example + +This prevents the open-parenthesis from being treated as the start of a +defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}). @item @iftex @@ -401,22 +545,63 @@ would be printed (which usually means in lower case), with single-quotes around it. For example: @samp{`lambda'}. There are two exceptions: write @code{t} and @code{nil} without single-quotes. @end iftex -@ifinfo +@ifnottex When a documentation string refers to a Lisp symbol, write it as it would be printed (which usually means in lower case), with single-quotes around it. For example: @samp{lambda}. There are two exceptions: write -t and nil without single-quotes. (In this manual, we normally do use -single-quotes for those symbols.) -@end ifinfo +t and nil without single-quotes. (In this manual, we use a different +convention, with single-quotes for all symbols.) +@end ifnottex + +Help mode automatically creates a hyperlink when a documentation string +uses a symbol name inside single quotes, if the symbol has either a +function or a variable definition. You do not need to do anything +special to make use of this feature. However, when a symbol has both a +function definition and a variable definition, and you want to refer to +just one of them, you can specify which one by writing one of the words +@samp{variable}, @samp{option}, @samp{function}, or @samp{command}, +immediately before the symbol name. (Case makes no difference in +recognizing these indicator words.) For example, if you write + +@example +This function sets the variable `buffer-file-name'. +@end example + +@noindent +then the hyperlink will refer only to the variable documentation of +@code{buffer-file-name}, and not to its function documentation. + +If a symbol has a function definition and/or a variable definition, but +those are irrelevant to the use of the symbol that you are documenting, +you can write the word @samp{symbol} before the symbol name to prevent +making any hyperlink. For example, + +@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 +does not make a hyperlink to the documentation, irrelevant here, of the +function @code{list}. + +To make a hyperlink to Info documentation, write the name of the Info +node in single quotes, preceded by @samp{info node} or @samp{Info +node}. The Info file name defaults to @samp{emacs}. For example, + +@smallexample +See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'. +@end smallexample @item Don't write key sequences directly in documentation strings. Instead, use the @samp{\\[@dots{}]} construct to stand for them. For example, -instead of writing @samp{C-f}, write @samp{\\[forward-char]}. When -Emacs displays the documentation string, it substitutes whatever key is -currently bound to @code{forward-char}. (This is normally @samp{C-f}, -but it may be some other character if the user has moved key bindings.) -@xref{Keys in Documentation}. +instead of writing @samp{C-f}, write the construct +@samp{\\[forward-char]}. When Emacs displays the documentation string, +it substitutes whatever key is currently bound to @code{forward-char}. +(This is normally @samp{C-f}, but it may be some other character if the +user has moved key bindings.) @xref{Keys in Documentation}. @item In documentation strings for a major mode, you will want to refer to the @@ -431,10 +616,6 @@ It is not practical to use @samp{\\[@dots{}]} very many times, because display of the documentation string will become slow. So use this to describe the most important commands in your major mode, and then use @samp{\\@{@dots{}@}} to display the rest of the mode's keymap. - -@item -Don't use the term ``Elisp'', since that is or was a trademark. -Use the term ``Emacs Lisp''. @end itemize @node Comment Tips @@ -479,28 +660,31 @@ at that point. For example: @end group @end smallexample -Every function that has no documentation string (because it is use only -internally within the package it belongs to), should have instead a -two-semicolon comment right before the function, explaining what the -function does and how to call it properly. Explain precisely what each -argument means and how the function interprets its possible values. - -@item ;;; -Comments that start with three semicolons, @samp{;;;}, should start at -the left margin. Such comments are used outside function definitions to -make general statements explaining the design principles of the program. -For example: +We also normally use two semicolons for comments outside functions. @smallexample @group -;;; This Lisp code is run in Emacs -;;; when it is to operate as a server -;;; for other processes. +;; This Lisp code is run in Emacs +;; when it is to operate as a server +;; for other processes. @end group @end smallexample +Every function that has no documentation string (presumably one that is +used only internally within the package it belongs to), should instead +have a two-semicolon comment right before the function, explaining what +the function does and how to call it properly. Explain precisely what +each argument means and how the function interprets its possible values. + +@item ;;; +Comments that start with three semicolons, @samp{;;;}, should start at +the left margin. These are used, occasionally, for comments within +functions that should start at the margin. We also use them sometimes +for comments that are between functions---whether to use two or three +semicolons there is a matter of style. + Another use for triple-semicolon comments is for commenting out lines -within a function. We use triple-semicolons for this precisely so that +within a function. We use three semicolons for this precisely so that they remain at the left margin. @smallexample @@ -522,7 +706,7 @@ program. For example: @noindent The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;} -(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}) +(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}), automatically indent comments according to these conventions, depending on the number of semicolons. @xref{Comments,, Manipulating Comments, emacs, The GNU Emacs Manual}. @@ -532,9 +716,23 @@ Manipulating Comments, emacs, The GNU Emacs Manual}. @cindex header comments @cindex library header comments - Emacs 19 has conventions for using special comments in Lisp libraries + Emacs has conventions for using special comments in Lisp libraries to divide them into sections and give information such as who wrote -them. This section explains these conventions. First, an example: +them. This section explains these conventions. + + We'll start with an example, a package that is included in the Emacs +distribution. + + Parts of this example reflect its status as part of Emacs; for +example, the copyright notice lists the Free Software Foundation as the +copyright holder, and the copying permission says the file is part of +Emacs. When you write a package and post it, the copyright holder would +be you (unless your employer claims to own it instead), and you should +get the suggested copying permission from the end of the GNU General +Public License itself. Don't say your file is part of Emacs +if we haven't installed it in Emacs yet! + + With that warning out of the way, on to the example: @smallexample @group @@ -551,7 +749,9 @@ them. This section explains these conventions. First, an example: ;; Keywords: docs ;; This file is part of GNU Emacs. -@var{copying permissions}@dots{} +@dots{} +;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, +;; Boston, MA 02111-1307, USA. @end group @end smallexample @@ -614,6 +814,8 @@ example). @item Keywords This line lists keywords for the @code{finder-by-keyword} help command. +Please use that command to see a list of the meaningful keywords. + This field is important; it's how people will find your package when they're looking for things by topic area. To separate the keywords, you can use spaces, commas, or both. @@ -625,19 +827,27 @@ appropriate. You can also put in header lines with other header names---they have no standard meanings, so they can't do any harm. We use additional stylized comments to subdivide the contents of the -library file. Here is a table of them: +library file. These should be separated by blank lines from anything +else. Here is a table of them: @table @samp @item ;;; Commentary: This begins introductory comments that explain how the library works. -It should come right after the copying permissions. +It should come right after the copying permissions, terminated by a +@samp{Change Log}, @samp{History} or @samp{Code} comment line. This +text is used by the Finder package, so it should make sense in that +context. + +@item ;;; Documentation +This has been used in some files in place of @samp{;;; Commentary:}, +but @samp{;;; Commentary:} is preferred. -@item ;;; Change log: +@item ;;; Change Log: This begins change log information stored in the library file (if you -store the change history there). For most of the Lisp -files distributed with Emacs, the change history is kept in the file -@file{ChangeLog} and not in the source file at all; these files do -not have a @samp{;;; Change log:} line. +store the change history there). For Lisp files distributed with Emacs, +the change history is kept in the file @file{ChangeLog} and not in the +source file at all; these files generally do not have a @samp{;;; Change +Log:} line. @samp{History} is an alternative to @samp{Change Log}. @item ;;; Code: This begins the actual code of the program.