-@c -*-texinfo-*-
+@c -*- mode: texinfo; coding: utf-8 -*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1993, 1995, 1998-1999, 2001-2013 Free Software
+@c Copyright (C) 1990-1993, 1995, 1998-1999, 2001-2016 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Tips
previous chapters, and describes conventions Emacs Lisp programmers
should follow.
+@findex checkdoc
+@findex checkdoc-current-buffer
+@findex checkdoc-file
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.
+all. Alternatively, use the command @kbd{M-x checkdoc-current-buffer RET}
+to check the conventions in the current buffer, or @code{checkdoc-file}
+when you want to check a file in batch mode, e.g., with a command run by
+@kbd{@w{M-x compile RET}}.
@menu
* Coding Conventions:: Conventions for clean and robust programs.
Lisp programs. The names of all global symbols in your program, that
is the names of variables, constants, and functions, should begin with
that chosen prefix. Separate the prefix from the rest of the name
-with a hyphen, @samp{-}. Use two hyphens if the symbol is not meant
-to be used by other packages. This practice helps avoid name
-conflicts, since all global variables in Emacs Lisp share the same
-name space, and all functions share another name space@footnote{The
-benefits of a Common Lisp-style package system are considered not to
-outweigh the costs.}.
+with a hyphen, @samp{-}. This practice helps avoid name conflicts,
+since all global variables in Emacs Lisp share the same name space,
+and all functions share another name space@footnote{The benefits of a
+Common Lisp-style package system are considered not to outweigh the
+costs.}. Use two hyphens to separate prefix and name if the symbol is
+not meant to be used by other packages.
Occasionally, for a command name intended for users to use, it is more
convenient if some words come before the package's name prefix. And
another Lisp package (@pxref{Advising Functions}).
@item
-Avoid using @code{eval-after-load} in libraries and packages
-(@pxref{Hooks for Loading}). This feature is meant for personal
-customizations; using it in a Lisp program is unclean, because it
-modifies the behavior of another Lisp file in a way that's not visible
-in that file. This is an obstacle for debugging, much like advising a
-function in the other package.
+Avoid using @code{eval-after-load} and @code{with-eval-after-load} in
+libraries and packages (@pxref{Hooks for Loading}). This feature is
+meant for personal customizations; using it in a Lisp program is
+unclean, because it modifies the behavior of another Lisp file in a
+way that's not visible in that file. This is an obstacle for
+debugging, much like advising a function in the other package.
@item
If a file does replace any of the standard functions or library
coherent if all libraries use the same conventions.
@item
-If your program contains non-ASCII characters in string or character
-constants, you should make sure Emacs always decodes these characters
-the same way, regardless of the user's settings. The easiest way to
-do this is to use the coding system @code{utf-8-emacs} (@pxref{Coding
-System Basics}), and specify that coding in the @samp{-*-} line or the
+The default file coding system for Emacs Lisp source files is UTF-8
+(@pxref{Text Representations}). In the rare event that your program
+contains characters which are @emph{not} in UTF-8, you should specify
+an appropriate coding system in the source file's @samp{-*-} line or
local variables list. @xref{File Variables, , Local Variables in
Files, emacs, The GNU Emacs Manual}.
-@example
-;; XXX.el -*- coding: utf-8-emacs; -*-
-@end example
-
@item
Indent the file using the default indentation parameters.
@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.
+Sequences consisting of @kbd{C-c} followed by any other
+@acronym{ASCII} punctuation or symbol 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
Don't bind @kbd{C-h} following any prefix character (including
@item
In @code{interactive}, if you use a Lisp expression to produce a list
-of arguments, don't try to provide the ``correct'' default values for
+of arguments, don't try to provide the correct default values for
region or position arguments. Instead, provide @code{nil} for those
arguments if they were not specified, and have the function body
compute the default value when the argument is @code{nil}. For
60 characters. The first line should not be wider than 67 characters
or it will look bad in the output of @code{apropos}.
-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 sections if the documentation string is long.
+@vindex emacs-lisp-docstring-fill-column
+You can fill the text if that looks good. Emacs Lisp mode fills
+documentation strings to the width specified by
+@code{emacs-lisp-docstring-fill-column}. However, you can sometimes
+make a documentation string much more readable by adjusting its line
+breaks with care. Use blank lines between sections if the
+documentation string is long.
@item
The first line of the documentation string should consist of one or two
@anchor{Docstring hyperlinks}
@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
-@ifnottex
+@cindex curly quotes
+@cindex curved quotes
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 use a different
-convention, with single-quotes for all symbols.)
-@end ifnottex
+would be printed (which usually means in lower case), surrounding
+it with curved single quotes (@t{‘} and @t{’}). There are
+two exceptions: write @code{t} and @code{nil} without surrounding
+punctuation. For example: @samp{CODE can be ‘lambda’, nil, or t}.
+@xref{Quotation Marks,,, emacs, The GNU Emacs Manual}, for how to
+enter curved single quotes.
+
+Documentation strings can also use an older single-quoting convention,
+which quotes symbols with grave accent @t{`} and apostrophe
+@t{'}: @t{`like-this'} rather than @t{‘like-this’}. This
+older convention was designed for now-obsolete displays in which grave
+accent and apostrophe were mirror images.
+Documentation using this convention is converted to the user's
+preferred format when it is copied into a help buffer. @xref{Keys in
+Documentation}.
@cindex hyperlinks in documentation strings
Help mode automatically creates a hyperlink when a documentation string
-uses a symbol name inside single quotes, if the symbol has either a
+uses a single-quoted symbol name, 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
documentation will be shown, even if the symbol is also defined as a
variable or as a function.
-To make a hyperlink to Info documentation, write the name of the Info
-node (or anchor) in single quotes, preceded by @samp{info node},
-@samp{Info node}, @samp{info anchor} or @samp{Info anchor}. The Info
-file name defaults to @samp{emacs}. For example,
+To make a hyperlink to Info documentation, write the single-quoted
+name of the Info node (or anchor), preceded by
+@samp{info node}, @samp{Info node}, @samp{info anchor} or @samp{Info
+anchor}. 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
-Finally, to create a hyperlink to URLs, write the URL in single
-quotes, preceded by @samp{URL}. For example,
+Finally, to create a hyperlink to URLs, write the single-quoted URL,
+preceded by @samp{URL}. For example,
@smallexample
The home page for the GNU project has more information (see URL
@item
The documentation string for a function that is a yes-or-no predicate
should start with words such as ``Return t if'', to indicate
-explicitly what constitutes ``truth''. The word ``return'' avoids
+explicitly what constitutes truth. The word ``return'' avoids
starting the sentence with lower-case ``t'', which could be somewhat
distracting.
@smallexample
@group
-(setq base-version-list ; there was a base
+(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
+ ; a subversion.
@end group
@end smallexample
@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 depends on whether the comment should be considered a
-``heading'' by Outline minor mode. By default, comments starting with
+the left margin. We use them
+for comments which should be considered a
+heading by Outline minor mode. By default, comments starting with
at least three semicolons (followed by a single space and a
non-whitespace character) are considered headings, comments starting
-with two or fewer are not.
-
-Another use for triple-semicolon comments is for commenting out lines
-within a function. We use three semicolons for this precisely so that
-they remain at the left margin. By default, Outline minor mode does
-not consider a comment to be a heading (even if it starts with at
-least three semicolons) if the semicolons are followed by at least two
-spaces. Thus, if you add an introductory comment to the commented out
-code, make sure to indent it by at least two spaces after the three
-semicolons.
-
-@smallexample
-(defun foo (a)
-;;; This is no longer necessary.
-;;; (force-mode-line-update)
- (message "Finished with %s" a))
-@end smallexample
+with two or fewer are not. Historically, triple-semicolon comments have
+also been used for commenting out lines within a function, but this use
+is discouraged.
When commenting out entire functions, use two semicolons.
@group
;;; foo.el --- Support for the Foo programming language
-;; Copyright (C) 2010-2013 Your Name
+;; Copyright (C) 2010-2016 Your Name
@end group
;; Author: Your Name <yourname@@example.com>
but only the main one.
@item Keywords
+@vindex checkdoc-package-keywords-flag
+@findex checkdoc-package-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.
+Please use that command to see a list of the meaningful keywords. The
+command @kbd{M-x checkdoc-package-keywords RET} will find and display
+any keywords that are not in @code{finder-known-keywords}. If you set
+the variable @code{checkdoc-package-keywords-flag} non-@code{nil},
+checkdoc commands will include the keyword verification in its checks.
This field is how people will find your package when they're looking
for things by topic. To separate the keywords, you can use spaces,
@item ;;; Change Log:
This begins an optional log of changes to the file over time. Don't
put too much information in this section---it is better to keep the
-detailed logs in a separate @file{ChangeLog} file (as Emacs does),
-and/or to use a version control system. @samp{History} is an
-alternative to @samp{Change Log}.
+detailed logs in a version control system (as Emacs does) or in a
+separate @file{ChangeLog} file. @samp{History} is an alternative to
+@samp{Change Log}.
@item ;;; Code:
This begins the actual code of the program.