428
+ − 1 @c -*-texinfo-*-
+ − 2 @c This is part of the XEmacs Lisp Reference Manual.
444
+ − 3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
428
+ − 4 @c See the file lispref.texi for copying conditions.
+ − 5 @setfilename ../../info/tips.info
+ − 6 @node Tips, Building XEmacs and Object Allocation, MULE, Top
+ − 7 @appendix Tips and Standards
+ − 8 @cindex tips
+ − 9 @cindex standards of coding style
+ − 10 @cindex coding standards
+ − 11
+ − 12 This chapter describes no additional features of XEmacs Lisp.
+ − 13 Instead it gives advice on making effective use of the features described
+ − 14 in the previous chapters.
+ − 15
+ − 16 @menu
+ − 17 * Style Tips:: Writing clean and robust programs.
+ − 18 * Compilation Tips:: Making compiled code run fast.
+ − 19 * Documentation Tips:: Writing readable documentation strings.
+ − 20 * Comment Tips:: Conventions for writing comments.
+ − 21 * Library Headers:: Standard headers for library packages.
+ − 22 @end menu
+ − 23
+ − 24 @node Style Tips
+ − 25 @section Writing Clean Lisp Programs
+ − 26
+ − 27 Here are some tips for avoiding common errors in writing Lisp code
+ − 28 intended for widespread use:
+ − 29
+ − 30 @itemize @bullet
+ − 31 @item
+ − 32 Since all global variables share the same name space, and all functions
+ − 33 share another name space, you should choose a short word to distinguish
+ − 34 your program from other Lisp programs. Then take care to begin the
+ − 35 names of all global variables, constants, and functions with the chosen
+ − 36 prefix. This helps avoid name conflicts.
+ − 37
+ − 38 This recommendation applies even to names for traditional Lisp
+ − 39 primitives that are not primitives in XEmacs Lisp---even to @code{cadr}.
+ − 40 Believe it or not, there is more than one plausible way to define
+ − 41 @code{cadr}. Play it safe; append your name prefix to produce a name
+ − 42 like @code{foo-cadr} or @code{mylib-cadr} instead.
+ − 43
+ − 44 If you write a function that you think ought to be added to Emacs under
+ − 45 a certain name, such as @code{twiddle-files}, don't call it by that name
+ − 46 in your program. Call it @code{mylib-twiddle-files} in your program,
+ − 47 and send mail to @samp{bug-gnu-emacs@@prep.ai.mit.edu} suggesting we add
+ − 48 it to Emacs. If and when we do, we can change the name easily enough.
+ − 49
+ − 50 If one prefix is insufficient, your package may use two or three
+ − 51 alternative common prefixes, so long as they make sense.
+ − 52
+ − 53 Separate the prefix from the rest of the symbol name with a hyphen,
+ − 54 @samp{-}. This will be consistent with XEmacs itself and with most Emacs
+ − 55 Lisp programs.
+ − 56
+ − 57 @item
+ − 58 It is often useful to put a call to @code{provide} in each separate
+ − 59 library program, at least if there is more than one entry point to the
+ − 60 program.
+ − 61
+ − 62 @item
+ − 63 If a file requires certain other library programs to be loaded
+ − 64 beforehand, then the comments at the beginning of the file should say
+ − 65 so. Also, use @code{require} to make sure they are loaded.
+ − 66
+ − 67 @item
+ − 68 If one file @var{foo} uses a macro defined in another file @var{bar},
+ − 69 @var{foo} should contain this expression before the first use of the
+ − 70 macro:
+ − 71
+ − 72 @example
+ − 73 (eval-when-compile (require '@var{bar}))
+ − 74 @end example
+ − 75
+ − 76 @noindent
+ − 77 (And @var{bar} should contain @code{(provide '@var{bar})}, to make the
+ − 78 @code{require} work.) This will cause @var{bar} to be loaded when you
+ − 79 byte-compile @var{foo}. Otherwise, you risk compiling @var{foo} without
+ − 80 the necessary macro loaded, and that would produce compiled code that
+ − 81 won't work right. @xref{Compiling Macros}.
+ − 82
+ − 83 Using @code{eval-when-compile} avoids loading @var{bar} when
+ − 84 the compiled version of @var{foo} is @emph{used}.
+ − 85
+ − 86 @item
+ − 87 If you define a major mode, make sure to run a hook variable using
+ − 88 @code{run-hooks}, just as the existing major modes do. @xref{Hooks}.
+ − 89
+ − 90 @item
+ − 91 If the purpose of a function is to tell you whether a certain condition
+ − 92 is true or false, give the function a name that ends in @samp{p}. If
+ − 93 the name is one word, add just @samp{p}; if the name is multiple words,
+ − 94 add @samp{-p}. Examples are @code{framep} and @code{frame-live-p}.
+ − 95
+ − 96 @item
+ − 97 If a user option variable records a true-or-false condition, give it a
+ − 98 name that ends in @samp{-flag}.
+ − 99
+ − 100 @item
+ − 101 Please do not define @kbd{C-c @var{letter}} as a key in your major
+ − 102 modes. These sequences are reserved for users; they are the
+ − 103 @strong{only} sequences reserved for users, so we cannot do without
+ − 104 them.
+ − 105
+ − 106 Instead, define sequences consisting of @kbd{C-c} followed by a
+ − 107 non-letter. These sequences are reserved for major modes.
+ − 108
+ − 109 Changing all the major modes in Emacs 18 so they would follow this
+ − 110 convention was a lot of work. Abandoning this convention would make
+ − 111 that work go to waste, and inconvenience users.
+ − 112
+ − 113 @item
+ − 114 Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
+ − 115 @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes.
+ − 116
+ − 117 @item
+ − 118 Sequences consisting of @kbd{C-c} followed by any other punctuation
+ − 119 character are allocated for minor modes. Using them in a major mode is
+ − 120 not absolutely prohibited, but if you do that, the major mode binding
+ − 121 may be shadowed from time to time by minor modes.
+ − 122
+ − 123 @item
+ − 124 You should not bind @kbd{C-h} following any prefix character (including
+ − 125 @kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically available
+ − 126 as a help character for listing the subcommands of the prefix character.
+ − 127
+ − 128 @item
+ − 129 You should not bind a key sequence ending in @key{ESC} except following
+ − 130 another @key{ESC}. (That is, it is ok to bind a sequence ending in
+ − 131 @kbd{@key{ESC} @key{ESC}}.)
+ − 132
+ − 133 The reason for this rule is that a non-prefix binding for @key{ESC} in
+ − 134 any context prevents recognition of escape sequences as function keys in
+ − 135 that context.
+ − 136
+ − 137 @item
+ − 138 Applications should not bind mouse events based on button 1 with the
+ − 139 shift key held down. These events include @kbd{S-mouse-1},
+ − 140 @kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on. They are reserved for
+ − 141 users.
+ − 142
+ − 143 @item
+ − 144 Modes should redefine @kbd{mouse-2} as a command to follow some sort of
+ − 145 reference in the text of a buffer, if users usually would not want to
+ − 146 alter the text in that buffer by hand. Modes such as Dired, Info,
+ − 147 Compilation, and Occur redefine it in this way.
+ − 148
+ − 149 @item
+ − 150 When a package provides a modification of ordinary Emacs behavior, it is
+ − 151 good to include a command to enable and disable the feature, Provide a
+ − 152 command named @code{@var{whatever}-mode} which turns the feature on or
+ − 153 off, and make it autoload (@pxref{Autoload}). Design the package so
+ − 154 that simply loading it has no visible effect---that should not enable
+ − 155 the feature. Users will request the feature by invoking the command.
+ − 156
+ − 157 @item
+ − 158 It is a bad idea to define aliases for the Emacs primitives. Use the
+ − 159 standard names instead.
+ − 160
+ − 161 @item
+ − 162 Redefining an Emacs primitive is an even worse idea.
444
+ − 163 It may do the right thing for a particular program, but
428
+ − 164 there is no telling what other programs might break as a result.
+ − 165
+ − 166 @item
+ − 167 If a file does replace any of the functions or library programs of
+ − 168 standard XEmacs, prominent comments at the beginning of the file should
+ − 169 say which functions are replaced, and how the behavior of the
+ − 170 replacements differs from that of the originals.
+ − 171
+ − 172 @item
+ − 173 Please keep the names of your XEmacs Lisp source files to 13 characters
+ − 174 or less. This way, if the files are compiled, the compiled files' names
+ − 175 will be 14 characters or less, which is short enough to fit on all kinds
+ − 176 of Unix systems.
+ − 177
+ − 178 @item
+ − 179 Don't use @code{next-line} or @code{previous-line} in programs; nearly
+ − 180 always, @code{forward-line} is more convenient as well as more
+ − 181 predictable and robust. @xref{Text Lines}.
+ − 182
+ − 183 @item
+ − 184 Don't call functions that set the mark, unless setting the mark is one
+ − 185 of the intended features of your program. The mark is a user-level
+ − 186 feature, so it is incorrect to change the mark except to supply a value
+ − 187 for the user's benefit. @xref{The Mark}.
+ − 188
+ − 189 In particular, don't use these functions:
+ − 190
+ − 191 @itemize @bullet
+ − 192 @item
+ − 193 @code{beginning-of-buffer}, @code{end-of-buffer}
+ − 194 @item
+ − 195 @code{replace-string}, @code{replace-regexp}
+ − 196 @end itemize
+ − 197
+ − 198 If you just want to move point, or replace a certain string, without any
+ − 199 of the other features intended for interactive users, you can replace
+ − 200 these functions with one or two lines of simple Lisp code.
+ − 201
+ − 202 @item
+ − 203 Use lists rather than vectors, except when there is a particular reason
+ − 204 to use a vector. Lisp has more facilities for manipulating lists than
+ − 205 for vectors, and working with lists is usually more convenient.
+ − 206
+ − 207 Vectors are advantageous for tables that are substantial in size and are
+ − 208 accessed in random order (not searched front to back), provided there is
+ − 209 no need to insert or delete elements (only lists allow that).
+ − 210
+ − 211 @item
+ − 212 The recommended way to print a message in the echo area is with
+ − 213 the @code{message} function, not @code{princ}. @xref{The Echo Area}.
+ − 214
+ − 215 @item
+ − 216 When you encounter an error condition, call the function @code{error}
+ − 217 (or @code{signal}). The function @code{error} does not return.
+ − 218 @xref{Signaling Errors}.
+ − 219
+ − 220 Do not use @code{message}, @code{throw}, @code{sleep-for},
+ − 221 or @code{beep} to report errors.
+ − 222
+ − 223 @item
+ − 224 An error message should start with a capital letter but should not end
+ − 225 with a period.
+ − 226
+ − 227 @item
+ − 228 Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e}
+ − 229 command does: use a new local keymap that contains one command defined
+ − 230 to switch back to the old local keymap. Or do what the
+ − 231 @code{edit-options} command does: switch to another buffer and let the
+ − 232 user switch back at will. @xref{Recursive Editing}.
+ − 233
+ − 234 @item
+ − 235 In some other systems there is a convention of choosing variable names
+ − 236 that begin and end with @samp{*}. We don't use that convention in Emacs
+ − 237 Lisp, so please don't use it in your programs. (Emacs uses such names
+ − 238 only for program-generated buffers.) The users will find Emacs more
+ − 239 coherent if all libraries use the same conventions.
+ − 240
+ − 241 @item
+ − 242 Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
+ − 243 default indentation parameters.
+ − 244
+ − 245 @item
+ − 246 Don't make a habit of putting close-parentheses on lines by themselves;
+ − 247 Lisp programmers find this disconcerting. Once in a while, when there
+ − 248 is a sequence of many consecutive close-parentheses, it may make sense
+ − 249 to split them in one or two significant places.
+ − 250
+ − 251 @item
+ − 252 Please put a copyright notice on the file if you give copies to anyone.
+ − 253 Use the same lines that appear at the top of the Lisp files in XEmacs
+ − 254 itself. If you have not signed papers to assign the copyright to the
+ − 255 Foundation, then place your name in the copyright notice in place of the
+ − 256 Foundation's name.
+ − 257 @end itemize
+ − 258
+ − 259 @node Compilation Tips
+ − 260 @section Tips for Making Compiled Code Fast
+ − 261 @cindex execution speed
+ − 262 @cindex speedups
+ − 263
+ − 264 Here are ways of improving the execution speed of byte-compiled
+ − 265 Lisp programs.
+ − 266
+ − 267 @itemize @bullet
+ − 268 @item
+ − 269 @cindex profiling
+ − 270 @cindex timing programs
+ − 271 @cindex @file{profile.el}
+ − 272 Use the @file{profile} library to profile your program. See the file
+ − 273 @file{profile.el} for instructions.
+ − 274
+ − 275 @item
+ − 276 Use iteration rather than recursion whenever possible.
+ − 277 Function calls are slow in XEmacs Lisp even when a compiled function
+ − 278 is calling another compiled function.
+ − 279
+ − 280 @item
+ − 281 Using the primitive list-searching functions @code{memq}, @code{member},
+ − 282 @code{assq}, or @code{assoc} is even faster than explicit iteration. It
+ − 283 may be worth rearranging a data structure so that one of these primitive
+ − 284 search functions can be used.
+ − 285
+ − 286 @item
444
+ − 287 Certain built-in functions are handled specially in byte-compiled code,
428
+ − 288 avoiding the need for an ordinary function call. It is a good idea to
+ − 289 use these functions rather than alternatives. To see whether a function
+ − 290 is handled specially by the compiler, examine its @code{byte-compile}
+ − 291 property. If the property is non-@code{nil}, then the function is
+ − 292 handled specially.
+ − 293
+ − 294 For example, the following input will show you that @code{aref} is
+ − 295 compiled specially (@pxref{Array Functions}) while @code{elt} is not
+ − 296 (@pxref{Sequence Functions}):
+ − 297
+ − 298 @example
+ − 299 @group
+ − 300 (get 'aref 'byte-compile)
+ − 301 @result{} byte-compile-two-args
+ − 302 @end group
+ − 303
+ − 304 @group
+ − 305 (get 'elt 'byte-compile)
+ − 306 @result{} nil
+ − 307 @end group
+ − 308 @end example
+ − 309
+ − 310 @item
+ − 311 If calling a small function accounts for a substantial part of your
+ − 312 program's running time, make the function inline. This eliminates
+ − 313 the function call overhead. Since making a function inline reduces
+ − 314 the flexibility of changing the program, don't do it unless it gives
+ − 315 a noticeable speedup in something slow enough that users care about
+ − 316 the speed. @xref{Inline Functions}.
+ − 317 @end itemize
+ − 318
+ − 319 @node Documentation Tips
+ − 320 @section Tips for Documentation Strings
+ − 321
+ − 322 Here are some tips for the writing of documentation strings.
+ − 323
+ − 324 @itemize @bullet
+ − 325 @item
+ − 326 Every command, function, or variable intended for users to know about
+ − 327 should have a documentation string.
+ − 328
+ − 329 @item
+ − 330 An internal variable or subroutine of a Lisp program might as well have
+ − 331 a documentation string. In earlier Emacs versions, you could save space
+ − 332 by using a comment instead of a documentation string, but that is no
+ − 333 longer the case.
+ − 334
+ − 335 @item
+ − 336 The first line of the documentation string should consist of one or two
+ − 337 complete sentences that stand on their own as a summary. @kbd{M-x
+ − 338 apropos} displays just the first line, and if it doesn't stand on its
+ − 339 own, the result looks bad. In particular, start the first line with a
+ − 340 capital letter and end with a period.
+ − 341
+ − 342 The documentation string can have additional lines that expand on the
+ − 343 details of how to use the function or variable. The additional lines
+ − 344 should be made up of complete sentences also, but they may be filled if
+ − 345 that looks good.
+ − 346
+ − 347 @item
+ − 348 For consistency, phrase the verb in the first sentence of a
+ − 349 documentation string as an infinitive with ``to'' omitted. For
+ − 350 instance, use ``Return the cons of A and B.'' in preference to ``Returns
+ − 351 the cons of A and B@.'' Usually it looks good to do likewise for the
+ − 352 rest of the first paragraph. Subsequent paragraphs usually look better
+ − 353 if they have proper subjects.
+ − 354
+ − 355 @item
+ − 356 Write documentation strings in the active voice, not the passive, and in
+ − 357 the present tense, not the future. For instance, use ``Return a list
+ − 358 containing A and B.'' instead of ``A list containing A and B will be
+ − 359 returned.''
+ − 360
+ − 361 @item
+ − 362 Avoid using the word ``cause'' (or its equivalents) unnecessarily.
+ − 363 Instead of, ``Cause Emacs to display text in boldface,'' write just
+ − 364 ``Display text in boldface.''
+ − 365
+ − 366 @item
+ − 367 Do not start or end a documentation string with whitespace.
+ − 368
+ − 369 @item
+ − 370 Format the documentation string so that it fits in an Emacs window on an
+ − 371 80-column screen. It is a good idea for most lines to be no wider than
444
+ − 372 60 characters. The first line can be wider if necessary to fit the
428
+ − 373 information that ought to be there.
+ − 374
+ − 375 However, rather than simply filling the entire documentation string, you
+ − 376 can make it much more readable by choosing line breaks with care.
+ − 377 Use blank lines between topics if the documentation string is long.
444
+ − 378
428
+ − 379 @item
+ − 380 @strong{Do not} indent subsequent lines of a documentation string so
+ − 381 that the text is lined up in the source code with the text of the first
+ − 382 line. This looks nice in the source code, but looks bizarre when users
+ − 383 view the documentation. Remember that the indentation before the
+ − 384 starting double-quote is not part of the string!
+ − 385
+ − 386 @item
+ − 387 A variable's documentation string should start with @samp{*} if the
+ − 388 variable is one that users would often want to set interactively. If
+ − 389 the value is a long list, or a function, or if the variable would be set
+ − 390 only in init files, then don't start the documentation string with
+ − 391 @samp{*}. @xref{Defining Variables}.
+ − 392
+ − 393 @item
+ − 394 The documentation string for a variable that is a yes-or-no flag should
+ − 395 start with words such as ``Non-nil means@dots{}'', to make it clear that
+ − 396 all non-@code{nil} values are equivalent and indicate explicitly what
+ − 397 @code{nil} and non-@code{nil} mean.
+ − 398
+ − 399 @item
+ − 400 When a function's documentation string mentions the value of an argument
+ − 401 of the function, use the argument name in capital letters as if it were
+ − 402 a name for that value. Thus, the documentation string of the function
+ − 403 @code{/} refers to its second argument as @samp{DIVISOR}, because the
+ − 404 actual argument name is @code{divisor}.
+ − 405
+ − 406 Also use all caps for meta-syntactic variables, such as when you show
+ − 407 the decomposition of a list or vector into subunits, some of which may
+ − 408 vary.
+ − 409
+ − 410 @item
+ − 411 @iftex
+ − 412 When a documentation string refers to a Lisp symbol, write it as it
+ − 413 would be printed (which usually means in lower case), with single-quotes
+ − 414 around it. For example: @samp{`lambda'}. There are two exceptions:
+ − 415 write @code{t} and @code{nil} without single-quotes.
+ − 416 @end iftex
+ − 417 @ifinfo
+ − 418 When a documentation string refers to a Lisp symbol, write it as it
+ − 419 would be printed (which usually means in lower case), with single-quotes
+ − 420 around it. For example: @samp{lambda}. There are two exceptions: write
+ − 421 t and nil without single-quotes. (In this manual, we normally do use
+ − 422 single-quotes for those symbols.)
+ − 423 @end ifinfo
+ − 424
+ − 425 @item
+ − 426 Don't write key sequences directly in documentation strings. Instead,
+ − 427 use the @samp{\\[@dots{}]} construct to stand for them. For example,
+ − 428 instead of writing @samp{C-f}, write @samp{\\[forward-char]}. When
+ − 429 Emacs displays the documentation string, it substitutes whatever key is
+ − 430 currently bound to @code{forward-char}. (This is normally @samp{C-f},
+ − 431 but it may be some other character if the user has moved key bindings.)
+ − 432 @xref{Keys in Documentation}.
+ − 433
+ − 434 @item
+ − 435 In documentation strings for a major mode, you will want to refer to the
+ − 436 key bindings of that mode's local map, rather than global ones.
+ − 437 Therefore, use the construct @samp{\\<@dots{}>} once in the
+ − 438 documentation string to specify which key map to use. Do this before
+ − 439 the first use of @samp{\\[@dots{}]}. The text inside the
+ − 440 @samp{\\<@dots{}>} should be the name of the variable containing the
+ − 441 local keymap for the major mode.
+ − 442
+ − 443 It is not practical to use @samp{\\[@dots{}]} very many times, because
+ − 444 display of the documentation string will become slow. So use this to
+ − 445 describe the most important commands in your major mode, and then use
+ − 446 @samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
+ − 447 @end itemize
+ − 448
+ − 449 @node Comment Tips
+ − 450 @section Tips on Writing Comments
+ − 451
+ − 452 We recommend these conventions for where to put comments and how to
+ − 453 indent them:
+ − 454
+ − 455 @table @samp
+ − 456 @item ;
+ − 457 Comments that start with a single semicolon, @samp{;}, should all be
+ − 458 aligned to the same column on the right of the source code. Such
+ − 459 comments usually explain how the code on the same line does its job. In
+ − 460 Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment})
+ − 461 command automatically inserts such a @samp{;} in the right place, or
+ − 462 aligns such a comment if it is already present.
+ − 463
+ − 464 This and following examples are taken from the Emacs sources.
+ − 465
+ − 466 @smallexample
+ − 467 @group
+ − 468 (setq base-version-list ; there was a base
+ − 469 (assoc (substring fn 0 start-vn) ; version to which
+ − 470 file-version-assoc-list)) ; this looks like
+ − 471 ; a subversion
+ − 472 @end group
+ − 473 @end smallexample
+ − 474
+ − 475 @item ;;
+ − 476 Comments that start with two semicolons, @samp{;;}, should be aligned to
+ − 477 the same level of indentation as the code. Such comments usually
+ − 478 describe the purpose of the following lines or the state of the program
+ − 479 at that point. For example:
+ − 480
+ − 481 @smallexample
+ − 482 @group
+ − 483 (prog1 (setq auto-fill-function
+ − 484 @dots{}
+ − 485 @dots{}
+ − 486 ;; update modeline
+ − 487 (redraw-modeline)))
+ − 488 @end group
+ − 489 @end smallexample
+ − 490
1755
+ − 491 Every function that has no documentation string (because it is used only
428
+ − 492 internally within the package it belongs to), should have instead a
+ − 493 two-semicolon comment right before the function, explaining what the
+ − 494 function does and how to call it properly. Explain precisely what each
+ − 495 argument means and how the function interprets its possible values.
+ − 496
+ − 497 @item ;;;
+ − 498 Comments that start with three semicolons, @samp{;;;}, should start at
+ − 499 the left margin. Such comments are used outside function definitions to
+ − 500 make general statements explaining the design principles of the program.
+ − 501 For example:
+ − 502
+ − 503 @smallexample
+ − 504 @group
+ − 505 ;;; This Lisp code is run in XEmacs
+ − 506 ;;; when it is to operate as a server
+ − 507 ;;; for other processes.
+ − 508 @end group
+ − 509 @end smallexample
+ − 510
+ − 511 Another use for triple-semicolon comments is for commenting out lines
+ − 512 within a function. We use triple-semicolons for this precisely so that
+ − 513 they remain at the left margin.
+ − 514
+ − 515 @smallexample
+ − 516 (defun foo (a)
+ − 517 ;;; This is no longer necessary.
+ − 518 ;;; (force-mode-line-update)
+ − 519 (message "Finished with %s" a))
+ − 520 @end smallexample
+ − 521
+ − 522 @item ;;;;
+ − 523 Comments that start with four semicolons, @samp{;;;;}, should be aligned
+ − 524 to the left margin and are used for headings of major sections of a
+ − 525 program. For example:
+ − 526
+ − 527 @smallexample
+ − 528 ;;;; The kill ring
+ − 529 @end smallexample
+ − 530 @end table
+ − 531
+ − 532 @noindent
+ − 533 The indentation commands of the Lisp modes in XEmacs, such as @kbd{M-;}
+ − 534 (@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line})
+ − 535 automatically indent comments according to these conventions,
+ − 536 depending on the number of semicolons. @xref{Comments,,
446
+ − 537 Manipulating Comments, xemacs, The XEmacs User's Manual}.
428
+ − 538
+ − 539 @node Library Headers
+ − 540 @section Conventional Headers for XEmacs Libraries
+ − 541 @cindex header comments
+ − 542 @cindex library header comments
+ − 543
+ − 544 XEmacs has conventions for using special comments in Lisp libraries
+ − 545 to divide them into sections and give information such as who wrote
+ − 546 them. This section explains these conventions. First, an example:
+ − 547
+ − 548 @smallexample
+ − 549 @group
+ − 550 ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
+ − 551
+ − 552 ;; Copyright (C) 1992 Free Software Foundation, Inc.
+ − 553 @end group
+ − 554
+ − 555 ;; Author: Eric S. Raymond <esr@@snark.thyrsus.com>
+ − 556 ;; Maintainer: Eric S. Raymond <esr@@snark.thyrsus.com>
+ − 557 ;; Created: 14 Jul 1992
+ − 558 ;; Version: 1.2
+ − 559 @group
+ − 560 ;; Keywords: docs
+ − 561
+ − 562 ;; This file is part of XEmacs.
+ − 563 @var{copying permissions}@dots{}
+ − 564 @end group
+ − 565 @end smallexample
+ − 566
+ − 567 The very first line should have this format:
+ − 568
+ − 569 @example
+ − 570 ;;; @var{filename} --- @var{description}
+ − 571 @end example
+ − 572
+ − 573 @noindent
+ − 574 The description should be complete in one line.
+ − 575
+ − 576 After the copyright notice come several @dfn{header comment} lines,
+ − 577 each beginning with @samp{;; @var{header-name}:}. Here is a table of
+ − 578 the conventional possibilities for @var{header-name}:
+ − 579
+ − 580 @table @samp
+ − 581 @item Author
+ − 582 This line states the name and net address of at least the principal
+ − 583 author of the library.
+ − 584
+ − 585 If there are multiple authors, you can list them on continuation lines
+ − 586 led by @code{;;} and a tab character, like this:
+ − 587
+ − 588 @smallexample
+ − 589 @group
+ − 590 ;; Author: Ashwin Ram <Ram-Ashwin@@cs.yale.edu>
+ − 591 ;; Dave Sill <de5@@ornl.gov>
+ − 592 ;; Dave Brennan <brennan@@hal.com>
+ − 593 ;; Eric Raymond <esr@@snark.thyrsus.com>
+ − 594 @end group
+ − 595 @end smallexample
+ − 596
+ − 597 @item Maintainer
+ − 598 This line should contain a single name/address as in the Author line, or
+ − 599 an address only, or the string @samp{FSF}. If there is no maintainer
+ − 600 line, the person(s) in the Author field are presumed to be the
+ − 601 maintainers. The example above is mildly bogus because the maintainer
+ − 602 line is redundant.
+ − 603
+ − 604 The idea behind the @samp{Author} and @samp{Maintainer} lines is to make
+ − 605 possible a Lisp function to ``send mail to the maintainer'' without
+ − 606 having to mine the name out by hand.
+ − 607
+ − 608 Be sure to surround the network address with @samp{<@dots{}>} if
+ − 609 you include the person's full name as well as the network address.
+ − 610
+ − 611 @item Created
+ − 612 This optional line gives the original creation date of the
+ − 613 file. For historical interest only.
+ − 614
+ − 615 @item Version
+ − 616 If you wish to record version numbers for the individual Lisp program, put
+ − 617 them in this line.
+ − 618
+ − 619 @item Adapted-By
+ − 620 In this header line, place the name of the person who adapted the
+ − 621 library for installation (to make it fit the style conventions, for
+ − 622 example).
+ − 623
+ − 624 @item Keywords
+ − 625 This line lists keywords for the @code{finder-by-keyword} help command.
+ − 626 This field is important; it's how people will find your package when
+ − 627 they're looking for things by topic area. To separate the keywords, you
+ − 628 can use spaces, commas, or both.
+ − 629 @end table
+ − 630
+ − 631 Just about every Lisp library ought to have the @samp{Author} and
+ − 632 @samp{Keywords} header comment lines. Use the others if they are
+ − 633 appropriate. You can also put in header lines with other header
+ − 634 names---they have no standard meanings, so they can't do any harm.
+ − 635
+ − 636 We use additional stylized comments to subdivide the contents of the
+ − 637 library file. Here is a table of them:
+ − 638
+ − 639 @table @samp
+ − 640 @item ;;; Commentary:
+ − 641 This begins introductory comments that explain how the library works.
+ − 642 It should come right after the copying permissions.
+ − 643
+ − 644 @item ;;; Change log:
+ − 645 This begins change log information stored in the library file (if you
+ − 646 store the change history there). For most of the Lisp
+ − 647 files distributed with XEmacs, the change history is kept in the file
+ − 648 @file{ChangeLog} and not in the source file at all; these files do
+ − 649 not have a @samp{;;; Change log:} line.
+ − 650
+ − 651 @item ;;; Code:
+ − 652 This begins the actual code of the program.
+ − 653
+ − 654 @item ;;; @var{filename} ends here
+ − 655 This is the @dfn{footer line}; it appears at the very end of the file.
+ − 656 Its purpose is to enable people to detect truncated versions of the file
+ − 657 from the lack of a footer line.
+ − 658 @end table
