@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998, 1999, 2002, 2003,
-@c 2004, 2005 Free Software Foundation, Inc.
+@c 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/tips
@node Tips, GNU Emacs Internals, GPL, Top
benefits of a Common Lisp-style package system are considered not to
outweigh the costs.} Then take care to begin the names of all global
variables, constants, and functions in your program with the chosen
-prefix. This helps avoid name conflicts. (Occasionally, for a command
-name intended for users to use, it is cleaner if some words come
-before the package name prefix.)
+prefix. This helps avoid name conflicts.
+
+Occasionally, for a command name intended for users to use, it is more
+convenient if some words come before the package's name prefix. And
+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.
This recommendation applies even to names for traditional Lisp
primitives that are not primitives in Emacs Lisp---such as
It should look like this:
@example
-Enter the answer: (default 42)
+Enter the answer (default 42):
@end example
@item
include before the first blank line so as to make this display useful.
@item
-A variable's documentation string should start with @samp{*} if the
-variable is one that users would often want to set interactively. If
-the value is a long list, or a function, or if the variable would be set
-only in init files, then don't start the documentation string with
-@samp{*}. @xref{Defining Variables}.
+When you define a variable that users ought to set interactively, you
+normally should use @code{defcustom}. However, if for some reason you
+use @code{defvar} instead, start the doc string with a @samp{*}.
+@xref{Defining Variables}.
@item
The documentation string for a variable that is a yes-or-no flag should
If a symbol has a function definition and/or a variable definition, but
those are irrelevant to the use of the symbol that you are documenting,
-you can write the word @samp{symbol} before the symbol name to prevent
-making any hyperlink. For example,
+you can write the words @samp{symbol} or @samp{program} before the
+symbol name to prevent making any hyperlink. For example,
@example
If the argument KIND-OF-RESULT is the symbol `list',
See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
@end smallexample
+Finally, to create a hyperlink to URLs, write the URL in single
+quotes, preceded by @samp{URL}. For example,
+
+@smallexample
+The home page for the GNU project has more information (see URL
+`http://www.gnu.org/').
+@end smallexample
+
@item
Don't write key sequences directly in documentation strings. Instead,
use the @samp{\\[@dots{}]} construct to stand for them. For example,
HCoop / bpt / emacs.git / blobdiff