--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/lispref/tips.texi	Mon Aug 13 08:45:50 2007 +0200
@@ -0,0 +1,658 @@
+@c -*-texinfo-*-
+@c This is part of the XEmacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. 
+@c See the file lispref.texi for copying conditions.
+@setfilename ../../info/tips.info
+@node Tips, Building XEmacs and Object Allocation, MULE, Top
+@appendix Tips and Standards
+@cindex tips
+@cindex standards of coding style
+@cindex coding standards
+
+  This chapter describes no additional features of XEmacs Lisp.
+Instead it gives advice on making effective use of the features described
+in the previous chapters.
+
+@menu
+* Style Tips::                Writing 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
+
+  Here are some tips for avoiding common errors in writing Lisp code
+intended for widespread use:
+
+@itemize @bullet
+@item
+Since all global variables share the same name space, and all functions
+share another name space, you should choose a short word to distinguish
+your program from other Lisp programs.  Then take care to begin the
+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 XEmacs 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.
+
+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
+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
+alternative common prefixes, so long as they make sense.
+
+Separate the prefix from the rest of the symbol name with a hyphen,
+@samp{-}.  This will be consistent with XEmacs itself and with most Emacs
+Lisp programs.
+
+@item
+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 this expression before the first use of the
+macro:
+
+@example
+(eval-when-compile (require '@var{bar}))
+@end example
+
+@noindent
+(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}.
+
+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}.
+
+@item
+If the purpose of a function is to tell you whether a certain condition
+is true or false, give the function a name that ends in @samp{p}.  If
+the name is one word, add just @samp{p}; if the name is multiple words,
+add @samp{-p}.  Examples are @code{framep} and @code{frame-live-p}.
+
+@item
+If a user option variable records a true-or-false condition, give it a
+name that ends in @samp{-flag}.
+
+@item
+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.
+
+Instead, define sequences consisting of @kbd{C-c} followed by a
+non-letter.  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.
+
+@item
+Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
+@kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes.
+
+@item
+Sequences consisting of @kbd{C-c} followed by any other punctuation
+character are allocated for minor modes.  Using them in a major mode is
+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
+@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
+@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
+Applications should not bind mouse events based on button 1 with the
+shift key held down.  These events include @kbd{S-mouse-1},
+@kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on.  They are reserved for
+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.
+
+@item
+When a package provides a modification of ordinary Emacs behavior, it is
+good to include a command to enable and disable the feature, Provide a
+command named @code{@var{whatever}-mode} which turns the feature on or
+off, and make it autoload (@pxref{Autoload}).  Design the package so
+that simply loading it has no visible effect---that should not enable
+the feature.  Users will request the feature by invoking the command.
+
+@item
+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.
+
+@item
+If a file does replace any of the functions or library programs of
+standard XEmacs, 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
+Please keep the names of your XEmacs Lisp source files to 13 characters
+or less.  This way, if the files are compiled, the compiled files' names
+will be 14 characters or less, which is short enough to fit on all kinds
+of Unix systems.
+
+@item
+Don't use @code{next-line} or @code{previous-line} in programs; nearly
+always, @code{forward-line} is more convenient as well as more
+predictable and robust.  @xref{Text Lines}.
+
+@item
+Don't call functions that set the mark, unless setting the mark is one
+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:
+
+@itemize @bullet
+@item
+@code{beginning-of-buffer}, @code{end-of-buffer}
+@item
+@code{replace-string}, @code{replace-regexp}
+@end itemize
+
+If you just want to move point, or replace a certain string, without any
+of the other features intended for interactive users, you can replace
+these functions with one or two lines of simple Lisp code.
+
+@item
+Use lists rather than vectors, except when there is a particular reason
+to use a vector.  Lisp has more facilities for manipulating lists than
+for vectors, and working with lists is usually more convenient.
+
+Vectors are advantageous for tables that are substantial in size and are
+accessed in random order (not searched front to back), provided there is
+no need to insert or delete elements (only lists allow that).
+
+@item
+The recommended way to print a message in the echo area is with
+the @code{message} function, not @code{princ}.  @xref{The Echo Area}.
+
+@item
+When you encounter an error condition, call the function @code{error}
+(or @code{signal}).  The function @code{error} does not return.
+@xref{Signaling Errors}.
+
+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
+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
+to switch back to the old local keymap.  Or do what the
+@code{edit-options} command does: switch to another buffer and let the
+user switch back at will.  @xref{Recursive Editing}.
+
+@item
+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
+coherent if all libraries use the same conventions.
+
+@item
+Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the
+default indentation parameters.
+
+@item
+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.
+
+@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 XEmacs
+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.
+@end itemize
+
+@node Compilation Tips
+@section Tips for Making Compiled Code Fast
+@cindex execution speed
+@cindex speedups
+
+  Here are ways of improving the execution speed of byte-compiled
+Lisp programs.
+
+@itemize @bullet
+@item
+@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.
+
+@item
+Use iteration rather than recursion whenever possible.
+Function calls are slow in XEmacs Lisp even when a compiled function
+is calling another compiled function.
+
+@item
+Using the primitive list-searching functions @code{memq}, @code{member},
+@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.
+
+@item
+Certain built-in functions are handled specially in byte-compiled code, 
+avoiding the need for an ordinary function call.  It is a good idea to
+use these functions rather than alternatives.  To see whether a function
+is handled specially by the compiler, examine its @code{byte-compile}
+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}):
+
+@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
+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
+a noticeable speedup in something slow enough that users care about
+the speed.  @xref{Inline Functions}.
+@end itemize
+
+@node Documentation Tips
+@section Tips for Documentation Strings
+
+  Here are some tips for the writing of documentation strings.
+
+@itemize @bullet
+@item
+Every command, function, or variable intended for users to know about
+should have a documentation string.
+
+@item
+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.
+
+@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.
+
+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.
+
+@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.
+
+@item
+Write documentation strings in the active voice, not the passive, and in
+the present tense, not the future.  For instance, use ``Return a list
+containing A and B.'' instead of ``A list containing A and B will be
+returned.''
+
+@item
+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
+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.
+
+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.
+ 
+@item
+@strong{Do not} indent subsequent lines of a documentation string so
+that the text is lined up in the source code with the text of the first
+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
+A variable's documentation string should start with @samp{*} if the
+variable is one that users would often want to set interactively.  If
+the value is a long list, or a function, or if the variable would be set
+only in init files, then don't start the documentation string with
+@samp{*}.  @xref{Defining Variables}.
+
+@item
+The documentation string for a variable that is a yes-or-no flag should
+start with words such as ``Non-nil means@dots{}'', to make it clear that
+all non-@code{nil} values are equivalent and indicate explicitly what
+@code{nil} and non-@code{nil} mean.
+
+@item
+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}.
+
+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.
+
+@item
+@iftex
+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 @code{t} and @code{nil} without single-quotes.
+@end iftex
+@ifinfo
+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
+
+@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}.
+
+@item
+In documentation strings for a major mode, you will want to refer to the
+key bindings of that mode's local map, rather than global ones.
+Therefore, use the construct @samp{\\<@dots{}>} once in the
+documentation string to specify which key map to use.  Do this before
+the first use of @samp{\\[@dots{}]}.  The text inside the
+@samp{\\<@dots{}>} should be the name of the variable containing the
+local keymap for the major mode.
+
+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.
+@end itemize
+
+@node Comment Tips
+@section Tips on Writing Comments
+
+  We recommend these conventions for where to put comments and how to
+indent them:
+
+@table @samp
+@item ;
+Comments that start with a single semicolon, @samp{;}, should all be
+aligned to the same column on the right of the source code.  Such
+comments usually explain how the code on the same line does its job.  In
+Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment})
+command automatically inserts such a @samp{;} in the right place, or
+aligns such a comment if it is already present.
+
+This and following examples are taken from the Emacs sources.
+
+@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 ;;
+Comments that start with two semicolons, @samp{;;}, should be aligned to
+the same level of indentation as the code.  Such comments usually
+describe the purpose of the following lines or the state of the program
+at that point.  For example:
+
+@smallexample
+@group
+(prog1 (setq auto-fill-function
+             @dots{}
+             @dots{}
+  ;; update modeline
+  (redraw-modeline)))
+@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:
+
+@smallexample
+@group
+;;; This Lisp code is run in XEmacs
+;;; when it is to operate as a server
+;;; for other processes.
+@end group
+@end smallexample
+
+Another use for triple-semicolon comments is for commenting out lines
+within a function.  We use triple-semicolons for this precisely so that
+they remain at the left margin.
+
+@smallexample
+(defun foo (a)
+;;; This is no longer necessary.
+;;;  (force-mode-line-update)
+  (message "Finished with %s" a))
+@end smallexample
+
+@item ;;;;
+Comments that start with four semicolons, @samp{;;;;}, should be aligned
+to the left margin and are used for headings of major sections of a
+program.  For example:
+
+@smallexample
+;;;; The kill ring
+@end smallexample
+@end table
+
+@noindent
+The indentation commands of the Lisp modes in XEmacs, such as @kbd{M-;}
+(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line})
+automatically indent comments according to these conventions,
+depending on the the number of semicolons.  @xref{Comments,,
+Manipulating Comments, emacs, The XEmacs Reference Manual}.
+
+@node Library Headers
+@section Conventional Headers for XEmacs Libraries
+@cindex header comments
+@cindex library header comments
+
+  XEmacs 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:
+
+@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 XEmacs.
+@var{copying permissions}@dots{}
+@end group
+@end smallexample
+
+  The very first line should have this format:
+
+@example
+;;; @var{filename} --- @var{description}
+@end example
+
+@noindent
+The description should be complete in one line.
+
+  After the copyright notice come several @dfn{header comment} lines,
+each beginning with @samp{;; @var{header-name}:}.  Here is a table of
+the conventional possibilities for @var{header-name}:
+
+@table @samp
+@item Author
+This line states the name and net address of at least the principal
+author of the library.
+
+If there are multiple authors, you can list them on continuation lines
+led by @code{;;} and a tab character, like this:
+
+@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
+This line should contain a single name/address as in the Author line, or
+an address only, or the string @samp{FSF}.  If there is no maintainer
+line, the person(s) in the Author field are presumed to be the
+maintainers.  The example above is mildly bogus because the maintainer
+line is redundant.
+
+The idea behind the @samp{Author} and @samp{Maintainer} lines is to make
+possible a Lisp function to ``send mail to the maintainer'' without
+having to mine the name out by hand.
+
+Be sure to surround the network address with @samp{<@dots{}>} if
+you include the person's full name as well as the network address.
+
+@item Created
+This optional line gives the original creation date of the
+file.  For historical interest only.
+
+@item Version
+If you wish to record version numbers for the individual Lisp program, put
+them in this line.
+
+@item Adapted-By
+In this header line, place the name of the person who adapted the
+library for installation (to make it fit the style conventions, for
+example).
+
+@item Keywords
+This line lists keywords for the @code{finder-by-keyword} help command.
+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.
+@end table
+
+  Just about every Lisp library ought to have the @samp{Author} and
+@samp{Keywords} header comment lines.  Use the others if they are
+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:
+
+@table @samp
+@item ;;; Commentary:
+This begins introductory comments that explain how the library works.
+It should come right after the copying permissions.
+
+@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 XEmacs, 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.
+
+@item ;;; Code:
+This begins the actual code of the program.
+
+@item ;;; @var{filename} ends here
+This is the @dfn{footer line}; it appears at the very end of the file.
+Its purpose is to enable people to detect truncated versions of the file
+from the lack of a footer line.
+@end table