2015-09-25 09:32:13 +00:00
|
|
|
|
@c -*- mode: texinfo; coding: utf-8 -*-
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@c This is part of the GNU Emacs Lisp Reference Manual.
|
2018-01-01 08:21:42 +00:00
|
|
|
|
@c Copyright (C) 1990-1993, 1995, 1998-1999, 2001-2018 Free Software
|
2013-01-01 09:11:05 +00:00
|
|
|
|
@c Foundation, Inc.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@c See the file elisp.texi for copying conditions.
|
2012-05-27 01:34:14 +00:00
|
|
|
|
@node Tips
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@appendix Tips and Conventions
|
|
|
|
|
@cindex tips for writing Lisp
|
|
|
|
|
@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, and describes conventions Emacs Lisp programmers
|
|
|
|
|
should follow.
|
|
|
|
|
|
2015-11-28 12:32:04 +00:00
|
|
|
|
@findex checkdoc
|
|
|
|
|
@findex checkdoc-current-buffer
|
|
|
|
|
@findex checkdoc-file
|
2018-01-31 18:59:12 +00:00
|
|
|
|
You can automatically check some of the conventions described below
|
|
|
|
|
by running the command @kbd{M-x checkdoc @key{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. Alternatively, use the command @kbd{M-x
|
|
|
|
|
checkdoc-current-buffer @key{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
|
|
|
|
|
@key{RET}}}.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@menu
|
|
|
|
|
* Coding Conventions:: Conventions for clean and robust programs.
|
|
|
|
|
* Key Binding Conventions:: Which keys should be bound by which programs.
|
|
|
|
|
* Programming Tips:: Making Emacs code fit smoothly in Emacs.
|
|
|
|
|
* Compilation Tips:: Making compiled code run fast.
|
|
|
|
|
* Warning Tips:: Turning off compiler warnings.
|
|
|
|
|
* Documentation Tips:: Writing readable documentation strings.
|
Untabify doc/lispref/*.texi.
* abbrevs.texi, commands.texi, compile.texi, debugging.texi:
* display.texi, edebug.texi, elisp.texi, eval.texi, files.texi:
* frames.texi, functions.texi, internals.texi, keymaps.texi:
* loading.texi, minibuf.texi, numbers.texi, os.texi, processes.texi:
* searching.texi, sequences.texi, strings.texi, syntax.texi:
* text.texi, tips.texi, vol1.texi, vol2.texi, windows.texi:
Untabify Texinfo files.
2010-06-23 03:36:56 +00:00
|
|
|
|
* Comment Tips:: Conventions for writing comments.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
* Library Headers:: Standard headers for library packages.
|
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
|
|
@node Coding Conventions
|
|
|
|
|
@section Emacs Lisp Coding Conventions
|
|
|
|
|
|
|
|
|
|
@cindex coding conventions in Emacs Lisp
|
|
|
|
|
Here are conventions that you should follow when writing Emacs Lisp
|
|
|
|
|
code intended for widespread use:
|
|
|
|
|
|
|
|
|
|
@itemize @bullet
|
|
|
|
|
@item
|
2009-04-26 02:35:18 +00:00
|
|
|
|
Simply loading a package should not change Emacs's editing behavior.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
Include a command or commands to enable and disable the feature,
|
|
|
|
|
or to invoke it.
|
|
|
|
|
|
|
|
|
|
This convention is mandatory for any file that includes custom
|
|
|
|
|
definitions. If fixing such a file to follow this convention requires
|
|
|
|
|
an incompatible change, go ahead and make the incompatible change;
|
|
|
|
|
don't postpone it.
|
|
|
|
|
|
|
|
|
|
@item
|
2009-04-26 02:35:18 +00:00
|
|
|
|
You should choose a short word to distinguish your program from other
|
2013-04-15 17:01:00 +00:00
|
|
|
|
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
|
2013-06-26 15:22:21 +00:00
|
|
|
|
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.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
Occasionally, for a command name intended for users to use, it is more
|
2017-09-22 09:41:00 +00:00
|
|
|
|
convenient if some words come before the package's name prefix. For
|
|
|
|
|
example, it is our convention to have commands that list objects named
|
|
|
|
|
as @samp{list-@var{something}}, e.g., a package called @samp{frob}
|
|
|
|
|
could have a command @samp{list-frobs}, when its other global symbols
|
|
|
|
|
begin with @samp{frob-}. Also, constructs that define functions,
|
|
|
|
|
variables, etc., work better if they start with @samp{defun} or
|
|
|
|
|
@samp{defvar}, so put the name prefix later on in the name.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
This recommendation applies even to names for traditional Lisp
|
|
|
|
|
primitives that are not primitives in Emacs Lisp---such as
|
|
|
|
|
@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@@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 can use two or three
|
|
|
|
|
alternative common prefixes, so long as they make sense.
|
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
Put a call to @code{provide} at the end of each separate Lisp file.
|
2009-04-26 02:35:18 +00:00
|
|
|
|
@xref{Named Features}.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
If a file requires certain other Lisp 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.
|
2010-05-03 22:01:23 +00:00
|
|
|
|
@xref{Named Features}.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
2009-04-26 02:35:18 +00:00
|
|
|
|
If a file @var{foo} uses a macro defined in another file @var{bar},
|
|
|
|
|
but does not use any functions or variables defined in @var{bar}, then
|
|
|
|
|
@var{foo} should contain the following expression:
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@example
|
|
|
|
|
(eval-when-compile (require '@var{bar}))
|
|
|
|
|
@end example
|
|
|
|
|
|
|
|
|
|
@noindent
|
2009-04-26 02:35:18 +00:00
|
|
|
|
This tells Emacs to load @var{bar} just before byte-compiling
|
|
|
|
|
@var{foo}, so that the macro definition is available during
|
|
|
|
|
compilation. Using @code{eval-when-compile} avoids loading @var{bar}
|
|
|
|
|
when the compiled version of @var{foo} is @emph{used}. It should be
|
|
|
|
|
called before the first use of the macro in the file. @xref{Compiling
|
|
|
|
|
Macros}.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
2012-03-03 01:29:55 +00:00
|
|
|
|
@item
|
|
|
|
|
Avoid loading additional libraries at run time unless they are really
|
|
|
|
|
needed. If your file simply cannot work without some other library,
|
|
|
|
|
then just @code{require} that library at the top-level and be done
|
|
|
|
|
with it. But if your file contains several independent features, and
|
|
|
|
|
only one or two require the extra library, then consider putting
|
|
|
|
|
@code{require} statements inside the relevant functions rather than at
|
|
|
|
|
the top-level. Or use @code{autoload} statements to load the extra
|
|
|
|
|
library when needed. This way people who don't use those aspects of
|
|
|
|
|
your file do not need to load the extra library.
|
|
|
|
|
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@item
|
2012-10-22 02:18:58 +00:00
|
|
|
|
If you need Common Lisp extensions, use the @code{cl-lib} library
|
|
|
|
|
rather than the old @code{cl} library. The latter does not
|
|
|
|
|
use a clean namespace (i.e., its definitions do not
|
|
|
|
|
start with a @samp{cl-} prefix). If your package loads @code{cl} at
|
|
|
|
|
run time, that could cause name clashes for users who don't use that
|
|
|
|
|
package.
|
|
|
|
|
|
|
|
|
|
There is no problem with using the @code{cl} package at @emph{compile}
|
|
|
|
|
time, with @code{(eval-when-compile (require 'cl))}. That's
|
2007-09-06 04:25:08 +00:00
|
|
|
|
sufficient for using the macros in the @code{cl} package, because the
|
2012-10-22 02:18:58 +00:00
|
|
|
|
compiler expands them before generating the byte-code. It is still
|
|
|
|
|
better to use the more modern @code{cl-lib} in this case, though.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@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
|
2009-04-26 02:35:18 +00:00
|
|
|
|
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} (which stands for ``predicate''). 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}.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
If the purpose of a variable is to store a single function, give it a
|
|
|
|
|
name that ends in @samp{-function}. If the purpose of a variable is
|
|
|
|
|
to store a list of functions (i.e., the variable is a hook), please
|
|
|
|
|
follow the naming conventions for hooks. @xref{Hooks}.
|
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
@cindex unloading packages, preparing for
|
|
|
|
|
If loading the file adds functions to hooks, define a function
|
2016-11-07 17:39:54 +00:00
|
|
|
|
@code{@var{feature}-unload-function}, where @var{feature} is the name
|
|
|
|
|
of the feature the package provides, and make it undo any such
|
|
|
|
|
changes. Using @code{unload-feature} to unload the file will run this
|
|
|
|
|
function. @xref{Unloading}.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
It is a bad idea to define aliases for the Emacs primitives. Normally
|
|
|
|
|
you should use the standard names instead. The case where an alias
|
|
|
|
|
may be useful is where it facilitates backwards compatibility or
|
|
|
|
|
portability.
|
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
If a package needs to define an alias or a new function for
|
|
|
|
|
compatibility with some other version of Emacs, name it with the package
|
|
|
|
|
prefix, not with the raw name with which it occurs in the other version.
|
|
|
|
|
Here is an example from Gnus, which provides many examples of such
|
|
|
|
|
compatibility issues.
|
|
|
|
|
|
|
|
|
|
@example
|
|
|
|
|
(defalias 'gnus-point-at-bol
|
|
|
|
|
(if (fboundp 'point-at-bol)
|
|
|
|
|
'point-at-bol
|
|
|
|
|
'line-beginning-position))
|
|
|
|
|
@end example
|
|
|
|
|
|
|
|
|
|
@item
|
2009-04-26 02:35:18 +00:00
|
|
|
|
Redefining or advising an Emacs primitive is a bad idea. It may do
|
2007-09-06 04:25:08 +00:00
|
|
|
|
the right thing for a particular program, but there is no telling what
|
2009-04-26 02:35:18 +00:00
|
|
|
|
other programs might break as a result.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
2009-04-26 02:35:18 +00:00
|
|
|
|
It is likewise a bad idea for one Lisp package to advise a function in
|
|
|
|
|
another Lisp package (@pxref{Advising Functions}).
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
2016-04-30 17:20:12 +00:00
|
|
|
|
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.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
2009-04-26 02:35:18 +00:00
|
|
|
|
If a file does replace any of the standard functions or library
|
|
|
|
|
programs of Emacs, prominent comments at the beginning of the file
|
|
|
|
|
should say which functions are replaced, and how the behavior of the
|
2007-09-06 04:25:08 +00:00
|
|
|
|
replacements differs from that of the originals.
|
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
Constructs that define a function or variable should be macros,
|
2012-03-03 01:29:55 +00:00
|
|
|
|
not functions, and their names should start with @samp{define-}.
|
|
|
|
|
The macro should receive the name to be
|
2007-09-06 04:25:08 +00:00
|
|
|
|
defined as the first argument. That will help various tools find the
|
|
|
|
|
definition automatically. Avoid constructing the names in the macro
|
|
|
|
|
itself, since that would confuse these tools.
|
|
|
|
|
|
|
|
|
|
@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
|
2012-03-03 01:29:55 +00:00
|
|
|
|
only for special-purpose buffers.) People will find Emacs more
|
2007-09-06 04:25:08 +00:00
|
|
|
|
coherent if all libraries use the same conventions.
|
|
|
|
|
|
|
|
|
|
@item
|
2013-12-25 10:24:52 +00:00
|
|
|
|
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
|
2012-03-03 01:29:55 +00:00
|
|
|
|
local variables list. @xref{File Variables, , Local Variables in
|
2009-04-26 02:35:18 +00:00
|
|
|
|
Files, emacs, The GNU Emacs Manual}.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
2012-03-03 01:29:55 +00:00
|
|
|
|
Indent the file using the default indentation parameters.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
2009-04-26 02:35:18 +00:00
|
|
|
|
Don't make a habit of putting close-parentheses on lines by
|
|
|
|
|
themselves; Lisp programmers find this disconcerting.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
Please put a copyright notice and copying permission notice on the
|
2012-03-03 01:29:55 +00:00
|
|
|
|
file if you distribute copies. @xref{Library Headers}.
|
2008-05-16 06:02:53 +00:00
|
|
|
|
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@end itemize
|
|
|
|
|
|
|
|
|
|
@node Key Binding Conventions
|
|
|
|
|
@section Key Binding Conventions
|
|
|
|
|
@cindex key binding, conventions for
|
|
|
|
|
|
|
|
|
|
@itemize @bullet
|
|
|
|
|
@item
|
|
|
|
|
@cindex mouse-2
|
|
|
|
|
@cindex references, following
|
2009-04-26 02:35:18 +00:00
|
|
|
|
Many special major modes, like Dired, Info, Compilation, and Occur,
|
|
|
|
|
are designed to handle read-only text that contains @dfn{hyper-links}.
|
|
|
|
|
Such a major mode should redefine @kbd{mouse-2} and @key{RET} to
|
|
|
|
|
follow the links. It should also set up a @code{follow-link}
|
|
|
|
|
condition, so that the link obeys @code{mouse-1-click-follows-link}.
|
|
|
|
|
@xref{Clickable Text}. @xref{Buttons}, for an easy method of
|
|
|
|
|
implementing such clickable links.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
@cindex reserved keys
|
|
|
|
|
@cindex keys, reserved
|
2009-04-26 02:35:18 +00:00
|
|
|
|
Don't define @kbd{C-c @var{letter}} as a key in Lisp programs.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
Sequences consisting of @kbd{C-c} and a letter (either upper or lower
|
|
|
|
|
case) are reserved for users; they are the @strong{only} sequences
|
|
|
|
|
reserved for users, so do not block them.
|
|
|
|
|
|
|
|
|
|
Changing all the Emacs major modes to respect this convention was a
|
|
|
|
|
lot of work; abandoning this convention would make that work go to
|
|
|
|
|
waste, and inconvenience users. Please comply with it.
|
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
Function keys @key{F5} through @key{F9} without modifier keys are
|
|
|
|
|
also reserved for users to define.
|
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
Sequences consisting of @kbd{C-c} followed by a control character or a
|
|
|
|
|
digit are reserved for major modes.
|
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
|
|
|
|
|
@kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes.
|
|
|
|
|
|
|
|
|
|
@item
|
2016-02-09 18:12:17 +00:00
|
|
|
|
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.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
2009-04-26 02:35:18 +00:00
|
|
|
|
Don't 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.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
2009-04-26 02:35:18 +00:00
|
|
|
|
Don't bind a key sequence ending in @key{ESC} except following another
|
|
|
|
|
@key{ESC}. (That is, it is OK to bind a sequence ending in
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@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.
|
|
|
|
|
|
2011-09-17 19:49:57 +00:00
|
|
|
|
@item
|
|
|
|
|
Similarly, don't bind a key sequence ending in @key{C-g}, since that
|
|
|
|
|
is commonly used to cancel a key sequence.
|
|
|
|
|
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@item
|
2012-03-03 01:29:55 +00:00
|
|
|
|
Anything that acts like a temporary mode or state that the user can
|
2007-09-06 04:25:08 +00:00
|
|
|
|
enter and leave should define @kbd{@key{ESC} @key{ESC}} or
|
|
|
|
|
@kbd{@key{ESC} @key{ESC} @key{ESC}} as a way to escape.
|
|
|
|
|
|
2012-03-03 01:29:55 +00:00
|
|
|
|
For a state that accepts ordinary Emacs commands, or more generally any
|
2007-09-06 04:25:08 +00:00
|
|
|
|
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.
|
|
|
|
|
@end itemize
|
|
|
|
|
|
|
|
|
|
@node Programming Tips
|
|
|
|
|
@section Emacs Programming Tips
|
|
|
|
|
@cindex programming conventions
|
|
|
|
|
|
|
|
|
|
Following these conventions will make your program fit better
|
|
|
|
|
into Emacs when it runs.
|
|
|
|
|
|
|
|
|
|
@itemize @bullet
|
|
|
|
|
@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 any of these functions:
|
|
|
|
|
|
|
|
|
|
@itemize @bullet
|
|
|
|
|
@item
|
|
|
|
|
@code{beginning-of-buffer}, @code{end-of-buffer}
|
|
|
|
|
@item
|
|
|
|
|
@code{replace-string}, @code{replace-regexp}
|
|
|
|
|
@item
|
|
|
|
|
@code{insert-file}, @code{insert-buffer}
|
|
|
|
|
@end itemize
|
|
|
|
|
|
|
|
|
|
If you just want to move point, or replace a certain string, or insert
|
|
|
|
|
a file or buffer's contents, 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 show 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}.
|
|
|
|
|
|
2009-04-26 02:35:18 +00:00
|
|
|
|
Don't use @code{message}, @code{throw}, @code{sleep-for}, or
|
|
|
|
|
@code{beep} to report errors.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
An error message should start with a capital letter but should not end
|
|
|
|
|
with a period.
|
|
|
|
|
|
|
|
|
|
@item
|
2012-03-03 01:29:55 +00:00
|
|
|
|
A question asked in the minibuffer with @code{yes-or-no-p} or
|
|
|
|
|
@code{y-or-n-p} should start with a capital letter and end with
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@samp{? }.
|
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
When you mention a default value in a minibuffer prompt,
|
|
|
|
|
put it and the word @samp{default} inside parentheses.
|
|
|
|
|
It should look like this:
|
|
|
|
|
|
|
|
|
|
@example
|
|
|
|
|
Enter the answer (default 42):
|
|
|
|
|
@end example
|
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
In @code{interactive}, if you use a Lisp expression to produce a list
|
2015-09-15 15:46:48 +00:00
|
|
|
|
of arguments, don't try to provide the correct default values for
|
2007-09-06 04:25:08 +00:00
|
|
|
|
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
|
|
|
|
|
instance, write this:
|
|
|
|
|
|
|
|
|
|
@example
|
|
|
|
|
(defun foo (pos)
|
|
|
|
|
(interactive
|
|
|
|
|
(list (if @var{specified} @var{specified-pos})))
|
|
|
|
|
(unless pos (setq pos @var{default-pos}))
|
|
|
|
|
...)
|
|
|
|
|
@end example
|
|
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
|
rather than this:
|
|
|
|
|
|
|
|
|
|
@example
|
|
|
|
|
(defun foo (pos)
|
|
|
|
|
(interactive
|
|
|
|
|
(list (if @var{specified} @var{specified-pos}
|
|
|
|
|
@var{default-pos})))
|
|
|
|
|
...)
|
|
|
|
|
@end example
|
|
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
|
This is so that repetition of the command will recompute
|
|
|
|
|
these defaults based on the current circumstances.
|
|
|
|
|
|
|
|
|
|
You do not need to take such precautions when you use interactive
|
|
|
|
|
specs @samp{d}, @samp{m} and @samp{r}, because they make special
|
|
|
|
|
arrangements to recompute the argument values on repetition of the
|
|
|
|
|
command.
|
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
Many commands that take a long time to execute display a message that
|
2009-04-26 02:35:18 +00:00
|
|
|
|
says something like @samp{Operating...} when they start, and change it
|
|
|
|
|
to @samp{Operating...done} when they finish. Please keep the style of
|
2007-09-06 04:25:08 +00:00
|
|
|
|
these messages uniform: @emph{no} space around the ellipsis, and
|
2009-04-26 02:35:18 +00:00
|
|
|
|
@emph{no} period after @samp{done}. @xref{Progress}, for an easy way
|
|
|
|
|
to generate such messages.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e}
|
2012-03-03 01:29:55 +00:00
|
|
|
|
command does: use a new local keymap that contains a command defined
|
|
|
|
|
to switch back to the old local keymap. Or simply switch to another
|
|
|
|
|
buffer and let the user switch back at will. @xref{Recursive Editing}.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@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
|
2012-11-20 08:02:54 +00:00
|
|
|
|
Profile your program, to find out where the time is being spent.
|
|
|
|
|
@xref{Profiling}.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
Use iteration rather than recursion whenever possible.
|
|
|
|
|
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{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,
|
|
|
|
|
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}):
|
|
|
|
|
|
|
|
|
|
@example
|
|
|
|
|
@group
|
|
|
|
|
(get 'aref 'byte-compile)
|
|
|
|
|
@result{} byte-compile-two-args
|
|
|
|
|
@end group
|
|
|
|
|
@end example
|
|
|
|
|
|
2012-03-03 01:29:55 +00:00
|
|
|
|
@noindent
|
|
|
|
|
Note that in this case (and many others), you must first load the
|
|
|
|
|
@file{bytecomp} library, which defines the @code{byte-compile} property.
|
|
|
|
|
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@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 Warning Tips
|
|
|
|
|
@section Tips for Avoiding Compiler Warnings
|
|
|
|
|
@cindex byte compiler warnings, how to avoid
|
|
|
|
|
|
|
|
|
|
@itemize @bullet
|
|
|
|
|
@item
|
|
|
|
|
Try to avoid compiler warnings about undefined free variables, by adding
|
|
|
|
|
dummy @code{defvar} definitions for these variables, like this:
|
|
|
|
|
|
|
|
|
|
@example
|
|
|
|
|
(defvar foo)
|
|
|
|
|
@end example
|
|
|
|
|
|
|
|
|
|
Such a definition has no effect except to tell the compiler
|
|
|
|
|
not to warn about uses of the variable @code{foo} in this file.
|
|
|
|
|
|
2012-03-03 01:29:55 +00:00
|
|
|
|
@item
|
|
|
|
|
Similarly, to avoid a compiler warning about an undefined function
|
|
|
|
|
that you know @emph{will} be defined, use a @code{declare-function}
|
|
|
|
|
statement (@pxref{Declaring Functions}).
|
|
|
|
|
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@item
|
2017-11-27 16:24:29 +00:00
|
|
|
|
If you use many functions, macros, and variables from a certain file,
|
|
|
|
|
you can add a @code{require} (@pxref{Named Features, require}) for
|
|
|
|
|
that package to avoid compilation warnings for them, like this:
|
|
|
|
|
|
|
|
|
|
@example
|
|
|
|
|
(require 'foo)
|
|
|
|
|
@end example
|
|
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
|
If you need only macros from some file, you can require it only at
|
|
|
|
|
compile time (@pxref{Eval During Compile}). For instance,
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@example
|
|
|
|
|
(eval-when-compile
|
|
|
|
|
(require 'foo))
|
|
|
|
|
@end example
|
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
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 adding a definition would be
|
|
|
|
|
unclean if the variable has a short name, since Lisp packages should
|
|
|
|
|
not define short variable names. The right thing to do is to rename
|
|
|
|
|
this variable to start with the name prefix used for the other
|
|
|
|
|
functions and variables in your package.
|
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
The last resort for avoiding a warning, when you want to do something
|
2012-03-03 01:29:55 +00:00
|
|
|
|
that is usually a mistake but you know is not a mistake in your usage,
|
|
|
|
|
is to put it inside @code{with-no-warnings}. @xref{Compiler Errors}.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@end itemize
|
|
|
|
|
|
|
|
|
|
@node Documentation Tips
|
|
|
|
|
@section Tips for Documentation Strings
|
|
|
|
|
@cindex documentation strings, conventions and tips
|
|
|
|
|
|
|
|
|
|
@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
|
|
|
|
|
Every command, function, or variable intended for users to know about
|
|
|
|
|
should have a documentation string.
|
|
|
|
|
|
|
|
|
|
@item
|
2012-03-03 01:29:55 +00:00
|
|
|
|
An internal variable or subroutine of a Lisp program might as well
|
|
|
|
|
have a documentation string. Documentation strings take up very
|
|
|
|
|
little space in a running Emacs.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@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 should not be wider than 67 characters
|
|
|
|
|
or it will look bad in the output of @code{apropos}.
|
|
|
|
|
|
2014-01-03 05:49:06 +00:00
|
|
|
|
@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.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@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 that line's contents don't
|
|
|
|
|
stand on their own, the result looks bad. In particular, start the
|
2012-03-03 01:29:55 +00:00
|
|
|
|
first line with a capital letter and end it with a period.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
For a function, the first line should briefly answer the question,
|
|
|
|
|
``What does this function do?'' For a variable, the first line should
|
|
|
|
|
briefly answer the question, ``What does this value mean?''
|
|
|
|
|
|
|
|
|
|
Don't limit the documentation string 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 for the rest of the text too.
|
|
|
|
|
|
|
|
|
|
@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
|
|
|
|
|
The first line should mention all the important arguments of the
|
|
|
|
|
function, and should mention them in the order that they are written
|
|
|
|
|
in a function call. If the function has many arguments, then it is
|
|
|
|
|
not feasible to mention them all in the first line; in that case, the
|
|
|
|
|
first line should mention the first few arguments, including the most
|
|
|
|
|
important arguments.
|
|
|
|
|
|
|
|
|
|
@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
|
2012-03-03 01:29:55 +00:00
|
|
|
|
@code{eval} refers to its first argument as @samp{FORM}, because the
|
2007-09-06 04:25:08 +00:00
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
@example
|
|
|
|
|
The argument TABLE should be an alist whose elements
|
|
|
|
|
have the form (KEY . VALUE). Here, KEY is ...
|
|
|
|
|
@end example
|
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
Never change the case of a Lisp symbol when you mention it in a doc
|
2012-04-26 00:31:47 +00:00
|
|
|
|
string. If the symbol's name is @code{foo}, write ``foo'', not
|
2007-09-06 04:25:08 +00:00
|
|
|
|
``Foo'' (which is a different symbol).
|
|
|
|
|
|
|
|
|
|
This might appear to contradict the policy of writing function
|
|
|
|
|
argument values, but there is no real contradiction; the argument
|
2012-03-03 01:29:55 +00:00
|
|
|
|
@emph{value} is not the same thing as the @emph{symbol} that the
|
2007-09-06 04:25:08 +00:00
|
|
|
|
function uses to hold the value.
|
|
|
|
|
|
|
|
|
|
If this puts a lower-case letter at the beginning of a sentence
|
|
|
|
|
and that annoys you, rewrite the sentence so that the symbol
|
|
|
|
|
is not at the start of it.
|
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
Do not start or end a documentation string with whitespace.
|
|
|
|
|
|
|
|
|
|
@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!
|
|
|
|
|
|
|
|
|
|
@anchor{Docstring hyperlinks}
|
|
|
|
|
@item
|
2015-06-18 06:50:45 +00:00
|
|
|
|
@cindex curly quotes
|
|
|
|
|
@cindex curved quotes
|
2007-09-06 04:25:08 +00:00
|
|
|
|
When a documentation string refers to a Lisp symbol, write it as it
|
Support curved quotes in doc strings
Emacs's traditional doc string style has been to quote symbols
`like this'. This worked well on now-obsolete terminals where
` and ' were symmetric quotes, but nowadays curved quotes
‘like this’ look better. Support quoting the new way too.
(Bug#20385)
* doc/lispref/tips.texi (Documentation Tips): Symbols can be quoted
‘like-this’ as well as `like-this'.
* etc/NEWS: Mention this.
* lisp/cedet/mode-local.el (overload-docstring-extension)
(mode-local-print-binding, mode-local-describe-bindings-2):
* lisp/cus-theme.el (describe-theme-1):
* lisp/descr-text.el (describe-text-properties-1, describe-char):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine):
* lisp/emacs-lisp/cl-generic.el (cl--generic-describe):
* lisp/emacs-lisp/eieio-opt.el (eieio-help-class)
(eieio-help-constructor):
* lisp/emacs-lisp/package.el (describe-package-1):
* lisp/faces.el (describe-face):
* lisp/help-fns.el (help-fns--key-bindings)
(help-fns--compiler-macro, help-fns--parent-mode, help-fns--obsolete):
(help-fns--interactive-only, describe-function-1):
(describe-variable):
* lisp/help.el (describe-mode):
* lisp/international/mule-cmds.el (describe-input-method)
(describe-language-environment):
* lisp/international/mule-diag.el (describe-character-set)
(print-coding-system-briefly, list-input-methods)
(list-input-methods-1):
Insert curved quotes rather than grave accent and apostrophe.
* lisp/cedet/srecode/texi.el (srecode-texi-texify-docstring):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine)
(checkdoc-proper-noun-region-engine):
* lisp/emacs-lisp/lisp-mode.el (lisp-el-font-lock-keywords-2)
(lisp-cl-font-lock-keywords-2):
* lisp/finder.el (finder-font-lock-keywords):
* lisp/gnus/gnus-art.el (gnus-button-alist):
* lisp/help-fns.el (help-do-arg-highlight)
(describe-function-1, describe-variable):
* lisp/help-mode.el (help-xref-symbol-regexp)
(help-xref-info-regexp, help-xref-url-regexp):
* lisp/help.el (describe-mode):
* lisp/international/mule-cmds.el (help-xref-mule-regexp-template):
* lisp/wid-edit.el (widget-documentation-link-regexp):
Parse symbols quoted ‘like-this’ as well as `like-this'.
* lisp/progmodes/elisp-mode.el (emacs-lisp-mode):
Add "‘" and "’" to electric-pair-text-pairs.
(elisp--form-quoted-p): Also allow "‘" as a quoting char.
(elisp-completion-at-point, elisp--preceding-sexp):
Also treat "‘" and "’" as quoting chars.
2015-05-28 07:06:14 +00:00
|
|
|
|
would be printed (which usually means in lower case), surrounding
|
2015-06-18 06:50:45 +00:00
|
|
|
|
it with curved single quotes (@t{‘} and @t{’}). There are
|
Minor quoting etc. fixes to lispref manual
* doc/lispref/tips.texi (Documentation Tips):
Distinguish more clearly among grave accent, apostrophe,
and single quote.
* doc/lispref/README, doc/lispref/buffers.texi:
* doc/lispref/commands.texi, doc/lispref/control.texi:
* doc/lispref/customize.texi, doc/lispref/display.texi:
* doc/lispref/elisp.texi, doc/lispref/files.texi:
* doc/lispref/frames.texi, doc/lispref/hash.texi:
* doc/lispref/help.texi, doc/lispref/internals.texi:
* doc/lispref/loading.texi, doc/lispref/makefile.w32-in:
* doc/lispref/markers.texi, doc/lispref/modes.texi:
* doc/lispref/nonascii.texi, doc/lispref/objects.texi:
* doc/lispref/os.texi, doc/lispref/positions.texi:
* doc/lispref/strings.texi, doc/lispref/syntax.texi:
* doc/lispref/text.texi, doc/lispref/tips.texi:
* doc/lispref/two-volume-cross-refs.txt, doc/lispref/windows.texi:
Use American-style double quoting in ordinary text,
and quote 'like this' when single-quoting in ASCII text.
Also, fix some minor spacing issues.
2015-04-10 18:27:21 +00:00
|
|
|
|
two exceptions: write @code{t} and @code{nil} without surrounding
|
2015-06-18 06:50:45 +00:00
|
|
|
|
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.
|
Support curved quotes in doc strings
Emacs's traditional doc string style has been to quote symbols
`like this'. This worked well on now-obsolete terminals where
` and ' were symmetric quotes, but nowadays curved quotes
‘like this’ look better. Support quoting the new way too.
(Bug#20385)
* doc/lispref/tips.texi (Documentation Tips): Symbols can be quoted
‘like-this’ as well as `like-this'.
* etc/NEWS: Mention this.
* lisp/cedet/mode-local.el (overload-docstring-extension)
(mode-local-print-binding, mode-local-describe-bindings-2):
* lisp/cus-theme.el (describe-theme-1):
* lisp/descr-text.el (describe-text-properties-1, describe-char):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine):
* lisp/emacs-lisp/cl-generic.el (cl--generic-describe):
* lisp/emacs-lisp/eieio-opt.el (eieio-help-class)
(eieio-help-constructor):
* lisp/emacs-lisp/package.el (describe-package-1):
* lisp/faces.el (describe-face):
* lisp/help-fns.el (help-fns--key-bindings)
(help-fns--compiler-macro, help-fns--parent-mode, help-fns--obsolete):
(help-fns--interactive-only, describe-function-1):
(describe-variable):
* lisp/help.el (describe-mode):
* lisp/international/mule-cmds.el (describe-input-method)
(describe-language-environment):
* lisp/international/mule-diag.el (describe-character-set)
(print-coding-system-briefly, list-input-methods)
(list-input-methods-1):
Insert curved quotes rather than grave accent and apostrophe.
* lisp/cedet/srecode/texi.el (srecode-texi-texify-docstring):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine)
(checkdoc-proper-noun-region-engine):
* lisp/emacs-lisp/lisp-mode.el (lisp-el-font-lock-keywords-2)
(lisp-cl-font-lock-keywords-2):
* lisp/finder.el (finder-font-lock-keywords):
* lisp/gnus/gnus-art.el (gnus-button-alist):
* lisp/help-fns.el (help-do-arg-highlight)
(describe-function-1, describe-variable):
* lisp/help-mode.el (help-xref-symbol-regexp)
(help-xref-info-regexp, help-xref-url-regexp):
* lisp/help.el (describe-mode):
* lisp/international/mule-cmds.el (help-xref-mule-regexp-template):
* lisp/wid-edit.el (widget-documentation-link-regexp):
Parse symbols quoted ‘like-this’ as well as `like-this'.
* lisp/progmodes/elisp-mode.el (emacs-lisp-mode):
Add "‘" and "’" to electric-pair-text-pairs.
(elisp--form-quoted-p): Also allow "‘" as a quoting char.
(elisp-completion-at-point, elisp--preceding-sexp):
Also treat "‘" and "’" as quoting chars.
2015-05-28 07:06:14 +00:00
|
|
|
|
|
|
|
|
|
Documentation strings can also use an older single-quoting convention,
|
2015-06-18 06:50:45 +00:00
|
|
|
|
which quotes symbols with grave accent @t{`} and apostrophe
|
|
|
|
|
@t{'}: @t{`like-this'} rather than @t{‘like-this’}. This
|
Support curved quotes in doc strings
Emacs's traditional doc string style has been to quote symbols
`like this'. This worked well on now-obsolete terminals where
` and ' were symmetric quotes, but nowadays curved quotes
‘like this’ look better. Support quoting the new way too.
(Bug#20385)
* doc/lispref/tips.texi (Documentation Tips): Symbols can be quoted
‘like-this’ as well as `like-this'.
* etc/NEWS: Mention this.
* lisp/cedet/mode-local.el (overload-docstring-extension)
(mode-local-print-binding, mode-local-describe-bindings-2):
* lisp/cus-theme.el (describe-theme-1):
* lisp/descr-text.el (describe-text-properties-1, describe-char):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine):
* lisp/emacs-lisp/cl-generic.el (cl--generic-describe):
* lisp/emacs-lisp/eieio-opt.el (eieio-help-class)
(eieio-help-constructor):
* lisp/emacs-lisp/package.el (describe-package-1):
* lisp/faces.el (describe-face):
* lisp/help-fns.el (help-fns--key-bindings)
(help-fns--compiler-macro, help-fns--parent-mode, help-fns--obsolete):
(help-fns--interactive-only, describe-function-1):
(describe-variable):
* lisp/help.el (describe-mode):
* lisp/international/mule-cmds.el (describe-input-method)
(describe-language-environment):
* lisp/international/mule-diag.el (describe-character-set)
(print-coding-system-briefly, list-input-methods)
(list-input-methods-1):
Insert curved quotes rather than grave accent and apostrophe.
* lisp/cedet/srecode/texi.el (srecode-texi-texify-docstring):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine)
(checkdoc-proper-noun-region-engine):
* lisp/emacs-lisp/lisp-mode.el (lisp-el-font-lock-keywords-2)
(lisp-cl-font-lock-keywords-2):
* lisp/finder.el (finder-font-lock-keywords):
* lisp/gnus/gnus-art.el (gnus-button-alist):
* lisp/help-fns.el (help-do-arg-highlight)
(describe-function-1, describe-variable):
* lisp/help-mode.el (help-xref-symbol-regexp)
(help-xref-info-regexp, help-xref-url-regexp):
* lisp/help.el (describe-mode):
* lisp/international/mule-cmds.el (help-xref-mule-regexp-template):
* lisp/wid-edit.el (widget-documentation-link-regexp):
Parse symbols quoted ‘like-this’ as well as `like-this'.
* lisp/progmodes/elisp-mode.el (emacs-lisp-mode):
Add "‘" and "’" to electric-pair-text-pairs.
(elisp--form-quoted-p): Also allow "‘" as a quoting char.
(elisp-completion-at-point, elisp--preceding-sexp):
Also treat "‘" and "’" as quoting chars.
2015-05-28 07:06:14 +00:00
|
|
|
|
older convention was designed for now-obsolete displays in which grave
|
Improve the optional translation of quotes
Fix several problems with the recently-added custom variable
help-quote-translation where the code would quote inconsistently
in help buffers. Add support for quoting 'like this', which
is common in other GNU programs in ASCII environments. Change
help-quote-translation to use more mnemonic values: values are now the
initial quoting char, e.g., (setq help-quote-translation ?`) gets the
traditional Emacs help-buffer quoting style `like this'. Change the
default behavior of substitute-command-keys to match what's done in
set-locale-environment, i.e., quote ‘like this’ if displayable,
'like this' otherwise.
* doc/lispref/help.texi (Keys in Documentation): Document
new behavior of substitute-command-keys, and document
help-quote-translation.
* doc/lispref/tips.texi (Documentation Tips):
Mention the effect of help-quote-translation.
* etc/NEWS: Mention new behavior of substitute-command-keys,
and merge help-quote-translation news into it.
When talking about doc strings, mention new ways to type quotes.
* lisp/cedet/mode-local.el (overload-docstring-extension):
Revert my recent change to this function, which shouldn't be
needed as the result is a doc string.
* lisp/cedet/mode-local.el (mode-local-print-binding)
(mode-local-describe-bindings-2):
* lisp/cedet/srecode/srt-mode.el (srecode-macro-help):
* lisp/cus-theme.el (describe-theme-1):
* lisp/descr-text.el (describe-text-properties-1, describe-char):
* lisp/emacs-lisp/cl-generic.el (cl--generic-describe):
* lisp/emacs-lisp/eieio-opt.el (eieio-help-class)
(eieio-help-constructor):
* lisp/emacs-lisp/package.el (describe-package-1):
* lisp/faces.el (describe-face):
* lisp/help-fns.el (help-fns--key-bindings)
(help-fns--compiler-macro, help-fns--parent-mode)
(help-fns--obsolete, help-fns--interactive-only)
(describe-function-1, describe-variable):
* lisp/help.el (describe-mode):
Use substitute-command-keys to ensure a more-consistent quoting
style in help buffers.
* lisp/cus-start.el (standard):
Document new help-quote-translation behavior.
* lisp/emacs-lisp/lisp-mode.el (lisp-fdefs):
* lisp/help-mode.el (help-xref-symbol-regexp, help-xref-info-regexp)
(help-xref-url-regexp):
* lisp/international/mule-cmds.el (help-xref-mule-regexp-template):
* lisp/wid-edit.el (widget-documentation-link-regexp):
Also match 'foo', in case we're in a help buffer generated when
help-quote-translation is ?'.
* src/doc.c: Include disptab.h, for DISP_CHAR_VECTOR.
(LEFT_SINGLE_QUOTATION_MARK, uLSQM0, uLSQM1, uLSQM2, uRSQM0)
(uRSQM1, uRSQM2, LSQM, RSQM): New constants.
(Fsubstitute_command_keys): Document and implement new behavior.
(Vhelp_quote_translation): Document new behavior.
2015-06-19 07:35:43 +00:00
|
|
|
|
accent and apostrophe were mirror images.
|
2016-05-10 14:38:23 +00:00
|
|
|
|
Documentation using this convention is converted to the user's
|
Improve the optional translation of quotes
Fix several problems with the recently-added custom variable
help-quote-translation where the code would quote inconsistently
in help buffers. Add support for quoting 'like this', which
is common in other GNU programs in ASCII environments. Change
help-quote-translation to use more mnemonic values: values are now the
initial quoting char, e.g., (setq help-quote-translation ?`) gets the
traditional Emacs help-buffer quoting style `like this'. Change the
default behavior of substitute-command-keys to match what's done in
set-locale-environment, i.e., quote ‘like this’ if displayable,
'like this' otherwise.
* doc/lispref/help.texi (Keys in Documentation): Document
new behavior of substitute-command-keys, and document
help-quote-translation.
* doc/lispref/tips.texi (Documentation Tips):
Mention the effect of help-quote-translation.
* etc/NEWS: Mention new behavior of substitute-command-keys,
and merge help-quote-translation news into it.
When talking about doc strings, mention new ways to type quotes.
* lisp/cedet/mode-local.el (overload-docstring-extension):
Revert my recent change to this function, which shouldn't be
needed as the result is a doc string.
* lisp/cedet/mode-local.el (mode-local-print-binding)
(mode-local-describe-bindings-2):
* lisp/cedet/srecode/srt-mode.el (srecode-macro-help):
* lisp/cus-theme.el (describe-theme-1):
* lisp/descr-text.el (describe-text-properties-1, describe-char):
* lisp/emacs-lisp/cl-generic.el (cl--generic-describe):
* lisp/emacs-lisp/eieio-opt.el (eieio-help-class)
(eieio-help-constructor):
* lisp/emacs-lisp/package.el (describe-package-1):
* lisp/faces.el (describe-face):
* lisp/help-fns.el (help-fns--key-bindings)
(help-fns--compiler-macro, help-fns--parent-mode)
(help-fns--obsolete, help-fns--interactive-only)
(describe-function-1, describe-variable):
* lisp/help.el (describe-mode):
Use substitute-command-keys to ensure a more-consistent quoting
style in help buffers.
* lisp/cus-start.el (standard):
Document new help-quote-translation behavior.
* lisp/emacs-lisp/lisp-mode.el (lisp-fdefs):
* lisp/help-mode.el (help-xref-symbol-regexp, help-xref-info-regexp)
(help-xref-url-regexp):
* lisp/international/mule-cmds.el (help-xref-mule-regexp-template):
* lisp/wid-edit.el (widget-documentation-link-regexp):
Also match 'foo', in case we're in a help buffer generated when
help-quote-translation is ?'.
* src/doc.c: Include disptab.h, for DISP_CHAR_VECTOR.
(LEFT_SINGLE_QUOTATION_MARK, uLSQM0, uLSQM1, uLSQM2, uRSQM0)
(uRSQM1, uRSQM2, LSQM, RSQM): New constants.
(Fsubstitute_command_keys): Document and implement new behavior.
(Vhelp_quote_translation): Document new behavior.
2015-06-19 07:35:43 +00:00
|
|
|
|
preferred format when it is copied into a help buffer. @xref{Keys in
|
|
|
|
|
Documentation}.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@cindex hyperlinks in documentation strings
|
|
|
|
|
Help mode automatically creates a hyperlink when a documentation string
|
Support curved quotes in doc strings
Emacs's traditional doc string style has been to quote symbols
`like this'. This worked well on now-obsolete terminals where
` and ' were symmetric quotes, but nowadays curved quotes
‘like this’ look better. Support quoting the new way too.
(Bug#20385)
* doc/lispref/tips.texi (Documentation Tips): Symbols can be quoted
‘like-this’ as well as `like-this'.
* etc/NEWS: Mention this.
* lisp/cedet/mode-local.el (overload-docstring-extension)
(mode-local-print-binding, mode-local-describe-bindings-2):
* lisp/cus-theme.el (describe-theme-1):
* lisp/descr-text.el (describe-text-properties-1, describe-char):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine):
* lisp/emacs-lisp/cl-generic.el (cl--generic-describe):
* lisp/emacs-lisp/eieio-opt.el (eieio-help-class)
(eieio-help-constructor):
* lisp/emacs-lisp/package.el (describe-package-1):
* lisp/faces.el (describe-face):
* lisp/help-fns.el (help-fns--key-bindings)
(help-fns--compiler-macro, help-fns--parent-mode, help-fns--obsolete):
(help-fns--interactive-only, describe-function-1):
(describe-variable):
* lisp/help.el (describe-mode):
* lisp/international/mule-cmds.el (describe-input-method)
(describe-language-environment):
* lisp/international/mule-diag.el (describe-character-set)
(print-coding-system-briefly, list-input-methods)
(list-input-methods-1):
Insert curved quotes rather than grave accent and apostrophe.
* lisp/cedet/srecode/texi.el (srecode-texi-texify-docstring):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine)
(checkdoc-proper-noun-region-engine):
* lisp/emacs-lisp/lisp-mode.el (lisp-el-font-lock-keywords-2)
(lisp-cl-font-lock-keywords-2):
* lisp/finder.el (finder-font-lock-keywords):
* lisp/gnus/gnus-art.el (gnus-button-alist):
* lisp/help-fns.el (help-do-arg-highlight)
(describe-function-1, describe-variable):
* lisp/help-mode.el (help-xref-symbol-regexp)
(help-xref-info-regexp, help-xref-url-regexp):
* lisp/help.el (describe-mode):
* lisp/international/mule-cmds.el (help-xref-mule-regexp-template):
* lisp/wid-edit.el (widget-documentation-link-regexp):
Parse symbols quoted ‘like-this’ as well as `like-this'.
* lisp/progmodes/elisp-mode.el (emacs-lisp-mode):
Add "‘" and "’" to electric-pair-text-pairs.
(elisp--form-quoted-p): Also allow "‘" as a quoting char.
(elisp-completion-at-point, elisp--preceding-sexp):
Also treat "‘" and "’" as quoting chars.
2015-05-28 07:06:14 +00:00
|
|
|
|
uses a single-quoted symbol name, if the symbol has either a
|
2007-09-06 04:25:08 +00:00
|
|
|
|
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
|
Go back to grave quoting in source-code docstrings etc.
This reverts almost all my recent changes to use curved quotes
in docstrings and/or strings used for error diagnostics.
There are a few exceptions, e.g., Bahá’í proper names.
* admin/unidata/unidata-gen.el (unidata-gen-table):
* lisp/abbrev.el (expand-region-abbrevs):
* lisp/align.el (align-region):
* lisp/allout.el (allout-mode, allout-solicit-alternate-bullet)
(outlineify-sticky):
* lisp/apropos.el (apropos-library):
* lisp/bookmark.el (bookmark-default-annotation-text):
* lisp/button.el (button-category-symbol, button-put)
(make-text-button):
* lisp/calc/calc-aent.el (math-read-if, math-read-factor):
* lisp/calc/calc-embed.el (calc-do-embedded):
* lisp/calc/calc-ext.el (calc-user-function-list):
* lisp/calc/calc-graph.el (calc-graph-show-dumb):
* lisp/calc/calc-help.el (calc-describe-key)
(calc-describe-thing, calc-full-help):
* lisp/calc/calc-lang.el (calc-c-language)
(math-parse-fortran-vector-end, math-parse-tex-sum)
(math-parse-eqn-matrix, math-parse-eqn-prime)
(calc-yacas-language, calc-maxima-language, calc-giac-language)
(math-read-giac-subscr, math-read-math-subscr)
(math-read-big-rec, math-read-big-balance):
* lisp/calc/calc-misc.el (calc-help, report-calc-bug):
* lisp/calc/calc-mode.el (calc-auto-why, calc-save-modes)
(calc-auto-recompute):
* lisp/calc/calc-prog.el (calc-fix-token-name)
(calc-read-parse-table-part, calc-user-define-invocation)
(math-do-arg-check):
* lisp/calc/calc-store.el (calc-edit-variable):
* lisp/calc/calc-units.el (math-build-units-table-buffer):
* lisp/calc/calc-vec.el (math-read-brackets):
* lisp/calc/calc-yank.el (calc-edit-mode):
* lisp/calc/calc.el (calc, calc-do, calc-user-invocation):
* lisp/calendar/appt.el (appt-display-message):
* lisp/calendar/diary-lib.el (diary-check-diary-file)
(diary-mail-entries, diary-from-outlook):
* lisp/calendar/icalendar.el (icalendar-export-region)
(icalendar--convert-float-to-ical)
(icalendar--convert-date-to-ical)
(icalendar--convert-ical-to-diary)
(icalendar--convert-recurring-to-diary)
(icalendar--add-diary-entry):
* lisp/calendar/time-date.el (format-seconds):
* lisp/calendar/timeclock.el (timeclock-mode-line-display)
(timeclock-make-hours-explicit, timeclock-log-data):
* lisp/calendar/todo-mode.el (todo-prefix, todo-delete-category)
(todo-item-mark, todo-check-format)
(todo-insert-item--next-param, todo-edit-item--next-key)
(todo-mode):
* lisp/cedet/ede/pmake.el (ede-proj-makefile-insert-dist-rules):
* lisp/cedet/mode-local.el (describe-mode-local-overload)
(mode-local-print-binding, mode-local-describe-bindings-2):
* lisp/cedet/semantic/complete.el (semantic-displayor-show-request):
* lisp/cedet/srecode/srt-mode.el (srecode-macro-help):
* lisp/cus-start.el (standard):
* lisp/cus-theme.el (describe-theme-1):
* lisp/custom.el (custom-add-dependencies, custom-check-theme)
(custom--sort-vars-1, load-theme):
* lisp/descr-text.el (describe-text-properties-1, describe-char):
* lisp/dired-x.el (dired-do-run-mail):
* lisp/dired.el (dired-log):
* lisp/emacs-lisp/advice.el (ad-read-advised-function)
(ad-read-advice-class, ad-read-advice-name, ad-enable-advice)
(ad-disable-advice, ad-remove-advice, ad-set-argument)
(ad-set-arguments, ad--defalias-fset, ad-activate)
(ad-deactivate):
* lisp/emacs-lisp/byte-opt.el (byte-compile-inline-expand)
(byte-compile-unfold-lambda, byte-optimize-form-code-walker)
(byte-optimize-while, byte-optimize-apply):
* lisp/emacs-lisp/byte-run.el (defun, defsubst):
* lisp/emacs-lisp/bytecomp.el (byte-compile-lapcode)
(byte-compile-log-file, byte-compile-format-warn)
(byte-compile-nogroup-warn, byte-compile-arglist-warn)
(byte-compile-cl-warn)
(byte-compile-warn-about-unresolved-functions)
(byte-compile-file, byte-compile--declare-var)
(byte-compile-file-form-defmumble, byte-compile-form)
(byte-compile-normal-call, byte-compile-check-variable)
(byte-compile-variable-ref, byte-compile-variable-set)
(byte-compile-subr-wrong-args, byte-compile-setq-default)
(byte-compile-negation-optimizer)
(byte-compile-condition-case--old)
(byte-compile-condition-case--new, byte-compile-save-excursion)
(byte-compile-defvar, byte-compile-autoload)
(byte-compile-lambda-form)
(byte-compile-make-variable-buffer-local, display-call-tree)
(batch-byte-compile):
* lisp/emacs-lisp/cconv.el (cconv-convert, cconv--analyze-use):
* lisp/emacs-lisp/chart.el (chart-space-usage):
* lisp/emacs-lisp/check-declare.el (check-declare-scan)
(check-declare-warn, check-declare-file)
(check-declare-directory):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine)
(checkdoc-message-text-engine):
* lisp/emacs-lisp/cl-extra.el (cl-parse-integer)
(cl--describe-class):
* lisp/emacs-lisp/cl-generic.el (cl-defgeneric)
(cl--generic-describe, cl-generic-generalizers):
* lisp/emacs-lisp/cl-macs.el (cl--parse-loop-clause, cl-tagbody)
(cl-symbol-macrolet):
* lisp/emacs-lisp/cl.el (cl-unload-function, flet):
* lisp/emacs-lisp/copyright.el (copyright)
(copyright-update-directory):
* lisp/emacs-lisp/edebug.el (edebug-read-list):
* lisp/emacs-lisp/eieio-base.el (eieio-persistent-read):
* lisp/emacs-lisp/eieio-core.el (eieio--slot-override)
(eieio-oref):
* lisp/emacs-lisp/eieio-opt.el (eieio-help-constructor):
* lisp/emacs-lisp/eieio-speedbar.el:
(eieio-speedbar-child-make-tag-lines)
(eieio-speedbar-child-description):
* lisp/emacs-lisp/eieio.el (defclass, change-class):
* lisp/emacs-lisp/elint.el (elint-file, elint-get-top-forms)
(elint-init-form, elint-check-defalias-form)
(elint-check-let-form):
* lisp/emacs-lisp/ert.el (ert-get-test, ert-results-mode-menu)
(ert-results-pop-to-backtrace-for-test-at-point)
(ert-results-pop-to-messages-for-test-at-point)
(ert-results-pop-to-should-forms-for-test-at-point)
(ert-describe-test):
* lisp/emacs-lisp/find-func.el (find-function-search-for-symbol)
(find-function-library):
* lisp/emacs-lisp/generator.el (iter-yield):
* lisp/emacs-lisp/gv.el (gv-define-simple-setter):
* lisp/emacs-lisp/lisp-mnt.el (lm-verify):
* lisp/emacs-lisp/macroexp.el (macroexp--obsolete-warning):
* lisp/emacs-lisp/map-ynp.el (map-y-or-n-p):
* lisp/emacs-lisp/nadvice.el (advice--make-docstring)
(advice--make, define-advice):
* lisp/emacs-lisp/package-x.el (package-upload-file):
* lisp/emacs-lisp/package.el (package-version-join)
(package-disabled-p, package-activate-1, package-activate)
(package--download-one-archive)
(package--download-and-read-archives)
(package-compute-transaction, package-install-from-archive)
(package-install, package-install-selected-packages)
(package-delete, package-autoremove, describe-package-1)
(package-install-button-action, package-delete-button-action)
(package-menu-hide-package, package-menu--list-to-prompt)
(package-menu--perform-transaction)
(package-menu--find-and-notify-upgrades):
* lisp/emacs-lisp/pcase.el (pcase-exhaustive, pcase--u1):
* lisp/emacs-lisp/re-builder.el (reb-enter-subexp-mode):
* lisp/emacs-lisp/ring.el (ring-previous, ring-next):
* lisp/emacs-lisp/rx.el (rx-check, rx-anything)
(rx-check-any-string, rx-check-any, rx-check-not, rx-=)
(rx-repeat, rx-check-backref, rx-syntax, rx-check-category)
(rx-form):
* lisp/emacs-lisp/smie.el (smie-config-save):
* lisp/emacs-lisp/subr-x.el (internal--check-binding):
* lisp/emacs-lisp/tabulated-list.el (tabulated-list-put-tag):
* lisp/emacs-lisp/testcover.el (testcover-1value):
* lisp/emacs-lisp/timer.el (timer-event-handler):
* lisp/emulation/viper-cmd.el (viper-toggle-parse-sexp-ignore-comments)
(viper-toggle-search-style, viper-kill-buffer)
(viper-brac-function):
* lisp/emulation/viper-macs.el (viper-record-kbd-macro):
* lisp/env.el (setenv):
* lisp/erc/erc-button.el (erc-nick-popup):
* lisp/erc/erc.el (erc-cmd-LOAD, erc-handle-login, english):
* lisp/eshell/em-dirs.el (eshell/cd):
* lisp/eshell/em-glob.el (eshell-glob-regexp)
(eshell-glob-entries):
* lisp/eshell/em-pred.el (eshell-parse-modifiers):
* lisp/eshell/esh-opt.el (eshell-show-usage):
* lisp/facemenu.el (facemenu-add-new-face)
(facemenu-add-new-color):
* lisp/faces.el (read-face-name, read-face-font, describe-face)
(x-resolve-font-name):
* lisp/files-x.el (modify-file-local-variable):
* lisp/files.el (locate-user-emacs-file, find-alternate-file)
(set-auto-mode, hack-one-local-variable--obsolete)
(dir-locals-set-directory-class, write-file, basic-save-buffer)
(delete-directory, copy-directory, recover-session)
(recover-session-finish, insert-directory)
(file-modes-char-to-who, file-modes-symbolic-to-number)
(move-file-to-trash):
* lisp/filesets.el (filesets-add-buffer, filesets-remove-buffer):
* lisp/find-cmd.el (find-generic, find-to-string):
* lisp/finder.el (finder-commentary):
* lisp/font-lock.el (font-lock-fontify-buffer):
* lisp/format.el (format-write-file, format-find-file)
(format-insert-file):
* lisp/frame.el (get-device-terminal, select-frame-by-name):
* lisp/fringe.el (fringe--check-style):
* lisp/gnus/nnmairix.el (nnmairix-widget-create-query):
* lisp/help-fns.el (help-fns--key-bindings)
(help-fns--compiler-macro, help-fns--parent-mode)
(help-fns--obsolete, help-fns--interactive-only)
(describe-function-1, describe-variable):
* lisp/help.el (describe-mode)
(describe-minor-mode-from-indicator):
* lisp/image.el (image-type):
* lisp/international/ccl.el (ccl-dump):
* lisp/international/fontset.el (x-must-resolve-font-name):
* lisp/international/mule-cmds.el (prefer-coding-system)
(select-safe-coding-system-interactively)
(select-safe-coding-system, activate-input-method)
(toggle-input-method, describe-current-input-method)
(describe-language-environment):
* lisp/international/mule-conf.el (code-offset):
* lisp/international/mule-diag.el (describe-character-set)
(list-input-methods-1):
* lisp/mail/feedmail.el (feedmail-run-the-queue):
* lisp/mouse.el (minor-mode-menu-from-indicator):
* lisp/mpc.el (mpc-playlist-rename):
* lisp/msb.el (msb--choose-menu):
* lisp/net/ange-ftp.el (ange-ftp-shell-command):
* lisp/net/imap.el (imap-interactive-login):
* lisp/net/mairix.el (mairix-widget-create-query):
* lisp/net/newst-backend.el (newsticker--sentinel-work):
* lisp/net/newst-treeview.el (newsticker--treeview-load):
* lisp/net/rlogin.el (rlogin):
* lisp/obsolete/iswitchb.el (iswitchb-possible-new-buffer):
* lisp/obsolete/otodo-mode.el (todo-more-important-p):
* lisp/obsolete/pgg-gpg.el (pgg-gpg-process-region):
* lisp/obsolete/pgg-pgp.el (pgg-pgp-process-region):
* lisp/obsolete/pgg-pgp5.el (pgg-pgp5-process-region):
* lisp/org/ob-core.el (org-babel-goto-named-src-block)
(org-babel-goto-named-result):
* lisp/org/ob-fortran.el (org-babel-fortran-ensure-main-wrap):
* lisp/org/ob-ref.el (org-babel-ref-resolve):
* lisp/org/org-agenda.el (org-agenda-prepare):
* lisp/org/org-clock.el (org-clock-notify-once-if-expired)
(org-clock-resolve):
* lisp/org/org-ctags.el (org-ctags-ask-rebuild-tags-file-then-find-tag):
* lisp/org/org-feed.el (org-feed-parse-atom-entry):
* lisp/org/org-habit.el (org-habit-parse-todo):
* lisp/org/org-mouse.el (org-mouse-popup-global-menu)
(org-mouse-context-menu):
* lisp/org/org-table.el (org-table-edit-formulas):
* lisp/org/ox.el (org-export-async-start):
* lisp/proced.el (proced-log):
* lisp/progmodes/ada-mode.el (ada-get-indent-case)
(ada-check-matching-start, ada-goto-matching-start):
* lisp/progmodes/ada-prj.el (ada-prj-display-page):
* lisp/progmodes/ada-xref.el (ada-find-executable):
* lisp/progmodes/ebrowse.el (ebrowse-tags-apropos):
* lisp/progmodes/etags.el (etags-tags-apropos-additional):
* lisp/progmodes/flymake.el (flymake-parse-err-lines)
(flymake-start-syntax-check-process):
* lisp/progmodes/python.el (python-shell-get-process-or-error)
(python-define-auxiliary-skeleton):
* lisp/progmodes/sql.el (sql-comint):
* lisp/progmodes/verilog-mode.el (verilog-load-file-at-point):
* lisp/progmodes/vhdl-mode.el (vhdl-widget-directory-validate):
* lisp/recentf.el (recentf-open-files):
* lisp/replace.el (query-replace-read-from)
(occur-after-change-function, occur-1):
* lisp/scroll-bar.el (scroll-bar-columns):
* lisp/server.el (server-get-auth-key):
* lisp/simple.el (execute-extended-command)
(undo-outer-limit-truncate, list-processes--refresh)
(compose-mail, set-variable, choose-completion-string)
(define-alternatives):
* lisp/startup.el (site-run-file, tty-handle-args, command-line)
(command-line-1):
* lisp/subr.el (noreturn, define-error, add-to-list)
(read-char-choice, version-to-list):
* lisp/term/common-win.el (x-handle-xrm-switch)
(x-handle-name-switch, x-handle-args):
* lisp/term/x-win.el (x-handle-parent-id, x-handle-smid):
* lisp/textmodes/reftex-ref.el (reftex-label):
* lisp/textmodes/reftex-toc.el (reftex-toc-rename-label):
* lisp/textmodes/two-column.el (2C-split):
* lisp/tutorial.el (tutorial--describe-nonstandard-key)
(tutorial--find-changed-keys):
* lisp/type-break.el (type-break-noninteractive-query):
* lisp/wdired.el (wdired-do-renames, wdired-do-symlink-changes)
(wdired-do-perm-changes):
* lisp/whitespace.el (whitespace-report-region):
Prefer grave quoting in source-code strings used to generate help
and diagnostics.
* lisp/faces.el (face-documentation):
No need to convert quotes, since the result is a docstring.
* lisp/info.el (Info-virtual-index-find-node)
(Info-virtual-index, info-apropos):
Simplify by generating only curved quotes, since info files are
typically that ways nowadays anyway.
* lisp/international/mule-diag.el (list-input-methods):
Don’t assume text quoting style is curved.
* lisp/org/org-bibtex.el (org-bibtex-fields):
Revert my recent changes, going back to the old quoting style.
2015-09-07 15:41:44 +00:00
|
|
|
|
This function sets the variable `buffer-file-name'.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@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 words @samp{symbol} or @samp{program} before the
|
|
|
|
|
symbol name to prevent making any hyperlink. For example,
|
|
|
|
|
|
|
|
|
|
@example
|
Go back to grave quoting in source-code docstrings etc.
This reverts almost all my recent changes to use curved quotes
in docstrings and/or strings used for error diagnostics.
There are a few exceptions, e.g., Bahá’í proper names.
* admin/unidata/unidata-gen.el (unidata-gen-table):
* lisp/abbrev.el (expand-region-abbrevs):
* lisp/align.el (align-region):
* lisp/allout.el (allout-mode, allout-solicit-alternate-bullet)
(outlineify-sticky):
* lisp/apropos.el (apropos-library):
* lisp/bookmark.el (bookmark-default-annotation-text):
* lisp/button.el (button-category-symbol, button-put)
(make-text-button):
* lisp/calc/calc-aent.el (math-read-if, math-read-factor):
* lisp/calc/calc-embed.el (calc-do-embedded):
* lisp/calc/calc-ext.el (calc-user-function-list):
* lisp/calc/calc-graph.el (calc-graph-show-dumb):
* lisp/calc/calc-help.el (calc-describe-key)
(calc-describe-thing, calc-full-help):
* lisp/calc/calc-lang.el (calc-c-language)
(math-parse-fortran-vector-end, math-parse-tex-sum)
(math-parse-eqn-matrix, math-parse-eqn-prime)
(calc-yacas-language, calc-maxima-language, calc-giac-language)
(math-read-giac-subscr, math-read-math-subscr)
(math-read-big-rec, math-read-big-balance):
* lisp/calc/calc-misc.el (calc-help, report-calc-bug):
* lisp/calc/calc-mode.el (calc-auto-why, calc-save-modes)
(calc-auto-recompute):
* lisp/calc/calc-prog.el (calc-fix-token-name)
(calc-read-parse-table-part, calc-user-define-invocation)
(math-do-arg-check):
* lisp/calc/calc-store.el (calc-edit-variable):
* lisp/calc/calc-units.el (math-build-units-table-buffer):
* lisp/calc/calc-vec.el (math-read-brackets):
* lisp/calc/calc-yank.el (calc-edit-mode):
* lisp/calc/calc.el (calc, calc-do, calc-user-invocation):
* lisp/calendar/appt.el (appt-display-message):
* lisp/calendar/diary-lib.el (diary-check-diary-file)
(diary-mail-entries, diary-from-outlook):
* lisp/calendar/icalendar.el (icalendar-export-region)
(icalendar--convert-float-to-ical)
(icalendar--convert-date-to-ical)
(icalendar--convert-ical-to-diary)
(icalendar--convert-recurring-to-diary)
(icalendar--add-diary-entry):
* lisp/calendar/time-date.el (format-seconds):
* lisp/calendar/timeclock.el (timeclock-mode-line-display)
(timeclock-make-hours-explicit, timeclock-log-data):
* lisp/calendar/todo-mode.el (todo-prefix, todo-delete-category)
(todo-item-mark, todo-check-format)
(todo-insert-item--next-param, todo-edit-item--next-key)
(todo-mode):
* lisp/cedet/ede/pmake.el (ede-proj-makefile-insert-dist-rules):
* lisp/cedet/mode-local.el (describe-mode-local-overload)
(mode-local-print-binding, mode-local-describe-bindings-2):
* lisp/cedet/semantic/complete.el (semantic-displayor-show-request):
* lisp/cedet/srecode/srt-mode.el (srecode-macro-help):
* lisp/cus-start.el (standard):
* lisp/cus-theme.el (describe-theme-1):
* lisp/custom.el (custom-add-dependencies, custom-check-theme)
(custom--sort-vars-1, load-theme):
* lisp/descr-text.el (describe-text-properties-1, describe-char):
* lisp/dired-x.el (dired-do-run-mail):
* lisp/dired.el (dired-log):
* lisp/emacs-lisp/advice.el (ad-read-advised-function)
(ad-read-advice-class, ad-read-advice-name, ad-enable-advice)
(ad-disable-advice, ad-remove-advice, ad-set-argument)
(ad-set-arguments, ad--defalias-fset, ad-activate)
(ad-deactivate):
* lisp/emacs-lisp/byte-opt.el (byte-compile-inline-expand)
(byte-compile-unfold-lambda, byte-optimize-form-code-walker)
(byte-optimize-while, byte-optimize-apply):
* lisp/emacs-lisp/byte-run.el (defun, defsubst):
* lisp/emacs-lisp/bytecomp.el (byte-compile-lapcode)
(byte-compile-log-file, byte-compile-format-warn)
(byte-compile-nogroup-warn, byte-compile-arglist-warn)
(byte-compile-cl-warn)
(byte-compile-warn-about-unresolved-functions)
(byte-compile-file, byte-compile--declare-var)
(byte-compile-file-form-defmumble, byte-compile-form)
(byte-compile-normal-call, byte-compile-check-variable)
(byte-compile-variable-ref, byte-compile-variable-set)
(byte-compile-subr-wrong-args, byte-compile-setq-default)
(byte-compile-negation-optimizer)
(byte-compile-condition-case--old)
(byte-compile-condition-case--new, byte-compile-save-excursion)
(byte-compile-defvar, byte-compile-autoload)
(byte-compile-lambda-form)
(byte-compile-make-variable-buffer-local, display-call-tree)
(batch-byte-compile):
* lisp/emacs-lisp/cconv.el (cconv-convert, cconv--analyze-use):
* lisp/emacs-lisp/chart.el (chart-space-usage):
* lisp/emacs-lisp/check-declare.el (check-declare-scan)
(check-declare-warn, check-declare-file)
(check-declare-directory):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine)
(checkdoc-message-text-engine):
* lisp/emacs-lisp/cl-extra.el (cl-parse-integer)
(cl--describe-class):
* lisp/emacs-lisp/cl-generic.el (cl-defgeneric)
(cl--generic-describe, cl-generic-generalizers):
* lisp/emacs-lisp/cl-macs.el (cl--parse-loop-clause, cl-tagbody)
(cl-symbol-macrolet):
* lisp/emacs-lisp/cl.el (cl-unload-function, flet):
* lisp/emacs-lisp/copyright.el (copyright)
(copyright-update-directory):
* lisp/emacs-lisp/edebug.el (edebug-read-list):
* lisp/emacs-lisp/eieio-base.el (eieio-persistent-read):
* lisp/emacs-lisp/eieio-core.el (eieio--slot-override)
(eieio-oref):
* lisp/emacs-lisp/eieio-opt.el (eieio-help-constructor):
* lisp/emacs-lisp/eieio-speedbar.el:
(eieio-speedbar-child-make-tag-lines)
(eieio-speedbar-child-description):
* lisp/emacs-lisp/eieio.el (defclass, change-class):
* lisp/emacs-lisp/elint.el (elint-file, elint-get-top-forms)
(elint-init-form, elint-check-defalias-form)
(elint-check-let-form):
* lisp/emacs-lisp/ert.el (ert-get-test, ert-results-mode-menu)
(ert-results-pop-to-backtrace-for-test-at-point)
(ert-results-pop-to-messages-for-test-at-point)
(ert-results-pop-to-should-forms-for-test-at-point)
(ert-describe-test):
* lisp/emacs-lisp/find-func.el (find-function-search-for-symbol)
(find-function-library):
* lisp/emacs-lisp/generator.el (iter-yield):
* lisp/emacs-lisp/gv.el (gv-define-simple-setter):
* lisp/emacs-lisp/lisp-mnt.el (lm-verify):
* lisp/emacs-lisp/macroexp.el (macroexp--obsolete-warning):
* lisp/emacs-lisp/map-ynp.el (map-y-or-n-p):
* lisp/emacs-lisp/nadvice.el (advice--make-docstring)
(advice--make, define-advice):
* lisp/emacs-lisp/package-x.el (package-upload-file):
* lisp/emacs-lisp/package.el (package-version-join)
(package-disabled-p, package-activate-1, package-activate)
(package--download-one-archive)
(package--download-and-read-archives)
(package-compute-transaction, package-install-from-archive)
(package-install, package-install-selected-packages)
(package-delete, package-autoremove, describe-package-1)
(package-install-button-action, package-delete-button-action)
(package-menu-hide-package, package-menu--list-to-prompt)
(package-menu--perform-transaction)
(package-menu--find-and-notify-upgrades):
* lisp/emacs-lisp/pcase.el (pcase-exhaustive, pcase--u1):
* lisp/emacs-lisp/re-builder.el (reb-enter-subexp-mode):
* lisp/emacs-lisp/ring.el (ring-previous, ring-next):
* lisp/emacs-lisp/rx.el (rx-check, rx-anything)
(rx-check-any-string, rx-check-any, rx-check-not, rx-=)
(rx-repeat, rx-check-backref, rx-syntax, rx-check-category)
(rx-form):
* lisp/emacs-lisp/smie.el (smie-config-save):
* lisp/emacs-lisp/subr-x.el (internal--check-binding):
* lisp/emacs-lisp/tabulated-list.el (tabulated-list-put-tag):
* lisp/emacs-lisp/testcover.el (testcover-1value):
* lisp/emacs-lisp/timer.el (timer-event-handler):
* lisp/emulation/viper-cmd.el (viper-toggle-parse-sexp-ignore-comments)
(viper-toggle-search-style, viper-kill-buffer)
(viper-brac-function):
* lisp/emulation/viper-macs.el (viper-record-kbd-macro):
* lisp/env.el (setenv):
* lisp/erc/erc-button.el (erc-nick-popup):
* lisp/erc/erc.el (erc-cmd-LOAD, erc-handle-login, english):
* lisp/eshell/em-dirs.el (eshell/cd):
* lisp/eshell/em-glob.el (eshell-glob-regexp)
(eshell-glob-entries):
* lisp/eshell/em-pred.el (eshell-parse-modifiers):
* lisp/eshell/esh-opt.el (eshell-show-usage):
* lisp/facemenu.el (facemenu-add-new-face)
(facemenu-add-new-color):
* lisp/faces.el (read-face-name, read-face-font, describe-face)
(x-resolve-font-name):
* lisp/files-x.el (modify-file-local-variable):
* lisp/files.el (locate-user-emacs-file, find-alternate-file)
(set-auto-mode, hack-one-local-variable--obsolete)
(dir-locals-set-directory-class, write-file, basic-save-buffer)
(delete-directory, copy-directory, recover-session)
(recover-session-finish, insert-directory)
(file-modes-char-to-who, file-modes-symbolic-to-number)
(move-file-to-trash):
* lisp/filesets.el (filesets-add-buffer, filesets-remove-buffer):
* lisp/find-cmd.el (find-generic, find-to-string):
* lisp/finder.el (finder-commentary):
* lisp/font-lock.el (font-lock-fontify-buffer):
* lisp/format.el (format-write-file, format-find-file)
(format-insert-file):
* lisp/frame.el (get-device-terminal, select-frame-by-name):
* lisp/fringe.el (fringe--check-style):
* lisp/gnus/nnmairix.el (nnmairix-widget-create-query):
* lisp/help-fns.el (help-fns--key-bindings)
(help-fns--compiler-macro, help-fns--parent-mode)
(help-fns--obsolete, help-fns--interactive-only)
(describe-function-1, describe-variable):
* lisp/help.el (describe-mode)
(describe-minor-mode-from-indicator):
* lisp/image.el (image-type):
* lisp/international/ccl.el (ccl-dump):
* lisp/international/fontset.el (x-must-resolve-font-name):
* lisp/international/mule-cmds.el (prefer-coding-system)
(select-safe-coding-system-interactively)
(select-safe-coding-system, activate-input-method)
(toggle-input-method, describe-current-input-method)
(describe-language-environment):
* lisp/international/mule-conf.el (code-offset):
* lisp/international/mule-diag.el (describe-character-set)
(list-input-methods-1):
* lisp/mail/feedmail.el (feedmail-run-the-queue):
* lisp/mouse.el (minor-mode-menu-from-indicator):
* lisp/mpc.el (mpc-playlist-rename):
* lisp/msb.el (msb--choose-menu):
* lisp/net/ange-ftp.el (ange-ftp-shell-command):
* lisp/net/imap.el (imap-interactive-login):
* lisp/net/mairix.el (mairix-widget-create-query):
* lisp/net/newst-backend.el (newsticker--sentinel-work):
* lisp/net/newst-treeview.el (newsticker--treeview-load):
* lisp/net/rlogin.el (rlogin):
* lisp/obsolete/iswitchb.el (iswitchb-possible-new-buffer):
* lisp/obsolete/otodo-mode.el (todo-more-important-p):
* lisp/obsolete/pgg-gpg.el (pgg-gpg-process-region):
* lisp/obsolete/pgg-pgp.el (pgg-pgp-process-region):
* lisp/obsolete/pgg-pgp5.el (pgg-pgp5-process-region):
* lisp/org/ob-core.el (org-babel-goto-named-src-block)
(org-babel-goto-named-result):
* lisp/org/ob-fortran.el (org-babel-fortran-ensure-main-wrap):
* lisp/org/ob-ref.el (org-babel-ref-resolve):
* lisp/org/org-agenda.el (org-agenda-prepare):
* lisp/org/org-clock.el (org-clock-notify-once-if-expired)
(org-clock-resolve):
* lisp/org/org-ctags.el (org-ctags-ask-rebuild-tags-file-then-find-tag):
* lisp/org/org-feed.el (org-feed-parse-atom-entry):
* lisp/org/org-habit.el (org-habit-parse-todo):
* lisp/org/org-mouse.el (org-mouse-popup-global-menu)
(org-mouse-context-menu):
* lisp/org/org-table.el (org-table-edit-formulas):
* lisp/org/ox.el (org-export-async-start):
* lisp/proced.el (proced-log):
* lisp/progmodes/ada-mode.el (ada-get-indent-case)
(ada-check-matching-start, ada-goto-matching-start):
* lisp/progmodes/ada-prj.el (ada-prj-display-page):
* lisp/progmodes/ada-xref.el (ada-find-executable):
* lisp/progmodes/ebrowse.el (ebrowse-tags-apropos):
* lisp/progmodes/etags.el (etags-tags-apropos-additional):
* lisp/progmodes/flymake.el (flymake-parse-err-lines)
(flymake-start-syntax-check-process):
* lisp/progmodes/python.el (python-shell-get-process-or-error)
(python-define-auxiliary-skeleton):
* lisp/progmodes/sql.el (sql-comint):
* lisp/progmodes/verilog-mode.el (verilog-load-file-at-point):
* lisp/progmodes/vhdl-mode.el (vhdl-widget-directory-validate):
* lisp/recentf.el (recentf-open-files):
* lisp/replace.el (query-replace-read-from)
(occur-after-change-function, occur-1):
* lisp/scroll-bar.el (scroll-bar-columns):
* lisp/server.el (server-get-auth-key):
* lisp/simple.el (execute-extended-command)
(undo-outer-limit-truncate, list-processes--refresh)
(compose-mail, set-variable, choose-completion-string)
(define-alternatives):
* lisp/startup.el (site-run-file, tty-handle-args, command-line)
(command-line-1):
* lisp/subr.el (noreturn, define-error, add-to-list)
(read-char-choice, version-to-list):
* lisp/term/common-win.el (x-handle-xrm-switch)
(x-handle-name-switch, x-handle-args):
* lisp/term/x-win.el (x-handle-parent-id, x-handle-smid):
* lisp/textmodes/reftex-ref.el (reftex-label):
* lisp/textmodes/reftex-toc.el (reftex-toc-rename-label):
* lisp/textmodes/two-column.el (2C-split):
* lisp/tutorial.el (tutorial--describe-nonstandard-key)
(tutorial--find-changed-keys):
* lisp/type-break.el (type-break-noninteractive-query):
* lisp/wdired.el (wdired-do-renames, wdired-do-symlink-changes)
(wdired-do-perm-changes):
* lisp/whitespace.el (whitespace-report-region):
Prefer grave quoting in source-code strings used to generate help
and diagnostics.
* lisp/faces.el (face-documentation):
No need to convert quotes, since the result is a docstring.
* lisp/info.el (Info-virtual-index-find-node)
(Info-virtual-index, info-apropos):
Simplify by generating only curved quotes, since info files are
typically that ways nowadays anyway.
* lisp/international/mule-diag.el (list-input-methods):
Don’t assume text quoting style is curved.
* lisp/org/org-bibtex.el (org-bibtex-fields):
Revert my recent changes, going back to the old quoting style.
2015-09-07 15:41:44 +00:00
|
|
|
|
If the argument KIND-OF-RESULT is the symbol `list',
|
2007-09-06 04:25:08 +00:00
|
|
|
|
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}.
|
|
|
|
|
|
|
|
|
|
Normally, no hyperlink is made for a variable without variable
|
|
|
|
|
documentation. You can force a hyperlink for such variables by
|
|
|
|
|
preceding them with one of the words @samp{variable} or
|
|
|
|
|
@samp{option}.
|
|
|
|
|
|
|
|
|
|
Hyperlinks for faces are only made if the face name is preceded or
|
|
|
|
|
followed by the word @samp{face}. In that case, only the face
|
|
|
|
|
documentation will be shown, even if the symbol is also defined as a
|
|
|
|
|
variable or as a function.
|
|
|
|
|
|
Support curved quotes in doc strings
Emacs's traditional doc string style has been to quote symbols
`like this'. This worked well on now-obsolete terminals where
` and ' were symmetric quotes, but nowadays curved quotes
‘like this’ look better. Support quoting the new way too.
(Bug#20385)
* doc/lispref/tips.texi (Documentation Tips): Symbols can be quoted
‘like-this’ as well as `like-this'.
* etc/NEWS: Mention this.
* lisp/cedet/mode-local.el (overload-docstring-extension)
(mode-local-print-binding, mode-local-describe-bindings-2):
* lisp/cus-theme.el (describe-theme-1):
* lisp/descr-text.el (describe-text-properties-1, describe-char):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine):
* lisp/emacs-lisp/cl-generic.el (cl--generic-describe):
* lisp/emacs-lisp/eieio-opt.el (eieio-help-class)
(eieio-help-constructor):
* lisp/emacs-lisp/package.el (describe-package-1):
* lisp/faces.el (describe-face):
* lisp/help-fns.el (help-fns--key-bindings)
(help-fns--compiler-macro, help-fns--parent-mode, help-fns--obsolete):
(help-fns--interactive-only, describe-function-1):
(describe-variable):
* lisp/help.el (describe-mode):
* lisp/international/mule-cmds.el (describe-input-method)
(describe-language-environment):
* lisp/international/mule-diag.el (describe-character-set)
(print-coding-system-briefly, list-input-methods)
(list-input-methods-1):
Insert curved quotes rather than grave accent and apostrophe.
* lisp/cedet/srecode/texi.el (srecode-texi-texify-docstring):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine)
(checkdoc-proper-noun-region-engine):
* lisp/emacs-lisp/lisp-mode.el (lisp-el-font-lock-keywords-2)
(lisp-cl-font-lock-keywords-2):
* lisp/finder.el (finder-font-lock-keywords):
* lisp/gnus/gnus-art.el (gnus-button-alist):
* lisp/help-fns.el (help-do-arg-highlight)
(describe-function-1, describe-variable):
* lisp/help-mode.el (help-xref-symbol-regexp)
(help-xref-info-regexp, help-xref-url-regexp):
* lisp/help.el (describe-mode):
* lisp/international/mule-cmds.el (help-xref-mule-regexp-template):
* lisp/wid-edit.el (widget-documentation-link-regexp):
Parse symbols quoted ‘like-this’ as well as `like-this'.
* lisp/progmodes/elisp-mode.el (emacs-lisp-mode):
Add "‘" and "’" to electric-pair-text-pairs.
(elisp--form-quoted-p): Also allow "‘" as a quoting char.
(elisp-completion-at-point, elisp--preceding-sexp):
Also treat "‘" and "’" as quoting chars.
2015-05-28 07:06:14 +00:00
|
|
|
|
To make a hyperlink to Info documentation, write the single-quoted
|
|
|
|
|
name of the Info node (or anchor), preceded by
|
Minor quoting etc. fixes to lispref manual
* doc/lispref/tips.texi (Documentation Tips):
Distinguish more clearly among grave accent, apostrophe,
and single quote.
* doc/lispref/README, doc/lispref/buffers.texi:
* doc/lispref/commands.texi, doc/lispref/control.texi:
* doc/lispref/customize.texi, doc/lispref/display.texi:
* doc/lispref/elisp.texi, doc/lispref/files.texi:
* doc/lispref/frames.texi, doc/lispref/hash.texi:
* doc/lispref/help.texi, doc/lispref/internals.texi:
* doc/lispref/loading.texi, doc/lispref/makefile.w32-in:
* doc/lispref/markers.texi, doc/lispref/modes.texi:
* doc/lispref/nonascii.texi, doc/lispref/objects.texi:
* doc/lispref/os.texi, doc/lispref/positions.texi:
* doc/lispref/strings.texi, doc/lispref/syntax.texi:
* doc/lispref/text.texi, doc/lispref/tips.texi:
* doc/lispref/two-volume-cross-refs.txt, doc/lispref/windows.texi:
Use American-style double quoting in ordinary text,
and quote 'like this' when single-quoting in ASCII text.
Also, fix some minor spacing issues.
2015-04-10 18:27:21 +00:00
|
|
|
|
@samp{info node}, @samp{Info node}, @samp{info anchor} or @samp{Info
|
|
|
|
|
anchor}. The Info file name defaults to @samp{emacs}. For example,
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@smallexample
|
Go back to grave quoting in source-code docstrings etc.
This reverts almost all my recent changes to use curved quotes
in docstrings and/or strings used for error diagnostics.
There are a few exceptions, e.g., Bahá’í proper names.
* admin/unidata/unidata-gen.el (unidata-gen-table):
* lisp/abbrev.el (expand-region-abbrevs):
* lisp/align.el (align-region):
* lisp/allout.el (allout-mode, allout-solicit-alternate-bullet)
(outlineify-sticky):
* lisp/apropos.el (apropos-library):
* lisp/bookmark.el (bookmark-default-annotation-text):
* lisp/button.el (button-category-symbol, button-put)
(make-text-button):
* lisp/calc/calc-aent.el (math-read-if, math-read-factor):
* lisp/calc/calc-embed.el (calc-do-embedded):
* lisp/calc/calc-ext.el (calc-user-function-list):
* lisp/calc/calc-graph.el (calc-graph-show-dumb):
* lisp/calc/calc-help.el (calc-describe-key)
(calc-describe-thing, calc-full-help):
* lisp/calc/calc-lang.el (calc-c-language)
(math-parse-fortran-vector-end, math-parse-tex-sum)
(math-parse-eqn-matrix, math-parse-eqn-prime)
(calc-yacas-language, calc-maxima-language, calc-giac-language)
(math-read-giac-subscr, math-read-math-subscr)
(math-read-big-rec, math-read-big-balance):
* lisp/calc/calc-misc.el (calc-help, report-calc-bug):
* lisp/calc/calc-mode.el (calc-auto-why, calc-save-modes)
(calc-auto-recompute):
* lisp/calc/calc-prog.el (calc-fix-token-name)
(calc-read-parse-table-part, calc-user-define-invocation)
(math-do-arg-check):
* lisp/calc/calc-store.el (calc-edit-variable):
* lisp/calc/calc-units.el (math-build-units-table-buffer):
* lisp/calc/calc-vec.el (math-read-brackets):
* lisp/calc/calc-yank.el (calc-edit-mode):
* lisp/calc/calc.el (calc, calc-do, calc-user-invocation):
* lisp/calendar/appt.el (appt-display-message):
* lisp/calendar/diary-lib.el (diary-check-diary-file)
(diary-mail-entries, diary-from-outlook):
* lisp/calendar/icalendar.el (icalendar-export-region)
(icalendar--convert-float-to-ical)
(icalendar--convert-date-to-ical)
(icalendar--convert-ical-to-diary)
(icalendar--convert-recurring-to-diary)
(icalendar--add-diary-entry):
* lisp/calendar/time-date.el (format-seconds):
* lisp/calendar/timeclock.el (timeclock-mode-line-display)
(timeclock-make-hours-explicit, timeclock-log-data):
* lisp/calendar/todo-mode.el (todo-prefix, todo-delete-category)
(todo-item-mark, todo-check-format)
(todo-insert-item--next-param, todo-edit-item--next-key)
(todo-mode):
* lisp/cedet/ede/pmake.el (ede-proj-makefile-insert-dist-rules):
* lisp/cedet/mode-local.el (describe-mode-local-overload)
(mode-local-print-binding, mode-local-describe-bindings-2):
* lisp/cedet/semantic/complete.el (semantic-displayor-show-request):
* lisp/cedet/srecode/srt-mode.el (srecode-macro-help):
* lisp/cus-start.el (standard):
* lisp/cus-theme.el (describe-theme-1):
* lisp/custom.el (custom-add-dependencies, custom-check-theme)
(custom--sort-vars-1, load-theme):
* lisp/descr-text.el (describe-text-properties-1, describe-char):
* lisp/dired-x.el (dired-do-run-mail):
* lisp/dired.el (dired-log):
* lisp/emacs-lisp/advice.el (ad-read-advised-function)
(ad-read-advice-class, ad-read-advice-name, ad-enable-advice)
(ad-disable-advice, ad-remove-advice, ad-set-argument)
(ad-set-arguments, ad--defalias-fset, ad-activate)
(ad-deactivate):
* lisp/emacs-lisp/byte-opt.el (byte-compile-inline-expand)
(byte-compile-unfold-lambda, byte-optimize-form-code-walker)
(byte-optimize-while, byte-optimize-apply):
* lisp/emacs-lisp/byte-run.el (defun, defsubst):
* lisp/emacs-lisp/bytecomp.el (byte-compile-lapcode)
(byte-compile-log-file, byte-compile-format-warn)
(byte-compile-nogroup-warn, byte-compile-arglist-warn)
(byte-compile-cl-warn)
(byte-compile-warn-about-unresolved-functions)
(byte-compile-file, byte-compile--declare-var)
(byte-compile-file-form-defmumble, byte-compile-form)
(byte-compile-normal-call, byte-compile-check-variable)
(byte-compile-variable-ref, byte-compile-variable-set)
(byte-compile-subr-wrong-args, byte-compile-setq-default)
(byte-compile-negation-optimizer)
(byte-compile-condition-case--old)
(byte-compile-condition-case--new, byte-compile-save-excursion)
(byte-compile-defvar, byte-compile-autoload)
(byte-compile-lambda-form)
(byte-compile-make-variable-buffer-local, display-call-tree)
(batch-byte-compile):
* lisp/emacs-lisp/cconv.el (cconv-convert, cconv--analyze-use):
* lisp/emacs-lisp/chart.el (chart-space-usage):
* lisp/emacs-lisp/check-declare.el (check-declare-scan)
(check-declare-warn, check-declare-file)
(check-declare-directory):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine)
(checkdoc-message-text-engine):
* lisp/emacs-lisp/cl-extra.el (cl-parse-integer)
(cl--describe-class):
* lisp/emacs-lisp/cl-generic.el (cl-defgeneric)
(cl--generic-describe, cl-generic-generalizers):
* lisp/emacs-lisp/cl-macs.el (cl--parse-loop-clause, cl-tagbody)
(cl-symbol-macrolet):
* lisp/emacs-lisp/cl.el (cl-unload-function, flet):
* lisp/emacs-lisp/copyright.el (copyright)
(copyright-update-directory):
* lisp/emacs-lisp/edebug.el (edebug-read-list):
* lisp/emacs-lisp/eieio-base.el (eieio-persistent-read):
* lisp/emacs-lisp/eieio-core.el (eieio--slot-override)
(eieio-oref):
* lisp/emacs-lisp/eieio-opt.el (eieio-help-constructor):
* lisp/emacs-lisp/eieio-speedbar.el:
(eieio-speedbar-child-make-tag-lines)
(eieio-speedbar-child-description):
* lisp/emacs-lisp/eieio.el (defclass, change-class):
* lisp/emacs-lisp/elint.el (elint-file, elint-get-top-forms)
(elint-init-form, elint-check-defalias-form)
(elint-check-let-form):
* lisp/emacs-lisp/ert.el (ert-get-test, ert-results-mode-menu)
(ert-results-pop-to-backtrace-for-test-at-point)
(ert-results-pop-to-messages-for-test-at-point)
(ert-results-pop-to-should-forms-for-test-at-point)
(ert-describe-test):
* lisp/emacs-lisp/find-func.el (find-function-search-for-symbol)
(find-function-library):
* lisp/emacs-lisp/generator.el (iter-yield):
* lisp/emacs-lisp/gv.el (gv-define-simple-setter):
* lisp/emacs-lisp/lisp-mnt.el (lm-verify):
* lisp/emacs-lisp/macroexp.el (macroexp--obsolete-warning):
* lisp/emacs-lisp/map-ynp.el (map-y-or-n-p):
* lisp/emacs-lisp/nadvice.el (advice--make-docstring)
(advice--make, define-advice):
* lisp/emacs-lisp/package-x.el (package-upload-file):
* lisp/emacs-lisp/package.el (package-version-join)
(package-disabled-p, package-activate-1, package-activate)
(package--download-one-archive)
(package--download-and-read-archives)
(package-compute-transaction, package-install-from-archive)
(package-install, package-install-selected-packages)
(package-delete, package-autoremove, describe-package-1)
(package-install-button-action, package-delete-button-action)
(package-menu-hide-package, package-menu--list-to-prompt)
(package-menu--perform-transaction)
(package-menu--find-and-notify-upgrades):
* lisp/emacs-lisp/pcase.el (pcase-exhaustive, pcase--u1):
* lisp/emacs-lisp/re-builder.el (reb-enter-subexp-mode):
* lisp/emacs-lisp/ring.el (ring-previous, ring-next):
* lisp/emacs-lisp/rx.el (rx-check, rx-anything)
(rx-check-any-string, rx-check-any, rx-check-not, rx-=)
(rx-repeat, rx-check-backref, rx-syntax, rx-check-category)
(rx-form):
* lisp/emacs-lisp/smie.el (smie-config-save):
* lisp/emacs-lisp/subr-x.el (internal--check-binding):
* lisp/emacs-lisp/tabulated-list.el (tabulated-list-put-tag):
* lisp/emacs-lisp/testcover.el (testcover-1value):
* lisp/emacs-lisp/timer.el (timer-event-handler):
* lisp/emulation/viper-cmd.el (viper-toggle-parse-sexp-ignore-comments)
(viper-toggle-search-style, viper-kill-buffer)
(viper-brac-function):
* lisp/emulation/viper-macs.el (viper-record-kbd-macro):
* lisp/env.el (setenv):
* lisp/erc/erc-button.el (erc-nick-popup):
* lisp/erc/erc.el (erc-cmd-LOAD, erc-handle-login, english):
* lisp/eshell/em-dirs.el (eshell/cd):
* lisp/eshell/em-glob.el (eshell-glob-regexp)
(eshell-glob-entries):
* lisp/eshell/em-pred.el (eshell-parse-modifiers):
* lisp/eshell/esh-opt.el (eshell-show-usage):
* lisp/facemenu.el (facemenu-add-new-face)
(facemenu-add-new-color):
* lisp/faces.el (read-face-name, read-face-font, describe-face)
(x-resolve-font-name):
* lisp/files-x.el (modify-file-local-variable):
* lisp/files.el (locate-user-emacs-file, find-alternate-file)
(set-auto-mode, hack-one-local-variable--obsolete)
(dir-locals-set-directory-class, write-file, basic-save-buffer)
(delete-directory, copy-directory, recover-session)
(recover-session-finish, insert-directory)
(file-modes-char-to-who, file-modes-symbolic-to-number)
(move-file-to-trash):
* lisp/filesets.el (filesets-add-buffer, filesets-remove-buffer):
* lisp/find-cmd.el (find-generic, find-to-string):
* lisp/finder.el (finder-commentary):
* lisp/font-lock.el (font-lock-fontify-buffer):
* lisp/format.el (format-write-file, format-find-file)
(format-insert-file):
* lisp/frame.el (get-device-terminal, select-frame-by-name):
* lisp/fringe.el (fringe--check-style):
* lisp/gnus/nnmairix.el (nnmairix-widget-create-query):
* lisp/help-fns.el (help-fns--key-bindings)
(help-fns--compiler-macro, help-fns--parent-mode)
(help-fns--obsolete, help-fns--interactive-only)
(describe-function-1, describe-variable):
* lisp/help.el (describe-mode)
(describe-minor-mode-from-indicator):
* lisp/image.el (image-type):
* lisp/international/ccl.el (ccl-dump):
* lisp/international/fontset.el (x-must-resolve-font-name):
* lisp/international/mule-cmds.el (prefer-coding-system)
(select-safe-coding-system-interactively)
(select-safe-coding-system, activate-input-method)
(toggle-input-method, describe-current-input-method)
(describe-language-environment):
* lisp/international/mule-conf.el (code-offset):
* lisp/international/mule-diag.el (describe-character-set)
(list-input-methods-1):
* lisp/mail/feedmail.el (feedmail-run-the-queue):
* lisp/mouse.el (minor-mode-menu-from-indicator):
* lisp/mpc.el (mpc-playlist-rename):
* lisp/msb.el (msb--choose-menu):
* lisp/net/ange-ftp.el (ange-ftp-shell-command):
* lisp/net/imap.el (imap-interactive-login):
* lisp/net/mairix.el (mairix-widget-create-query):
* lisp/net/newst-backend.el (newsticker--sentinel-work):
* lisp/net/newst-treeview.el (newsticker--treeview-load):
* lisp/net/rlogin.el (rlogin):
* lisp/obsolete/iswitchb.el (iswitchb-possible-new-buffer):
* lisp/obsolete/otodo-mode.el (todo-more-important-p):
* lisp/obsolete/pgg-gpg.el (pgg-gpg-process-region):
* lisp/obsolete/pgg-pgp.el (pgg-pgp-process-region):
* lisp/obsolete/pgg-pgp5.el (pgg-pgp5-process-region):
* lisp/org/ob-core.el (org-babel-goto-named-src-block)
(org-babel-goto-named-result):
* lisp/org/ob-fortran.el (org-babel-fortran-ensure-main-wrap):
* lisp/org/ob-ref.el (org-babel-ref-resolve):
* lisp/org/org-agenda.el (org-agenda-prepare):
* lisp/org/org-clock.el (org-clock-notify-once-if-expired)
(org-clock-resolve):
* lisp/org/org-ctags.el (org-ctags-ask-rebuild-tags-file-then-find-tag):
* lisp/org/org-feed.el (org-feed-parse-atom-entry):
* lisp/org/org-habit.el (org-habit-parse-todo):
* lisp/org/org-mouse.el (org-mouse-popup-global-menu)
(org-mouse-context-menu):
* lisp/org/org-table.el (org-table-edit-formulas):
* lisp/org/ox.el (org-export-async-start):
* lisp/proced.el (proced-log):
* lisp/progmodes/ada-mode.el (ada-get-indent-case)
(ada-check-matching-start, ada-goto-matching-start):
* lisp/progmodes/ada-prj.el (ada-prj-display-page):
* lisp/progmodes/ada-xref.el (ada-find-executable):
* lisp/progmodes/ebrowse.el (ebrowse-tags-apropos):
* lisp/progmodes/etags.el (etags-tags-apropos-additional):
* lisp/progmodes/flymake.el (flymake-parse-err-lines)
(flymake-start-syntax-check-process):
* lisp/progmodes/python.el (python-shell-get-process-or-error)
(python-define-auxiliary-skeleton):
* lisp/progmodes/sql.el (sql-comint):
* lisp/progmodes/verilog-mode.el (verilog-load-file-at-point):
* lisp/progmodes/vhdl-mode.el (vhdl-widget-directory-validate):
* lisp/recentf.el (recentf-open-files):
* lisp/replace.el (query-replace-read-from)
(occur-after-change-function, occur-1):
* lisp/scroll-bar.el (scroll-bar-columns):
* lisp/server.el (server-get-auth-key):
* lisp/simple.el (execute-extended-command)
(undo-outer-limit-truncate, list-processes--refresh)
(compose-mail, set-variable, choose-completion-string)
(define-alternatives):
* lisp/startup.el (site-run-file, tty-handle-args, command-line)
(command-line-1):
* lisp/subr.el (noreturn, define-error, add-to-list)
(read-char-choice, version-to-list):
* lisp/term/common-win.el (x-handle-xrm-switch)
(x-handle-name-switch, x-handle-args):
* lisp/term/x-win.el (x-handle-parent-id, x-handle-smid):
* lisp/textmodes/reftex-ref.el (reftex-label):
* lisp/textmodes/reftex-toc.el (reftex-toc-rename-label):
* lisp/textmodes/two-column.el (2C-split):
* lisp/tutorial.el (tutorial--describe-nonstandard-key)
(tutorial--find-changed-keys):
* lisp/type-break.el (type-break-noninteractive-query):
* lisp/wdired.el (wdired-do-renames, wdired-do-symlink-changes)
(wdired-do-perm-changes):
* lisp/whitespace.el (whitespace-report-region):
Prefer grave quoting in source-code strings used to generate help
and diagnostics.
* lisp/faces.el (face-documentation):
No need to convert quotes, since the result is a docstring.
* lisp/info.el (Info-virtual-index-find-node)
(Info-virtual-index, info-apropos):
Simplify by generating only curved quotes, since info files are
typically that ways nowadays anyway.
* lisp/international/mule-diag.el (list-input-methods):
Don’t assume text quoting style is curved.
* lisp/org/org-bibtex.el (org-bibtex-fields):
Revert my recent changes, going back to the old quoting style.
2015-09-07 15:41:44 +00:00
|
|
|
|
See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@end smallexample
|
|
|
|
|
|
Support curved quotes in doc strings
Emacs's traditional doc string style has been to quote symbols
`like this'. This worked well on now-obsolete terminals where
` and ' were symmetric quotes, but nowadays curved quotes
‘like this’ look better. Support quoting the new way too.
(Bug#20385)
* doc/lispref/tips.texi (Documentation Tips): Symbols can be quoted
‘like-this’ as well as `like-this'.
* etc/NEWS: Mention this.
* lisp/cedet/mode-local.el (overload-docstring-extension)
(mode-local-print-binding, mode-local-describe-bindings-2):
* lisp/cus-theme.el (describe-theme-1):
* lisp/descr-text.el (describe-text-properties-1, describe-char):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine):
* lisp/emacs-lisp/cl-generic.el (cl--generic-describe):
* lisp/emacs-lisp/eieio-opt.el (eieio-help-class)
(eieio-help-constructor):
* lisp/emacs-lisp/package.el (describe-package-1):
* lisp/faces.el (describe-face):
* lisp/help-fns.el (help-fns--key-bindings)
(help-fns--compiler-macro, help-fns--parent-mode, help-fns--obsolete):
(help-fns--interactive-only, describe-function-1):
(describe-variable):
* lisp/help.el (describe-mode):
* lisp/international/mule-cmds.el (describe-input-method)
(describe-language-environment):
* lisp/international/mule-diag.el (describe-character-set)
(print-coding-system-briefly, list-input-methods)
(list-input-methods-1):
Insert curved quotes rather than grave accent and apostrophe.
* lisp/cedet/srecode/texi.el (srecode-texi-texify-docstring):
* lisp/emacs-lisp/checkdoc.el (checkdoc-this-string-valid-engine)
(checkdoc-proper-noun-region-engine):
* lisp/emacs-lisp/lisp-mode.el (lisp-el-font-lock-keywords-2)
(lisp-cl-font-lock-keywords-2):
* lisp/finder.el (finder-font-lock-keywords):
* lisp/gnus/gnus-art.el (gnus-button-alist):
* lisp/help-fns.el (help-do-arg-highlight)
(describe-function-1, describe-variable):
* lisp/help-mode.el (help-xref-symbol-regexp)
(help-xref-info-regexp, help-xref-url-regexp):
* lisp/help.el (describe-mode):
* lisp/international/mule-cmds.el (help-xref-mule-regexp-template):
* lisp/wid-edit.el (widget-documentation-link-regexp):
Parse symbols quoted ‘like-this’ as well as `like-this'.
* lisp/progmodes/elisp-mode.el (emacs-lisp-mode):
Add "‘" and "’" to electric-pair-text-pairs.
(elisp--form-quoted-p): Also allow "‘" as a quoting char.
(elisp-completion-at-point, elisp--preceding-sexp):
Also treat "‘" and "’" as quoting chars.
2015-05-28 07:06:14 +00:00
|
|
|
|
Finally, to create a hyperlink to URLs, write the single-quoted URL,
|
|
|
|
|
preceded by @samp{URL}. For example,
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@smallexample
|
|
|
|
|
The home page for the GNU project has more information (see URL
|
2017-09-13 22:52:52 +00:00
|
|
|
|
`https://www.gnu.org/').
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@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 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
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
For consistency, phrase the verb in the first sentence of a function's
|
|
|
|
|
documentation string as an imperative---for instance, use ``Return the
|
2012-12-05 22:27:56 +00:00
|
|
|
|
cons of A and B.@:'' in preference to ``Returns the cons of A and B@.''
|
2007-09-06 04:25:08 +00:00
|
|
|
|
Usually it looks good to do likewise for the rest of the first
|
|
|
|
|
paragraph. Subsequent paragraphs usually look better if each sentence
|
|
|
|
|
is indicative and has a proper subject.
|
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
The documentation string for a function that is a yes-or-no predicate
|
2012-04-26 00:31:47 +00:00
|
|
|
|
should start with words such as ``Return t if'', to indicate
|
2015-09-15 15:46:48 +00:00
|
|
|
|
explicitly what constitutes truth. The word ``return'' avoids
|
2012-04-26 00:31:47 +00:00
|
|
|
|
starting the sentence with lower-case ``t'', which could be somewhat
|
2007-09-06 04:25:08 +00:00
|
|
|
|
distracting.
|
|
|
|
|
|
|
|
|
|
@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
|
|
|
|
|
Write documentation strings in the active voice, not the passive, and in
|
|
|
|
|
the present tense, not the future. For instance, use ``Return a list
|
2012-12-05 22:27:56 +00:00
|
|
|
|
containing A and B.@:'' instead of ``A list containing A and B will be
|
2007-09-06 04:25:08 +00:00
|
|
|
|
returned.''
|
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
Avoid using the word ``cause'' (or its equivalents) unnecessarily.
|
2012-04-26 00:31:47 +00:00
|
|
|
|
Instead of, ``Cause Emacs to display text in boldface'', write just
|
|
|
|
|
``Display text in boldface''.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
Avoid using ``iff'' (a mathematics term meaning ``if and only if''),
|
|
|
|
|
since many people are unfamiliar with it and mistake it for a typo. In
|
|
|
|
|
most cases, the meaning is clear with just ``if''. Otherwise, try to
|
|
|
|
|
find an alternate phrasing that conveys the meaning.
|
|
|
|
|
|
|
|
|
|
@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
|
2012-03-03 01:29:55 +00:00
|
|
|
|
When you define a variable that represents an option users might want
|
|
|
|
|
to set, use @code{defcustom}. @xref{Defining Variables}.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item
|
|
|
|
|
The documentation string for a variable that is a yes-or-no flag should
|
2012-04-26 00:31:47 +00:00
|
|
|
|
start with words such as ``Non-nil means'', to make it clear that
|
2007-09-06 04:25:08 +00:00
|
|
|
|
all non-@code{nil} values are equivalent and indicate explicitly what
|
|
|
|
|
@code{nil} and non-@code{nil} mean.
|
|
|
|
|
@end itemize
|
|
|
|
|
|
|
|
|
|
@node Comment Tips
|
|
|
|
|
@section Tips on Writing Comments
|
|
|
|
|
@cindex comments, Lisp convention for
|
|
|
|
|
|
2012-03-03 01:29:55 +00:00
|
|
|
|
We recommend these conventions for comments:
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@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
|
2012-03-03 01:29:55 +00:00
|
|
|
|
comments usually explain how the code on that line does its job.
|
|
|
|
|
For example:
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@smallexample
|
|
|
|
|
@group
|
2013-10-07 03:46:32 +00:00
|
|
|
|
(setq base-version-list ; There was a base
|
2007-09-06 04:25:08 +00:00
|
|
|
|
(assoc (substring fn 0 start-vn) ; version to which
|
|
|
|
|
file-version-assoc-list)) ; this looks like
|
2013-10-07 03:46:32 +00:00
|
|
|
|
; a subversion.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@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{}
|
2012-03-03 01:29:55 +00:00
|
|
|
|
;; Update mode line.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
(force-mode-line-update)))
|
|
|
|
|
@end group
|
|
|
|
|
@end smallexample
|
|
|
|
|
|
|
|
|
|
We also normally use two semicolons for comments outside functions.
|
|
|
|
|
|
|
|
|
|
@smallexample
|
|
|
|
|
@group
|
2012-03-03 01:29:55 +00:00
|
|
|
|
;; This Lisp code is run in Emacs when it is to operate as
|
|
|
|
|
;; a server for other processes.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@end group
|
|
|
|
|
@end smallexample
|
|
|
|
|
|
2012-03-03 01:29:55 +00:00
|
|
|
|
If a function has no documentation string, it 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. It is much better to convert such comments to documentation
|
|
|
|
|
strings, though.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item ;;;
|
|
|
|
|
Comments that start with three semicolons, @samp{;;;}, should start at
|
2013-10-07 03:46:32 +00:00
|
|
|
|
the left margin. We use them
|
|
|
|
|
for comments which should be considered a
|
2015-09-15 15:46:48 +00:00
|
|
|
|
heading by Outline minor mode. By default, comments starting with
|
2007-09-06 04:25:08 +00:00
|
|
|
|
at least three semicolons (followed by a single space and a
|
|
|
|
|
non-whitespace character) are considered headings, comments starting
|
2013-10-07 03:46:32 +00:00
|
|
|
|
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.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
When commenting out entire functions, use two semicolons.
|
|
|
|
|
|
|
|
|
|
@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
|
2012-03-03 01:29:55 +00:00
|
|
|
|
Generally speaking, the @kbd{M-;} (@code{comment-dwim}) command
|
|
|
|
|
automatically starts a comment of the appropriate type; or indents an
|
|
|
|
|
existing comment to the right place, depending on the number of
|
|
|
|
|
semicolons.
|
|
|
|
|
@xref{Comments,, Manipulating Comments, emacs, The GNU Emacs Manual}.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@node Library Headers
|
|
|
|
|
@section Conventional Headers for Emacs Libraries
|
|
|
|
|
@cindex header comments
|
|
|
|
|
@cindex library header comments
|
|
|
|
|
|
|
|
|
|
Emacs has conventions for using special comments in Lisp libraries
|
|
|
|
|
to divide them into sections and give information such as who wrote
|
2012-03-03 01:29:55 +00:00
|
|
|
|
them. Using a standard format for these items makes it easier for
|
|
|
|
|
tools (and people) to extract the relevant information. This section
|
|
|
|
|
explains these conventions, starting with an example:
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@smallexample
|
|
|
|
|
@group
|
2012-03-03 01:29:55 +00:00
|
|
|
|
;;; foo.el --- Support for the Foo programming language
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
2018-01-01 09:02:09 +00:00
|
|
|
|
;; Copyright (C) 2010-2018 Your Name
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@end group
|
|
|
|
|
|
2012-03-03 01:29:55 +00:00
|
|
|
|
;; Author: Your Name <yourname@@example.com>
|
|
|
|
|
;; Maintainer: Someone Else <someone@@example.com>
|
|
|
|
|
;; Created: 14 Jul 2010
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@group
|
2012-03-03 01:29:55 +00:00
|
|
|
|
;; Keywords: languages
|
2012-12-19 19:51:40 +00:00
|
|
|
|
;; Homepage: http://example.com/foo
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
2012-03-03 01:29:55 +00:00
|
|
|
|
;; This file is not part of GNU Emacs.
|
|
|
|
|
|
|
|
|
|
;; This file is free software@dots{}
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@dots{}
|
2017-09-13 22:52:52 +00:00
|
|
|
|
;; along with this file. If not, see <https://www.gnu.org/licenses/>.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@end group
|
|
|
|
|
@end smallexample
|
|
|
|
|
|
|
|
|
|
The very first line should have this format:
|
|
|
|
|
|
|
|
|
|
@example
|
|
|
|
|
;;; @var{filename} --- @var{description}
|
|
|
|
|
@end example
|
|
|
|
|
|
|
|
|
|
@noindent
|
2012-03-03 01:29:55 +00:00
|
|
|
|
The description should be contained in one line. If the file
|
2007-09-06 04:25:08 +00:00
|
|
|
|
needs a @samp{-*-} specification, put it after @var{description}.
|
2012-03-03 01:29:55 +00:00
|
|
|
|
If this would make the first line too long, use a Local Variables
|
|
|
|
|
section at the end of the file.
|
|
|
|
|
|
|
|
|
|
The copyright notice usually lists your name (if you wrote the
|
|
|
|
|
file). If you have an employer who claims copyright on your work, you
|
|
|
|
|
might need to list them instead. Do not say that the copyright holder
|
|
|
|
|
is the Free Software Foundation (or that the file is part of GNU
|
|
|
|
|
Emacs) unless your file has been accepted into the Emacs distribution.
|
|
|
|
|
For more information on the form of copyright and license notices, see
|
2017-09-13 22:52:52 +00:00
|
|
|
|
@uref{https://www.gnu.org/licenses/gpl-howto.html, the guide on the GNU
|
2012-03-03 01:29:55 +00:00
|
|
|
|
website}.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
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
|
2012-03-03 01:29:55 +00:00
|
|
|
|
This line states the name and email address of at least the principal
|
|
|
|
|
author of the library. If there are multiple authors, list them on
|
2012-12-19 19:51:40 +00:00
|
|
|
|
continuation lines led by @code{;;} and a tab or at least two spaces.
|
2012-03-03 01:29:55 +00:00
|
|
|
|
We recommend including a contact email address, of the form
|
|
|
|
|
@samp{<@dots{}>}. For example:
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@smallexample
|
|
|
|
|
@group
|
2012-03-03 01:29:55 +00:00
|
|
|
|
;; Author: Your Name <yourname@@example.com>
|
|
|
|
|
;; Someone Else <someone@@example.com>
|
|
|
|
|
;; Another Person <another@@example.com>
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@end group
|
|
|
|
|
@end smallexample
|
|
|
|
|
|
|
|
|
|
@item Maintainer
|
2012-03-03 01:29:55 +00:00
|
|
|
|
This header has the same format as the Author header. It lists the
|
|
|
|
|
person(s) who currently maintain(s) the file (respond to bug reports,
|
|
|
|
|
etc.).
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
2012-03-03 01:29:55 +00:00
|
|
|
|
If there is no maintainer line, the person(s) in the Author field
|
|
|
|
|
is/are presumed to be the maintainers. Some files in Emacs use
|
|
|
|
|
@samp{FSF} for the maintainer. This means that the original author is
|
|
|
|
|
no longer responsible for the file, and that it is maintained as part
|
|
|
|
|
of Emacs.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item Created
|
2012-03-03 01:29:55 +00:00
|
|
|
|
This optional line gives the original creation date of the file, and
|
|
|
|
|
is for historical interest only.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item Version
|
2012-03-03 01:29:55 +00:00
|
|
|
|
If you wish to record version numbers for the individual Lisp program,
|
|
|
|
|
put them in this line. Lisp files distributed with Emacs generally do
|
|
|
|
|
not have a @samp{Version} header, since the version number of Emacs
|
|
|
|
|
itself serves the same purpose. If you are distributing a collection
|
|
|
|
|
of multiple files, we recommend not writing the version in every file,
|
|
|
|
|
but only the main one.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@item Keywords
|
2015-11-28 12:32:04 +00:00
|
|
|
|
@vindex checkdoc-package-keywords-flag
|
|
|
|
|
@findex checkdoc-package-keywords
|
2007-09-06 04:25:08 +00:00
|
|
|
|
This line lists keywords for the @code{finder-by-keyword} help command.
|
2015-11-28 12:32:04 +00:00
|
|
|
|
Please use that command to see a list of the meaningful keywords. The
|
2018-01-31 18:59:12 +00:00
|
|
|
|
command @kbd{M-x checkdoc-package-keywords @key{RET}} will find and display
|
2015-11-28 12:32:04 +00:00
|
|
|
|
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.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
2012-03-03 01:29:55 +00:00
|
|
|
|
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,
|
|
|
|
|
commas, or both.
|
|
|
|
|
|
|
|
|
|
The name of this field is unfortunate, since people often assume it is
|
|
|
|
|
the place to write arbitrary keywords that describe their package,
|
|
|
|
|
rather than just the relevant Finder keywords.
|
2010-08-25 20:25:32 +00:00
|
|
|
|
|
2012-12-19 19:51:40 +00:00
|
|
|
|
@item Homepage
|
|
|
|
|
This line states the homepage of the library.
|
|
|
|
|
|
2010-08-25 20:25:32 +00:00
|
|
|
|
@item Package-Version
|
|
|
|
|
If @samp{Version} is not suitable for use by the package manager, then
|
|
|
|
|
a package can define @samp{Package-Version}; it will be used instead.
|
|
|
|
|
This is handy if @samp{Version} is an RCS id or something else that
|
|
|
|
|
cannot be parsed by @code{version-to-list}. @xref{Packaging Basics}.
|
|
|
|
|
|
|
|
|
|
@item Package-Requires
|
|
|
|
|
If this exists, it names packages on which the current package depends
|
|
|
|
|
for proper operation. @xref{Packaging Basics}. This is used by the
|
|
|
|
|
package manager both at download time (to ensure that a complete set
|
|
|
|
|
of packages is downloaded) and at activation time (to ensure that a
|
2012-03-03 01:29:55 +00:00
|
|
|
|
package is only activated if all its dependencies have been).
|
2010-08-25 20:25:32 +00:00
|
|
|
|
|
2017-03-25 04:58:44 +00:00
|
|
|
|
Its format is a list of lists on a single line. The @code{car} of
|
|
|
|
|
each sub-list is the name of a package, as a symbol. The @code{cadr}
|
|
|
|
|
of each sub-list is the minimum acceptable version number, as a string
|
|
|
|
|
that can be parse by @code{version-to-list}. An entry that lacks a
|
|
|
|
|
version (i.e., an entry which is just a symbol, or a sub-list of one
|
|
|
|
|
element) is equivalent to entry with version "0". For instance:
|
2010-08-25 20:25:32 +00:00
|
|
|
|
|
|
|
|
|
@smallexample
|
2017-03-25 04:58:44 +00:00
|
|
|
|
;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2") cl-lib (seq))
|
2010-08-25 20:25:32 +00:00
|
|
|
|
@end smallexample
|
|
|
|
|
|
|
|
|
|
The package code automatically defines a package named @samp{emacs}
|
|
|
|
|
with the version number of the currently running Emacs. This can be
|
|
|
|
|
used to require a minimal version of Emacs for a package.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@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
|
2012-03-03 01:29:55 +00:00
|
|
|
|
library file. These should be separated from anything else by blank
|
|
|
|
|
lines. Here is a table of them:
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
2012-12-31 20:06:43 +00:00
|
|
|
|
@cindex commentary, in a Lisp library
|
2007-09-06 04:25:08 +00:00
|
|
|
|
@table @samp
|
|
|
|
|
@item ;;; Commentary:
|
|
|
|
|
This begins introductory comments that explain how the library works.
|
|
|
|
|
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 ;;; Change Log:
|
2012-03-03 01:29:55 +00:00
|
|
|
|
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
|
2014-11-19 19:29:40 +00:00
|
|
|
|
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}.
|
2007-09-06 04:25:08 +00:00
|
|
|
|
|
|
|
|
|
@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
|