Mercurial > emacs
view doc/lispref/customize.texi @ 107863:594e81986a75
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-insert-link): Find the link buffer on visible
frames.
(org-export-latex-default-packages-alist): hyperref must be loaded
late.
(org-open-file): More care with the new matching for file links.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-latex.el (org-export-latex-preprocess): Do not yet protect
defined entities - these will be taken care of later.
(org-export-latex-special-chars): Post-process entity replacement.
(org-export-latex-fontify-headline): Do not yet protect defined
entities - these will be taken care of later.
(org-export-latex-tables, org-export-latex-links): Format the
caption properly.
* org-entities.el (org-entities-user): Fix typo.
* org.el (org-prepare-agenda-buffers): Uniquify TODO keywords
* org-entities.el (org-entities-user): Improve docstring.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-entities.el (org-macs): Require org-macs, to be sure that we
have `declare-function' defined.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-latex.el (org-export-latex-classes): Update docstring.
* org.el (org-format-latex-header): Add cookies to the header.
(org-splice-latex-header): Implement placement according to
cookies.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-publish.el (org-publish-aux-preprocess): Control case
sensitivity.
2010-04-10 Bastien Guerry <bzg@altern.org>
* org.el (org-splice-latex-header): Fix typo.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-latex.el (org-export-latex-make-header): Use
`org-splice-latex-header' to build the header.
(org-export-latex-classes): Update docstring.
* org.el (org-splice-latex-header): New function.
(org-create-formula-image): Use `org-splice-latex-header' to build
the header.
* org-gnus.el (org-gnus-follow-link): Handle nndoc backend.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-export-latex-packages-alist)
(org-export-latex-default-packages-alist): Fix docstring to
reflect the expected structure.
* org-docbook.el (org-docbook-do-expand): Fix bug with variable names.
(org-export-docbook-finalize-table): Make use of label for tables.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-attach.el (org-attach-commit): Split on newlines.
* org.el (org-export-latex-default-packages-alist): Use list
instead of cons for the entries.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-entities.el (org-entity-get-representation): Catch the case
that there is not entry in the list.
* org-mobile.el (org-mobile-use-encryption)
(org-mobile-encryption-tempfile, org-mobile-encryption-password):
New options.
(org-mobile-check-setup): CHeck the encryption setup.
(org-mobile-copy-agenda-files, org-mobile-sumo-agenda-command)
(org-mobile-create-sumo-agenda): Use encryption code.
(org-mobile-encrypt-and-move): New function.
(org-mobile-encrypt-file, org-mobile-decrypt-file): New
functions.
(org-mobile-move-capture): Decrypt the capture file.
* org.el (org-entities): Require the new file.
(org-export-latex-default-packages-alist): New variable.
(org-complete): Use new entity code for completion.
(org-create-formula-image): Use the new packages variable.
* org-latex.el (org-export-latex-classes): Remove the standard
packages from the class headers.
(org-export-latex-make-header): Use the new package variable.
(org-export-latex-special-chars): Better regexp for entities, to
support entity name that contain numbers.
(org-export-latex-treat-backslash-char): Use the new entity code.
* org-html.el (org-html-do-expand): Use the new entity code.
* org-exp.el (org-export): Add the new export commands.
(org-html-entities): Constant removed.
(org-export-visible): Add the new export commands.
* org-entities.el: New file.
* org-docbook.el (org-docbook-do-expand): Use new entity code.
* org-ascii.el (org-export-ascii-entities): New variable.
(org-export-as-latin1, org-export-as-latin1-to-buffer)
(org-export-as-utf8, org-export-as-utf8-to-buffer): New commands.
(org-export-as-encoding): New function.
(org-export-ascii-preprocess): Call `org-ascii-replace-entities'.
(org-ascii-replace-entities): New function.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-html.el (org-html-level-start): Catch the case that target
might be nil.
2010-04-10 Dan Davison <davison@stats.ox.ac.uk>
* org.el (org-appearance): Change Customize group variable name
from org-font-lock to org-appearance, and change tag from "Org
Font Lock" to "Org Appearance"
(org-odd-levels-only): Change Customize group variable name
(org-level-color-stars-only): Change Customize group variable name
(org-hide-leading-stars): Change Customize group variable name
(org-hidden-keywords): Change Customize group variable name
(org-fontify-done-headline): Change Customize group variable name
(org-fontify-emphasized-text): Change Customize group variable name
(org-fontify-whole-heading-line): Change Customize group variable name
(org-highlight-latex-fragments-and-specials): Change Customize
group variable name
(org-hide-emphasis-markers): Change Customize group variable name
(org-emphasis-alist): Change Customize group variable name
(org-emphasis-regexp-components): Change Customize group variable
name
(org-modules): Remove mention of org-R
* org-faces.el (org-faces): Change Customize group variable name
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-agenda.el (org-diary-last-run-time): New variable.
(org-diary): prepare agenda buffers only if last call was some
time ago.
* org-html.el (org-export-html-preprocess): Replace \ref macros
with a link.
(org-format-org-table-html): Add the label as an anchor.
* org-docbook.el (org-export-docbook-format-image): Do some
formatting on captions.
* org-latex.el (org-export-latex-tables, org-export-latex-links):
Do some formatting on captions.
* org-html.el (org-export-html-format-image)
(org-format-org-table-html): Do some formatting on captions.
2010-04-10 Dan Davison <davison@stats.ox.ac.uk>
* org.el (org-hidden-keywords): New customizable variable. This is
a list of symbols specifying which of the special keywords #+DATE,
#+AUTHOR, #+EMAIL and #+TITLE should be hidden by font lock.
(org-fontify-meta-lines-and-blocks): Changes to font-lock code
implementing new faces and hiding behaviour.
* org-faces.el (org-document-title): New face for #+TITLE lines
(org-document-info): New face for #+DATE, #+AUTHOR, #+EMAIL lines
(org-document-info-keyword): New face for #+DATE, #+AUTHOR, #+EMAIL keywords
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-publish.el (org-publish-sanitize-plist): New function to
rename "index" properties to "sitemap". Do this renaming
globally.
(org-publish-with-aux-preprocess-maybe): New macro.
(org-publish-org-to-pdf, org-publish-org-to-html): Use the new
macro.
(org-publish-aux-preprocess)
(org-publish-index-generate-theindex.inc): New function.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-table.el (org-table-align): Interpret <N> at fixed width,
not as maximum width.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-exp.el (org-export-author-info, org-export-email-info): Fix
docstrings.
* org-beamer.el (org-beamer-select-environment): Renamed from
`org-beamer-set-environment-tag'. Improve docstring.
* org-freemind.el (org-freemind-write-mm-buffer): Fix another
problem with odd levels.
* org-ascii.el (org-export-as-ascii): Export email only if the
author wants it.
* org-docbook.el (org-export-as-docbook): Export email only if the
author wants it.
* org-html.el (org-export-as-html): Export email only if the
author wants it.
* org-exp.el (org-export-email-info): New option.
(org-export-plist-vars): Add entry for `org-export-email'.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-table.el (org-table-goto-line): Fix typo.
2010-04-10 Mikael Fornius <mfo@abc.se>
* org.el (org-agenda-files): Typo.
(org-read-agenda-file-list): Add optional argument to help
`org-store-new-agenda-file-list' to remember un-expanded file
names. Expand file names relative to `org-directory'.
(org-store-new-agenda-file-list): Keep un-expanded file names when
saving, if available.
(org-agenda-files): Update documentation.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-ascii.el (org-export-as-ascii): Catch the case of exporting
a buffer with no file name attached.
* org.el (org-log-refile): New option.
(org-log-note-headings): Add a heading for refiling.
(org-startup-options): Add keywords for logging of the refile
action.
(org-refile): Add logging action.
(org-add-log-note): Allow for refiling action.
* org-agenda.el (org-agenda-bulk-action): Make sure
`org-log-refile' is not `note' during a bulk action.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-map-dblocks): Use save-excursion to remember the
position.
* org-attach.el (org-attach-commit): Remove dependence on xargs.
(org-attach-delete-one): Commit after deleting a file.
* org-latex.el (org-export-latex-fontify): Do not mistake table.el
borders for strike-through emphasis.
* org-freemind.el (org-freemind-write-mm-buffer): Simplify the
handling of odd levels.
* org-agenda.el (org-agenda-todo-ignore-deadlines): Document `past'
and `future' values.
(org-agenda-check-for-timestamp-as-reason-to-ignore-todo-item):
Handle `past' and `future' values.
* org.el (org-read-agenda-file-list): Interpret file names
relative to org-directory and allow environment variables and
"~".
* org-latex.el (org-export-latex-special-chars): Allow a
parenthesis before an exponent or subscript.
2010-04-10 Dan Davison <davison@stats.ox.ac.uk>
* org-src.el (org-edit-src-exit): When returning from code edit
buffer, if code block is hidden, leave point at start of
#+begin_src line
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-insert-heading): Do not remove all spaces if the
headline is empty.
* org-indent.el (org-indent): Fix group name.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-table.el (org-table-goto-column): Fix forcing a non-existing
column.
(org-table-get, org-table-put, org-table-goto-line)
(org-table-current-line): New functions.
2010-04-10 Jan Bcker <jan.boecker@jboecker.de>
* org.el (org-open-file): Allow regular expressions in
org-file-apps to capture link parameters using groups. In a
command string to be executed, the parameters can be referenced
using %1, %2, etc. Lisp forms can access them using
(match-string n link).
(org-apps-regexp-alist): Adopt the created regexp, as this is now
matched against a file: link instead of the file name.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-crypt.el (org-reveal-start-hook): Add a decryption function
to this hook.
(org-decrypt-entries, org-encrypt-entries, org-decrypt-entry): Add
docstrings.
* org.el (org-point-at-end-of-empty-headline)
(org-level-increment, org-get-previous-line-level): New function.
(org-cycle-level): Rewritten to be independent of when this
function is called.
(org-in-regexps-block-p): New function.
(org-reveal-start-hook): New hook.
(org-reveal): Run new hook.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-latex.el (org-export-latex-keywords): Start a new paragraph
after time keywords, do not add "\newline".
* org-html.el (org-export-as-html): Avoid double # in href.
* org.el (org-refile-get-location): Catch an invalid target
specification.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-agenda.el (org-agenda-add-entry-to-org-agenda-diary-file):
Make sure the behavior regarding to extracting time is
consistent.
2010-04-10 Stephen Eglen <stephen@gnu.org>
* org-agenda.el (org-agenda-insert-diary-extract-time): New
variable.
(org-agenda-add-entry-to-org-agenda-diary-file): Use this new
variable rather than `org-agenda-search-headline-for-time'.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-list.el (org-fix-bullet-type): Improve cursor positioning.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-adaptive-fill-regexp-backup): New variable.
(org-set-autofill-regexps): Store a backup of
`adaptive-fill-regexp'.
(org-adaptive-fill-function): Fix filling of comments and ordered
lists. If there is no other match, till try adaptive fill.
2010-04-10 John Wiegley <jwiegley@gmail.com>
* org-agenda.el (org-agenda-include-deadlines): Added new
customization variable to determine whether unscheduled tasks
should appear in the agenda solely because of their deadline.
Default to true, which was the previous behavior (it just wasn't
configurable).
(org-agenda-mode-map, org-agenda-view-mode-dispatch): Bind ! in
the agenda to show/hide deadline tasks.
(org-agenda-menu): Added menu option for show/hide deadlines.
(org-agenda-list): Make the agenda list sensitive to the value of
`org-agenda-include-deadlines'.
(org-agenda-toggle-deadlines): New function to toggle the value of
`org-agenda-include-deadlines' and repaint the modeline
indicators.
(org-agenda-set-mode-name): Show "Deadlines" in the agenda
modeline if deadline tasks are being displayed.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-table.el (org-table-eval-formula): Replace $# and @# by
current column and row number.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-set-property, org-delete-property): Go back to
prompting for the property.
* org-latex.el (org-export-latex-make-header): Fully process
author line.
(org-export-latex-fontify-headline): Allow several arguments, not
just one.
(org-export-latex-fix-inputenc): Catch the error when
`latexenc-coding-system-to-inputenc' is not defined.
* org-agenda.el (org-agenda-skip-if-todo): New function.
(org-agenda-skip-if): Add conditions for TODO keywords.
(org-agenda-skip-if): Document the new todo conditions.
2010-04-10 Mikael Fornius <mfo@abc.se>
* org.el (org-at-property-p): Check if we are inside a property
drawer not just any drawer.
(org-set-property, org-delete-property): When cursor is on a
property key value pair do not prompt for property name instead
use name at cursor.
(org-ctrl-c-ctrl-c): Still do org-property-action when cursor is
on the first line of a property drawer.
(org-property-end-re): Spell check.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-exp.el (org-export-attach-captions-and-attributes): Add the
properties to the entire table, in case the first line is
removed.
* org-archive.el (org-archive-reversed-order): New option.
(org-archive-subtree, org-archive-to-archive-sibling): Use the new
option `org-archive-reversed-order'.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-agenda.el (org-agenda-entry-types): New variable.
(org-agenda-list): Use `org-agenda-entry-types'.
(org-agenda-custom-commands-local-options): Support for setting
`org-agenda-entry-types' as an option.
(org-diary): Shift some documentation from here to the variable
`org-agenda-entry-types'.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-latex.el (org-export-latex-make-header): Apply macros in
author field.
* org-clock.el (org-clocking-buffer, org-clocking-p): New function.
(org-clock-select-task, org-clock-notify-once-if-expired)
(org-clock-in, org-clock-out, org-clock-cancel, org-clock-goto)
(org-clock-out-if-current, org-clock-save): Use the new functions.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-docbook.el (org-export-as-docbook): Remove unnecessary
newline.
(org-export-as-docbook): Remove unnecessary newline.
(org-export-as-docbook): Fix problem with double footnote
reference in one place.
* org-exp.el (org-export-format-source-code-or-example): Remove
unnecessary newline.
* org.el (org-deadline, org-schedule): Allow rescheduling entries
with repeaters.
* org-table.el (org-table-convert-refs-to-rc): Better way to catch
function calls that look like references.
* org.el (org-open-at-point): Get link abbreviations from
reference buffer.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-table.el (org-table-convert-refs-to-rc): Do not read arctan2
as a reference.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-link-unescape): Solve issue with lower-case escapes.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-latex.el (org-export-latex-classes): Add
\usepackage{latexsym} to all classes.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-html.el (org-export-as-html): Do not allow protected lines
into the table of contents.
* org-latex.el (org-export-latex-special-chars): Find subsequent
occurrences of special characters.
(org-export-latex-tables): Do not convert table-like stuff that is
protected.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-list.el (org-toggle-checkbox): No errors when updating
checkbox count fails because there is no heading.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-clock.el (org-clock-report-include-clocking-task): New
option.
(org-clock-sum): Add the current clocking task.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-cycle): Print a message when in a table.el table.
(org-edit-special): Recognize the table.el context.
(org-ctrl-c-ctrl-c): Print a message when in a table.el table.
* org-src.el (org-at-table.el-p): Declare.
(org-edit-src-code): Handle a special case for table.el editing.
(org-edit-src-find-region-and-lang): Recognize the table.el
context.
* org-latex.el (org-export-latex-tables): Convert table.el
tables.
(org-export-latex-convert-table.el-table): New function.
* org-html.el (org-html-expand): Fix table.el export.
* org-latex.el (org-export-latex-preprocess): Protect footnotes in
headings.
* org-id.el (org-id-find-id-file): Fix bug when there is no hash
table for the id locations.
* org.el (org-read-date-analyze): Match American-style dates, like
5/30 or 5/13/7. Make sure cal-iso.el is loaded. Don't force he
current year when reading ISO and American dates.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-face-from-face-or-color): New function.
(org-get-todo-face, org-font-lock-add-priority-faces)
(org-get-tag-face): Use `org-face-from-face-or-color'.
* org-faces.el (org-todo-keyword-faces, org-priority-faces): Allow
simple colors as values.
(org-faces-easy-properties): New option.
* org-agenda.el (org-agenda-set-mode-name): Show if the agenda is
restricted, as an agenda mode.
(org-agenda-fontify-priorities): Allow simple colors as values.
2010-04-10 Bastien Guerry <bzg@altern.org>
* org-timer.el (org-timer-current-timer): Renamed from
`org-timer-last-timer'.
(org-timer-timer1, org-timer-timer2, org-timer-timer3): Removed.
(org-timer-cancel-timer, org-timer-show-remaining-time)
(org-timer-set-timer): Update to use only one timer.
* org.el (org-set-property): Remove useless space in the prompt.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-html.el (org-export-html-style-default): Add a default style
for textareas.
* org-exp.el (org-export-format-source-code-or-example): Fix
textarea tag.
2010-04-10 Bastien Guerry <bzg@altern.org>
* org-clock.el (org-clock-current-task): New variable to store
last clocked in task.
(org-clock-set-current, org-clock-delete-current): New functions.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-remember.el (org-remember-apply-template): Extend comment.
(org-remember-handler): Implement clock sibling filing.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-publish.el (org-publish-all, org-publish-current-file)
(org-publish-current-project): When called with prefix argument
FORCE, also rebuild the validation file list.
* org-latex.el (org-export-latex-preprocess): Protect footnotes in
section headings.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-html.el (org-export-as-html-and-open): Kill product buffer
if the user wants that.
* org-latex.el (org-export-as-pdf-and-open): Kill product buffer
if the user wants that.
* org-exp.el (org-export-kill-product-buffer-when-displayed): New
option.
* org-agenda.el (org-batch-agenda-csv): Use the time property
instead of the `time-of-day' property.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-timer.el (org-timer-start-hook, org-timer-stop-hook)
(org-timer-pause-hook, org-timer-set-hook)
(org-timer-cancel-hook): New hooks.
(org-timer-start): Run `org-timer-start-hook'.
(org-timer-pause-or-continue): Run `org-timer-pause-hook'.
(org-timer-stop): Run `org-timer-stop-hook'.
(org-timer-cancel-timers): Run `org-timer-cancel-hook'.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-reveal): Double prefix arg shows the subtree of the
parent.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-agenda.el (org-search-view): Fix bug with searching full
words in headlines in search view.
(org-agenda-skip-deadline-prewarning-if-scheduled): New option.
(org-agenda-get-deadlines): Suppress pre-warning if the entry is
scheduled (if the user configures it so.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-hide-archived-subtrees): Don't jump to end of
subtree if the match was not in a headline.
(org-inside-latex-macro-p): Allow more complex arguments.
(org-emphasize): Protect against use at end of buffer.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-agenda.el (org-agenda-align-tags): Avoid side effects on
text properties.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-agenda.el (org-agenda-todo-ignore-scheduled): More allowed
values.
(org-agenda-todo-ignore-scheduled)
(org-agenda-todo-ignore-deadlines): More control with different
allowed values.
(org-agenda-check-for-timestamp-as-reason-to-ignore-todo-item):
Honor the new option settings.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-get-location): Make sure the selection buffer is
shown in the current frame.
* org-ascii.el (org-export-ascii-table-widen-columns): New
option.
(org-export-ascii-preprocess): Realign tables to remove narrowing
if `org-export-ascii-table-widen-columns' is set.
* org-table.el (org-table-do-narrow): New variable.
(org-table-align): Narrow only if `org-table-do-narrow' is t.
* org.el (org-deadline, org-schedule): Allow updating if the
relevant time stamp does not have a repeater, i.e. do not require
that no time stamp has a repeater.
* org-agenda.el (org-agenda-align-tags): Don't add a face to the
new white space before the tags.
* org-latex.el (org-export-as-latex): Do nit require the buffer to
be visiting a file when only exporting to a buffer or string.
(org-export-latex-fix-inputenc): Only save the buffer is there is
a file name attached to it.
2010-04-10 Dan Davison <davison@stats.ox.ac.uk>
* org-src.el (org-edit-src-exit): Widen before exiting edit buffers
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-fontify-meta-lines-and-blocks): Honor
`org-fontify-quote-and-verse-blocks'.
* org-faces.el (org-fontify-quote-and-verse-blocks): New option.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-open-at-point): Also check for text property
org-linked-text before offering collected links.
2010-04-10 Stephen Eglen <stephen@gnu.org>
* org-agenda.el (org-agenda-add-entry-to-org-agenda-diary-file):
Optionally extract time specification from text and add to the
timestamp.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-exp.el (org-html-entities): Fix typo.
* org-latex.el (org-export-latex-make-header): Use \providecommand
to make sure the \alert macro is defined.
* org.el (org-format-latex-signal-error)
(org-create-formula-image): Use `org-format-latex-signal-error'.
2010-04-10 Stephen Eglen <stephen@gnu.org>
* org.el (org-store-link): For dired buffers, use
default-directory as link name if dired-get-filename returns
nil.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-exp.el (org-export-concatenate-multiline-links): The for
protectedness at beginning of match.
* org-latex.el (org-export-latex-fix-inputenc): Never leave the
AUTO as a coding system, instead default to utf8.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-block-todo-from-children-or-siblings-or-parent)
(org-block-todo-from-checkboxes): Respect the local variable
value when deciding if blocking should be active.
* org-latex.el (org-export-latex-make-header): Define the align
macro if it is not yet defined.
* org-agenda.el (org-agenda-insert-diary-make-new-entry): Call
`org-insert-heading' with the INVISIBLE-OK argument.
* org-mac-message.el (org-mac-message-insert-flagged): Call
`org-insert-heading' with the INVISIBLE-OK argument.
* org.el (org-insert-heading): New argument INVISIBLE-OK.
* org-agenda.el (org-agenda-view-mode-dispatch): Improve the
prompt message.
* org-html.el (org-html-level-start): Use the
`html-container-class' text property to set an additional class
for an outline container.
* org-exp.el (org-export-remember-html-container-classes): New
function.
(org-export-preprocess-string): Call
`org-export-remember-html-container-classes'.
* org.el (org-cycle): Mention level cycling in the docstring.
(org-default-properties): Add new property HTML_CONTAINER_CLASS.
* org-remember.el (org-remember-apply-template): Do file insertion
first.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-habit.el (org-habit-insert-consistency-graphs): Fix a
problem with mis-aligned graphs when showing habits.
2010-04-10 Mikael Fornius <mfo@abc.se>
* org.el (org-assign-fast-keys): Prefer keys used in keyword name
when assigning. Begin using numerical characters when all in name
is used up. This is to spare alphanumeric characters for better
match with other keywords.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-exp.el (org-export-preprocess-hook): Improve documentation.
* org-latex.el (org-export-latex-preprocess): More consistent
conversion and protection of the words LaTeX and TeX.
(org-export-latex-fontify-headline, org-export-latex-preprocess):
Allow angle brackets in commands, for beamer.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-clock.el (org-clock-in): Improve the look of the clock line
by formatting links.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-latex.el (org-export-latex-classes): Use AUTO as the place
holder string for the coding system. And improve the
documentation.
(org-export-latex-fix-inputenc): Only modify the coding system if
it is given by the placeholder AUTO.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-clock.el (org-task-overrun-text): New option.
(org-task-overrun, org-clock-update-period): New variables.
(org-clock-get-clock-string, org-clock-update-mode-line): Mark
overrun clock.
(org-clock-notify-once-if-expired): Check if clock is overrun.
* org-faces.el: New face `org-mode-line-clock-overrun'.
2010-04-10 Jan Bcker <jan.boecker@jboecker.de>
* org.el (org-narrow-to-subtree): Position the end of the narrowed
region before the line with the next heading, to prevent the user
from prepending text to the next headline.
2010-04-10 Stephen Eglen <stephen@gnu.org>
* org-agenda.el (org-get-time-of-day): Use
org-agenda-time-leading-zero to allow leading zero (rather than
space) for times.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-agenda.el (org-agenda-diary-entry-in-org-file): Make sure
org-datetree.el is loaded.
* org-datetree.el: autoload `org-datetree-find-day-create'
* org-latex.el (org-export-latex-hyperref-format): New option.
(org-export-latex-links): Use `org-export-latex-hyperref-format'.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-ctags.el (org-ctags-enable): Change order of functions.
(org-ctags-create-tags): Add wildcard to file name expansion.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-entry-properties): Fix some important bugs.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-link-unescape, org-link-escape): Only use hexlify if
the table is not explicitly given.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-clock.el (org-clock-out-when-done): Allow a list of keywords
as value.
(org-clock-out-if-current): Work with the new list value of
`org-clock-out-when-done'.
(org-clock-out, org-clock-out-if-current): Avoid circular logic
between clocking out and state changes.
* org-ctags.el (org-ctags-path-to-ctags): Better system-type test.
* org-latex.el (org-export-latex-treat-backslash-char): Do not by
accident protect a character that is before a backslash.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-agenda.el (org-diary-class): Use
`org-order-calendar-date-args'.
* org.el (org-order-calendar-date-args): New function.
* org-exp.el (org-export-target-internal-links): Check for
protectedness after the first bracket.
* org.el (org-entry-properties): Don't match wrong-case TODO
keywords.
* org-agenda.el (org-agenda-schedule, org-agenda-deadline):
Document that ARG is passed through to remove the date.
(org-agenda-bulk-action): Accept prefix arg and pass it on. Do
not read a date when the user has given a `C-u' prefix.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-agenda.el (org-agenda-fix-displayed-tags): Fix bug when all
tags are hidden.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-latex.el (org-export-latex-fix-inputenc): New function.
(org-export-latex-inputenc-alist): New option.
* org-exp.el (org-export): New key SPC to publish enclosing
subtree.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-indent.el (org-indent-add-properties): Catch case when there
is no headline in the buffer.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-exp.el (org-html-entities): Add checkmark symbol.
* org-ascii.el (org-export-ascii-preprocess): Protect targets in
verbatim code for ASCII export.
* org.el (org-update-statistics-cookies): Also see checkboxes in
ordered lists.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-agenda.el (org-agenda-view-mode-dispatch): Define the `L'
key.
* org-beamer.el (org-beamer-amend-header): Change the location
where `org-beamer-header-extra' is inserted.
* org.el (org-compute-latex-and-specials-regexp): Don't do BIND
just for computing this regexp.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-beamer.el (org-beamer-frame-default-options): New option.
(org-beamer-sectioning): Use default options if the user does not
have defined any.
(org-beamer-fix-toc): Put a frame around the table of contents.
* org-exp.el (org-export-remove-comment-blocks-and-subtrees): Make
sure case-folding works well when processing comment stuff.
* org-latex.el (org-export-latex-after-save-hook): New hook.
(org-export-as-latex): Run the new hook.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-beamer.el (org-beamer-environments-default): Add the note
environments.
(org-beamer-after-initial-vars): Allow several BEAMER_HEADER_EXTRA
lines and collect and combine the content.
(org-beamer-after-initial-vars): Check for note tags and make sure
they will be seen like a property.
* org.el (org-offer-links-in-entry): Fix bug when there is a
single link.
* org-exp.el (org-export): Make sure the mark is activated, also
when `transient-mark-mode' is off.
* org-agenda.el (org-agenda-search-view-always-boolean): New option.
(org-agenda-search-view-search-words-only): Obsolete variable, is
now an alias for `org-agenda-search-view-always-boolean'.
(org-agenda-search-view-force-full-words): New option.
(org-search-view): Improve docstring, and implement a better logic
for Boolean and phrase searches.
(org-agenda-last-search-view-search-was-boolean): New variable.
(org-agenda-manipulate-query): Consider the type of the last
search when modifying the search string.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-latex.el (org-export-as-latex): Do the first letbind in the
right moment.
* org-agenda.el (org-get-entries-from-diary): Add the new face to
these entries.
* org-faces.el (org-agenda-diary): New face.
* org.el (org-make-link-regexps): Allow regexp-special characters
in link types.
(org-open-file): When in-emacs is `system', also force system
opening, like when the value was `(16)'.
(org-update-statistics-cookies): Handle entries without children.
* org-exp.el
(org-export-preprocess-before-normalizing-links-hook): New hook.
(org-export-preprocess-string): Run the new hook.
* org.el (org-offer-links-in-entry): Make RET open all links.
* org-html.el (org-export-as-html): Remove any leftover display
properties in the html file.
* org-wl.el (org-wl-store-link): Work-around for format bug with
text properties.
* org-habit.el (org-habit-insert-consistency-graphs): Turn off
invisibility while adding the graphs.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-remember.el (org-select-remember-template): Use C letter to
customize remember templates.
* org-agenda.el (org-agenda-bulk-mark, org-agenda-bulk-unmark):
Move cursor to next visible line.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-beamer.el (org-beamer-sectioning): Leave columns environment
by specifying 0 or 1 for column width.
(org-beamer-column-widths): Make 0 stand for 0.0.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-exp.el (org-export-mark-radio-links): Don't match inside
<<target>>.
* org.el (org-format-latex-header-extra): New variable.
(org-format-latex): Set org-format-latex-header-extra from
in-buffer stuff.
(org-format-latex): Add org-format-latex-header-extra to the
variables on which image creation depends.
(org-create-formula-image): Add the header stuff from in-buffer
settings.
(org-read-date-analyze): Base the analysis for future preference
on NOW, not on the default date.
* org-inlinetask.el (org-inlinetask-export-handler): Add CSS class
for TODO keyword in inline tasks.
* org.el (org-log-note-headings): New headings for removing
deadline or scheduling date.
(org-deadline, org-schedule): Arrange for logging when removing a
date.
(org-add-log-note): Handle deadline and scheduling removal.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-exp.el (org-export-visible): Add LaTeX/pdf export.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-agenda.el (org-diary-class): New function.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-latex.el (org-export-latex-preprocess): Do process the text
of a radio target.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-entry-properties): Add TIMESTAMP properties back
in.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-all-time-keywords): New variable.
(org-set-regexps-and-options): Set `org-all-time-keywords'.
(org-entry-blocked-p): New function.
(org-special-properties): Add BLOCKED as a new special property.
(org-entry-properties): New optional argument SPECIFIC, only parse
for this property when it is specified.
(org-entry-get): Pass a SPECIFIC argument to
`org-entry-properties'.
* org-latex.el (org-export-as-latex): Preprocess TEXT as well.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-latex.el (org-export-latex-tables): No forced line end if
there is no caption.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-exp.el (org-html-entities): Add Euro symbols from Marvosym
package.
* org-latex.el (org-export-latex-tables): Only add a caption when
macro in in longtable environments if one has been defined.
* org-html.el (org-export-as-html): Only take title from buffer if
not exporting body-only.
* org-latex.el (org-export-latex-preprocess): Better version of
the regular expression for protecting LaTeX macros.
(org-export-latex-preprocess): Start searching for macros to
protect from beginning of buffer.
* org-exp.el (org-export-target-internal-links): Check for
protectedness earlier in the string.
* org-agenda.el (org-agenda-highlight-todo): Match TODO keywords
case sensitively.
* org-id.el (org-id-store-link): Match TODO keywords case
sensitively.
* org.el (org-heading-components, org-get-outline-path)
(org-display-outline-path): Match TODO keywords case sensitively.
* org-latex.el (org-export-as-latex): Ignore read-only
properties.
* org-exp.el (org-export-preprocess-string): Remove any
`read-only' properties.
* org-agenda.el (org-agenda-inactive-leader): New option.
(org-agenda-get-timestamps): Use `org-agenda-inactive-leader'.
(org-tags-view): Prompt for matcher if MATCH is an empty string.
(org-todo-list): Prompt for matcher if ARG is an empty string.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-open-link-functions): New hook.
(org-open-at-point): Run `org-open-link-functions'.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-agenda.el (org-agenda-date-prompt): Allow inactive time
stamps as well.
* org.el (org-inhibit-startup-visibility-stuff): New variable.
(org-mode): Don't do startup visibility if inhibited.
(org-outline-overlay-data, org-set-outline-overlay-data): New
functions.
(org-save-outline-visibility): New macro.
(org-log-note-headings): Document that one should not change the
`state' note format.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-make-link-regexps): Capture link path into a group.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-beamer.el (org-beamer-after-initial-vars): Do not overwrite
the options plist.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org.el (org-startup-with-beamer-mode): New option.
(org-property-changed-functions)
(org-property-allowed-value-functions): New hooks.
(org-entry-put, org-property-get-allowed-values): Run the new
hooks.
(org-property-next-allowed-value): Run the new hooks.
* org-exp.el (org-export-select-backend-specific-text): Add the
special beamer tags.
* org-beamer.el
(org-export-preprocess-before-selecting-backend-code-hook): New
file.
* org-latex.el (org-export-latex-after-initial-vars-hook): New hook.
(org-export-as-latex): Run
`org-export-latex-after-initial-vars-hook'.
(org-export-latex-format-toc-function)
(org-export-latex-make-header): Call
`org-export-latex-format-toc-function'.
* org.el (org-fill-template): Make template searches case sensitive.
* org-exp.el (org-export): Use "1" as a sign to export only the
subtree.
* org-colview-xemacs.el (org-columns-edit-value): Use
org-unrestricted property.
* org-colview.el (org-columns-edit-value): Use
org-unrestricted property.
* org.el (org-compute-property-at-point): Set org-unrestricted
text property if the list contains ":ETC".
(org-insert-property-drawer): Use
org-unrestricted property.
* org-exp.el
(org-export-preprocess-before-selecting-backend-code-hook): New hook.
(org-export-preprocess-string): Run
`org-export-preprocess-before-selecting-backend-code-hook'.
* org-xoxo.el (org-export-as-xoxo): Run `org-export-first-hook'.
* org-latex.el (org-export-region-as-latex): Run
`org-export-first-hook'.
* org-html.el (org-export-as-html): Run `org-export-first-hook'.
* org-docbook.el (org-export-as-docbook): Run
`org-export-first-hook'.
* org-ascii.el (org-export-as-ascii): Run `org-export-first-hook'.
* org-exp.el (org-export-first-hook): New hook.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-list.el (org-previous-item): Exit at the beginning of the
buffer.
* org-id.el (org-id-locations-save): Only write the id locations
if any are defined.
* org-archive.el (org-archive-all-done): Make this work in a file
with org-odd-levels-only set.
* org.el (org-get-refile-targets): Catch the case when a buffer
has no file.
* org-latex.el (org-export-as-latex): Cleanup forced line ends
where they are not needed.
(org-export-latex-subcontent): Remove unnecessary newlines.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-latex.el (org-export-latex-make-header): Remove \obeylines.
(org-export-latex-fontify): Fix regexp bug that takes special
care of protecting the right boundary characters in emphasis
matches.
(org-export-latex-preprocess): Allow multiple arguments to latex
macros.
* org.el (org-make-link-regexps): Use John Gruber's regexp for
urls.
* org-macs.el (org-re): Interpret :punct: in regexps.
* org-exp.el (org-export-replace-src-segments-and-examples): Also
take the final newline after the END line.
* org.el (org-clean-visibility-after-subtree-move): Only fix
entries that are not entirely invisible already.
(org-insert-link): Respect org-link-file-path-type for
"docview:" links in addition to "file:" links.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-exp.el (org-export-format-source-code-or-example): Avoid
additional extra white lines in LaTeX.
* org-list.el (org-list-parse-list): Leave empty lines after the
list, don't consider them as part of the list.
* org-mobile.el (org-mobile-sumo-agenda-command): Allow tagstodo
searches.
* org-clock.el (org-clock-select-task): Convert integer to
character for XEmacs.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-clock.el (org-clock-resolve): Make reading a char XEmacs
compatible.
2010-04-10 Tassilo Horn <tassilo@member.fsf.org>
* org.el (org-complete-tags-always-offer-all-agenda-tags): New
variable.
(org-set-tags): Use it.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-list.el (org-empty-line-terminates-plain-lists): Update
docstring.
* org.el (org-format-latex): Fix link creation for processed latex
snippets.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-footnote.el (org-footnote-normalize): Protect replacement
text.
* org.el (org-inside-latex-macro-p): Save match data.
2010-04-10 Jan Bcker <jan.boecker@jboecker.de>
* org-docview.el: New file.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-latex.el (org-export-latex-class-options): New variable.
(org-export-latex-set-initial-vars): Use the class options.
* org.el (org-forward-same-level): Stop at headings that start
with an invisible character.
(org-additional-option-like-keywords): Add LaTeX_CLASS_OPTIONS.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-footnote.el (org-footnote-normalize): Don't take optional
arguments in LaTeX macros as footnotes.
* org.el (org-inside-latex-macro-p): New function.
* org-latex.el (org-latex-to-pdf-process): Change customization
group to `org-export-pdf'.
* org-agenda.el (org-agenda-get-blocks): Look at time string also
on days after the first one.
* org.el (org-insert-heading): Also check for item before assuming
before-first-heading condition.
* org-latex.el (org-latex-to-pdf-process): Fix typo in group tag.
(org-export-pdf-logfiles): New option.
(org-export-as-pdf): Use `org-export-pdf-logfiles'.
(org-export-pdf-logfiles): Fix customization type.
* org.el (org-insert-link): Improve error message when there is no
default link to select with RET.
* org-agenda.el (org-agenda-filter-by-tag): Use char argument from
parameter list.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-latex.el (org-export-latex-parse-global)
(org-export-latex-parse-content)
(org-export-latex-parse-subcontent): Use
`org-re-search-forward-unprotected'.
(org-export-as-pdf): Remove log files produced by XeTeX.
* org-macs.el (org-re-search-forward-unprotected): New function.
2010-04-10 James TD Smith <ahktenzero@mohorovi.cc>
* org-colview.el (org-agenda-colview-summarize): Sort out some
confusion between properties and titles, which resulted in
agenda summaries not working if a title was set for a column.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-mobile.el (org-mobile-agendas): New option.
(org-mobile-sumo-agenda-command): Select the right agendas.
* org-latex.el (org-export-latex-format-image): Preserve the
original-indentation property.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-clock.el (org-clock-insert-selection-line): Catch error when
an old tasks no longer exists.
* org-latex.el (org-export-as-pdf): Remove also the .idx file.
(org-export-as-pdf): Don't remove the old PDF file before making
the new one.
* org-mouse.el (org-mouse-end-headline, org-mouse-insert-item)
(org-mouse-context-menu): Use `org-looking-back'.
* org.el (org-cycle-level): Use `org-looking-back'.
* org-list.el (org-cycle-item-indentation): Use
`org-looking-back'.
* org-compat.el (org-looking-back): New function.
* org.el (org-insert-heading): Catch before-first-headline when
inserting a headline.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-latex.el (org-export-latex-format-image): Indent figure
environment, so that it does not interrupt plain list.
* org.el (org-open-at-point): Allow long link descriptions.
2010-04-10 Carsten Dominik <carsten.dominik@gmail.com>
* org-html.el (org-export-as-html): Remove empty lines at the
beginning of the exported text.
2010-04-15 Carsten Dominik <carsten.dominik@gmail.com>
* org.texi (LaTeX and PDF export): Add a footnote about xetex.
(LaTeX/PDF export commands): Section renamed and
moved.
(Sectioning structure): Update.
(References): New use case for field coordinates.
(The export dispatcher): Renamed from ASCII export.
(Setting up the staging area): Document the availability of
encryption for MobileOrg.
(Images and tables): Document how to reference labels.
(Index entries): New section.
(Generating an index): New section.
(Column width and alignment): Document that <N> now
means a fixed width, not a maximum width.
(Publishing options): Document the :email option.
(Beamer class export): Fix bug in the BEAMER example.
(Refiling notes): Document refile logging.
(In-buffer settings): Document refile logging keywords.
(Drawers): Document `C-c C-z' command.
(Agenda commands): Mention the alternative key `C-c C-z'.
(Special properties): Document the BLOCKED property.
(The spreadsheet): Mention the formula editor.
(References): Document field coordinates.
(Publishing action): Correct the documentation for the
publishing function.
(The date/time prompt): Document that we accept dates
like month/day/year.
(Cooperation): Document the changes in table.el support.
(Faces for TODO keywords, Faces for TODO keywords)
(Priorities): Document the easy colors.
(Visibility cycling): Document the new double prefix
arg for `org-reveal'.
(Cooperation): Remember.el is part of Emacs.
(Clean view): Mention that `wrap-prefix' is also set by
org-indent-mode.
(Agenda commands): Add information about prefix args to
scheduling and deadline commands.
(Search view): Point to the docstring of
`org-search-view' for more details.
(Agenda commands): Document that `>' prompts for a
date.
(Setting tags): Document variable
org-complete-tags-always-offer-all-agenda-tags.
(Column attributes): Cross-reference special
properties.
author | Carsten Dominik <carsten.dominik@gmail.com> |
---|---|
date | Thu, 15 Apr 2010 12:11:52 +0200 |
parents | 1d1d5d9bd884 |
children | d53ab813a8d6 |
line wrap: on
line source
@c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. @c Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, @c 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/customize @node Customization, Loading, Macros, Top @chapter Writing Customization Definitions @cindex customization definitions This chapter describes how to declare user options for customization, and also customization groups for classifying them. We use the term @dfn{customization item} to include both kinds of customization definitions---as well as face definitions (@pxref{Defining Faces}). @menu * Common Keywords:: Common keyword arguments for all kinds of customization declarations. * Group Definitions:: Writing customization group definitions. * Variable Definitions:: Declaring user options. * Customization Types:: Specifying the type of a user option. @end menu @node Common Keywords @section Common Item Keywords @cindex customization keywords All kinds of customization declarations (for variables and groups, and for faces) accept keyword arguments for specifying various information. This section describes some keywords that apply to all kinds. All of these keywords, except @code{:tag}, can be used more than once in a given item. Each use of the keyword has an independent effect. The keyword @code{:tag} is an exception because any given item can only display one name. @table @code @item :tag @var{label} @kindex tag@r{, customization keyword} Use @var{label}, a string, instead of the item's name, to label the item in customization menus and buffers. @strong{Don't use a tag which is substantially different from the item's real name; that would cause confusion.} @kindex group@r{, customization keyword} @item :group @var{group} Put this customization item in group @var{group}. When you use @code{:group} in a @code{defgroup}, it makes the new group a subgroup of @var{group}. If you use this keyword more than once, you can put a single item into more than one group. Displaying any of those groups will show this item. Please don't overdo this, since the result would be annoying. @item :link @var{link-data} @kindex link@r{, customization keyword} Include an external link after the documentation string for this item. This is a sentence containing an active field which references some other documentation. There are several alternatives you can use for @var{link-data}: @table @code @item (custom-manual @var{info-node}) Link to an Info node; @var{info-node} is a string which specifies the node name, as in @code{"(emacs)Top"}. The link appears as @samp{[Manual]} in the customization buffer and enters the built-in Info reader on @var{info-node}. @item (info-link @var{info-node}) Like @code{custom-manual} except that the link appears in the customization buffer with the Info node name. @item (url-link @var{url}) Link to a web page; @var{url} is a string which specifies the @acronym{URL}. The link appears in the customization buffer as @var{url} and invokes the WWW browser specified by @code{browse-url-browser-function}. @item (emacs-commentary-link @var{library}) Link to the commentary section of a library; @var{library} is a string which specifies the library name. @item (emacs-library-link @var{library}) Link to an Emacs Lisp library file; @var{library} is a string which specifies the library name. @item (file-link @var{file}) Link to a file; @var{file} is a string which specifies the name of the file to visit with @code{find-file} when the user invokes this link. @item (function-link @var{function}) Link to the documentation of a function; @var{function} is a string which specifies the name of the function to describe with @code{describe-function} when the user invokes this link. @item (variable-link @var{variable}) Link to the documentation of a variable; @var{variable} is a string which specifies the name of the variable to describe with @code{describe-variable} when the user invokes this link. @item (custom-group-link @var{group}) Link to another customization group. Invoking it creates a new customization buffer for @var{group}. @end table You can specify the text to use in the customization buffer by adding @code{:tag @var{name}} after the first element of the @var{link-data}; for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to the Emacs manual which appears in the buffer as @samp{foo}. An item can have more than one external link; however, most items have none at all. @item :load @var{file} @kindex load@r{, customization keyword} Load file @var{file} (a string) before displaying this customization item (@pxref{Loading}). Loading is done with @code{load}, and only if the file is not already loaded. @item :require @var{feature} @kindex require@r{, customization keyword} Execute @code{(require '@var{feature})} when your saved customizations set the value of this item. @var{feature} should be a symbol. The most common reason to use @code{:require} is when a variable enables a feature such as a minor mode, and just setting the variable won't have any effect unless the code which implements the mode is loaded. @item :version @var{version} @kindex version@r{, customization keyword} This keyword specifies that the item was first introduced in Emacs version @var{version}, or that its default value was changed in that version. The value @var{version} must be a string. @item :package-version '(@var{package} . @var{version}) @kindex package-version@r{, customization keyword} This keyword specifies that the item was first introduced in @var{package} version @var{version}, or that its meaning or default value was changed in that version. The value of @var{package} is a symbol and @var{version} is a string. This keyword takes priority over @code{:version}. @var{package} should be the official name of the package, such as MH-E or Gnus. If the package @var{package} is released as part of Emacs, @var{package} and @var{version} should appear in the value of @code{customize-package-emacs-version-alist}. @end table Packages distributed as part of Emacs that use the @code{:package-version} keyword must also update the @code{customize-package-emacs-version-alist} variable. @defvar customize-package-emacs-version-alist This alist provides a mapping for the versions of Emacs that are associated with versions of a package listed in the @code{:package-version} keyword. Its elements look like this: @example (@var{package} (@var{pversion} . @var{eversion})@dots{}) @end example For each @var{package}, which is a symbol, there are one or more elements that contain a package version @var{pversion} with an associated Emacs version @var{eversion}. These versions are strings. For example, the MH-E package updates this alist with the following: @smallexample (add-to-list 'customize-package-emacs-version-alist '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1") ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1") ("7.4" . "22.1") ("8.0" . "22.1"))) @end smallexample The value of @var{package} needs to be unique and it needs to match the @var{package} value appearing in the @code{:package-version} keyword. Since the user might see the value in a error message, a good choice is the official name of the package, such as MH-E or Gnus. @end defvar @node Group Definitions @section Defining Customization Groups @cindex define customization group @cindex customization groups, defining Each Emacs Lisp package should have one main customization group which contains all the options, faces and other groups in the package. If the package has a small number of options and faces, use just one group and put everything in it. When there are more than twelve or so options and faces, then you should structure them into subgroups, and put the subgroups under the package's main customization group. It is OK to put some of the options and faces in the package's main group alongside the subgroups. The package's main or only group should be a member of one or more of the standard customization groups. (To display the full list of them, use @kbd{M-x customize}.) Choose one or more of them (but not too many), and add your group to each of them using the @code{:group} keyword. The way to declare new customization groups is with @code{defgroup}. @defmac defgroup group members doc [keyword value]@dots{} Declare @var{group} as a customization group containing @var{members}. Do not quote the symbol @var{group}. The argument @var{doc} specifies the documentation string for the group. The argument @var{members} is a list specifying an initial set of customization items to be members of the group. However, most often @var{members} is @code{nil}, and you specify the group's members by using the @code{:group} keyword when defining those members. If you want to specify group members through @var{members}, each element should have the form @code{(@var{name} @var{widget})}. Here @var{name} is a symbol, and @var{widget} is a widget type for editing that symbol. Useful widgets are @code{custom-variable} for a variable, @code{custom-face} for a face, and @code{custom-group} for a group. When you introduce a new group into Emacs, use the @code{:version} keyword in the @code{defgroup}; then you need not use it for the individual members of the group. In addition to the common keywords (@pxref{Common Keywords}), you can also use this keyword in @code{defgroup}: @table @code @item :prefix @var{prefix} @kindex prefix@r{, @code{defgroup} keyword} If the name of an item in the group starts with @var{prefix}, then the tag for that item is constructed (by default) by omitting @var{prefix}. One group can have any number of prefixes. @end table @end defmac The prefix-discarding feature is currently turned off, which means that @code{:prefix} currently has no effect. We did this because we found that discarding the specified prefixes often led to confusing names for options. This happened because the people who wrote the @code{defgroup} definitions for various groups added @code{:prefix} keywords whenever they make logical sense---that is, whenever the variables in the library have a common prefix. In order to obtain good results with @code{:prefix}, it would be necessary to check the specific effects of discarding a particular prefix, given the specific items in a group and their names and documentation. If the resulting text is not clear, then @code{:prefix} should not be used in that case. It should be possible to recheck all the customization groups, delete the @code{:prefix} specifications which give unclear results, and then turn this feature back on, if someone would like to do the work. @node Variable Definitions @section Defining Customization Variables @cindex define customization options @cindex customization variables, how to define Use @code{defcustom} to declare user-customizable variables. @defmac defcustom option standard doc [keyword value]@dots{} This macro declares @var{option} as a customizable @dfn{user option}. You should not quote @var{option}. This causes the function @code{user-variable-p} to return @code{t} when given @var{option} as an argument. @xref{Defining Variables}. The argument @var{doc} specifies the documentation string for the variable. (Note that there is no need to start @var{doc} with a @samp{*}.) The argument @var{standard} is an expression that specifies the standard value for @var{option}. Evaluating the @code{defcustom} form evaluates @var{standard}, but does not necessarily install the standard value. If @var{option} already has a default value, @code{defcustom} does not change it. If the user has saved a customization for @var{option}, @code{defcustom} installs the user's customized value as @var{option}'s default value. If neither of those cases applies, @code{defcustom} installs the result of evaluating @var{standard} as the default value. The expression @var{standard} can be evaluated at various other times, too---whenever the customization facility needs to know @var{option}'s standard value. So be sure to use an expression which is harmless to evaluate at any time. We recommend avoiding backquotes in @var{standard}, because they are not expanded when editing the value, so list values will appear to have the wrong structure. Every @code{defcustom} should specify @code{:group} at least once. If you specify the @code{:set} keyword, to make the variable take other special actions when set through the customization buffer, the variable's documentation string should tell the user specifically how to do the same job in hand-written Lisp code. When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun} arranges to set the variable unconditionally, without testing whether its value is void. (The same feature applies to @code{defvar}.) @xref{Defining Variables}. If you put a @code{defcustom} in a file that is preloaded at dump time (@pxref{Building Emacs}), and the standard value installed for the variable at that time might not be correct, use @code{custom-reevaluate-setting}, described below, to re-evaluate the standard value during or after Emacs startup. @end defmac @code{defcustom} accepts the following additional keywords: @table @code @item :type @var{type} Use @var{type} as the data type for this option. It specifies which values are legitimate, and how to display the value. @xref{Customization Types}, for more information. @item :options @var{value-list} @kindex options@r{, @code{defcustom} keyword} Specify the list of reasonable values for use in this option. The user is not restricted to using only these values, but they are offered as convenient alternatives. This is meaningful only for certain types, currently including @code{hook}, @code{plist} and @code{alist}. See the definition of the individual types for a description of how to use @code{:options}. @item :set @var{setfunction} @kindex set@r{, @code{defcustom} keyword} Specify @var{setfunction} as the way to change the value of this option. The function @var{setfunction} should take two arguments, a symbol (the option name) and the new value, and should do whatever is necessary to update the value properly for this option (which may not mean simply setting the option as a Lisp variable). The default for @var{setfunction} is @code{set-default}. @item :get @var{getfunction} @kindex get@r{, @code{defcustom} keyword} Specify @var{getfunction} as the way to extract the value of this option. The function @var{getfunction} should take one argument, a symbol, and should return whatever customize should use as the ``current value'' for that symbol (which need not be the symbol's Lisp value). The default is @code{default-value}. You have to really understand the workings of Custom to use @code{:get} correctly. It is meant for values that are treated in Custom as variables but are not actually stored in Lisp variables. It is almost surely a mistake to specify @code{getfunction} for a value that really is stored in a Lisp variable. @item :initialize @var{function} @kindex initialize@r{, @code{defcustom} keyword} @var{function} should be a function used to initialize the variable when the @code{defcustom} is evaluated. It should take two arguments, the option name (a symbol) and the value. Here are some predefined functions meant for use in this way: @table @code @item custom-initialize-set Use the variable's @code{:set} function to initialize the variable, but do not reinitialize it if it is already non-void. @item custom-initialize-default Like @code{custom-initialize-set}, but use the function @code{set-default} to set the variable, instead of the variable's @code{:set} function. This is the usual choice for a variable whose @code{:set} function enables or disables a minor mode; with this choice, defining the variable will not call the minor mode function, but customizing the variable will do so. @item custom-initialize-reset Always use the @code{:set} function to initialize the variable. If the variable is already non-void, reset it by calling the @code{:set} function using the current value (returned by the @code{:get} method). This is the default @code{:initialize} function. @item custom-initialize-changed Use the @code{:set} function to initialize the variable, if it is already set or has been customized; otherwise, just use @code{set-default}. @item custom-initialize-safe-set @itemx custom-initialize-safe-default These functions behave like @code{custom-initialize-set} (@code{custom-initialize-default}, respectively), but catch errors. If an error occurs during initialization, they set the variable to @code{nil} using @code{set-default}, and throw no error. These two functions are only meant for options defined in pre-loaded files, where some variables or functions used to compute the option's value may not yet be defined. The option normally gets updated in @file{startup.el}, ignoring the previously computed value. Because of this typical usage, the value which these two functions compute normally only matters when, after startup, one unsets the option's value and then reevaluates the defcustom. By that time, the necessary variables and functions will be defined, so there will not be an error. @end table @item :risky @var{value} @kindex risky@r{, @code{defcustom} keyword} Set the variable's @code{risky-local-variable} property to @var{value} (@pxref{File Local Variables}). @item :safe @var{function} @kindex safe@r{, @code{defcustom} keyword} Set the variable's @code{safe-local-variable} property to @var{function} (@pxref{File Local Variables}). @item :set-after @var{variables} @kindex set-after@r{, @code{defcustom} keyword} When setting variables according to saved customizations, make sure to set the variables @var{variables} before this one; in other words, delay setting this variable until after those others have been handled. Use @code{:set-after} if setting this variable won't work properly unless those other variables already have their intended values. @end table It is useful to specify the @code{:require} keyword for an option that ``turns on'' a certain feature. This causes Emacs to load the feature, if it is not already loaded, whenever the option is set. @xref{Common Keywords}. Here is an example, from the library @file{saveplace.el}: @example (defcustom save-place nil "Non-nil means automatically save place in each file..." :type 'boolean :require 'saveplace :group 'save-place) @end example If a customization item has a type such as @code{hook} or @code{alist}, which supports @code{:options}, you can add additional values to the list from outside the @code{defcustom} declaration by calling @code{custom-add-frequent-value}. For example, if you define a function @code{my-lisp-mode-initialization} intended to be called from @code{emacs-lisp-mode-hook}, you might want to add that to the list of reasonable values for @code{emacs-lisp-mode-hook}, but not by editing its definition. You can do it thus: @example (custom-add-frequent-value 'emacs-lisp-mode-hook 'my-lisp-mode-initialization) @end example @defun custom-add-frequent-value symbol value For the customization option @var{symbol}, add @var{value} to the list of reasonable values. The precise effect of adding a value depends on the customization type of @var{symbol}. @end defun Internally, @code{defcustom} uses the symbol property @code{standard-value} to record the expression for the standard value, @code{saved-value} to record the value saved by the user with the customization buffer, and @code{customized-value} to record the value set by the user with the customization buffer, but not saved. @xref{Property Lists}. These properties are lists, the car of which is an expression that evaluates to the value. @defun custom-reevaluate-setting symbol This function re-evaluates the standard value of @var{symbol}, which should be a user option declared via @code{defcustom}. (If the variable was customized, this function re-evaluates the saved value instead.) This is useful for customizable options that are defined before their value could be computed correctly, such as variables defined in packages that are loaded at dump time, but depend on the run-time information. For example, the value could be a file whose precise name depends on the hierarchy of files when Emacs runs, or a name of a program that needs to be searched at run time. A good place to put calls to this function is in the function @code{command-line} that is run during startup (@pxref{Startup Summary}) or in the various hooks it calls. @end defun @node Customization Types @section Customization Types @cindex customization types When you define a user option with @code{defcustom}, you must specify its @dfn{customization type}. That is a Lisp object which describes (1) which values are legitimate and (2) how to display the value in the customization buffer for editing. @kindex type@r{, @code{defcustom} keyword} You specify the customization type in @code{defcustom} with the @code{:type} keyword. The argument of @code{:type} is evaluated, but only once when the @code{defcustom} is executed, so it isn't useful for the value to vary. Normally we use a quoted constant. For example: @example (defcustom diff-command "diff" "The command to use to run diff." :type '(string) :group 'diff) @end example In general, a customization type is a list whose first element is a symbol, one of the customization type names defined in the following sections. After this symbol come a number of arguments, depending on the symbol. Between the type symbol and its arguments, you can optionally write keyword-value pairs (@pxref{Type Keywords}). Some type symbols do not use any arguments; those are called @dfn{simple types}. For a simple type, if you do not use any keyword-value pairs, you can omit the parentheses around the type symbol. For example just @code{string} as a customization type is equivalent to @code{(string)}. All customization types are implemented as widgets; see @ref{Top, , Introduction, widget, The Emacs Widget Library}, for details. @menu * Simple Types:: Simple customization types: sexp, integer, number, string, file, directory, alist. * Composite Types:: Build new types from other types or data. * Splicing into Lists:: Splice elements into list with @code{:inline}. * Type Keywords:: Keyword-argument pairs in a customization type. * Defining New Types:: Give your type a name. @end menu @node Simple Types @subsection Simple Types This section describes all the simple customization types. @table @code @item sexp The value may be any Lisp object that can be printed and read back. You can use @code{sexp} as a fall-back for any option, if you don't want to take the time to work out a more specific type to use. @item integer The value must be an integer, and is represented textually in the customization buffer. @item number The value must be a number (floating point or integer), and is represented textually in the customization buffer. @item float The value must be a floating point number, and is represented textually in the customization buffer. @item string The value must be a string, and the customization buffer shows just the contents, with no delimiting @samp{"} characters and no quoting with @samp{\}. @item regexp Like @code{string} except that the string must be a valid regular expression. @item character The value must be a character code. A character code is actually an integer, but this type shows the value by inserting the character in the buffer, rather than by showing the number. @item file The value must be a file name, and you can do completion with @kbd{M-@key{TAB}}. @item (file :must-match t) The value must be a file name for an existing file, and you can do completion with @kbd{M-@key{TAB}}. @item directory The value must be a directory name, and you can do completion with @kbd{M-@key{TAB}}. @item hook The value must be a list of functions (or a single function, but that is obsolete usage). This customization type is used for hook variables. You can use the @code{:options} keyword in a hook variable's @code{defcustom} to specify a list of functions recommended for use in the hook; see @ref{Variable Definitions}. @item alist The value must be a list of cons-cells, the @sc{car} of each cell representing a key, and the @sc{cdr} of the same cell representing an associated value. The user can add and delete key/value pairs, and edit both the key and the value of each pair. You can specify the key and value types like this: @smallexample (alist :key-type @var{key-type} :value-type @var{value-type}) @end smallexample @noindent where @var{key-type} and @var{value-type} are customization type specifications. The default key type is @code{sexp}, and the default value type is @code{sexp}. The user can add any key matching the specified key type, but you can give some keys a preferential treatment by specifying them with the @code{:options} (see @ref{Variable Definitions}). The specified keys will always be shown in the customize buffer (together with a suitable value), with a checkbox to include or exclude or disable the key/value pair from the alist. The user will not be able to edit the keys specified by the @code{:options} keyword argument. The argument to the @code{:options} keywords should be a list of specifications for reasonable keys in the alist. Ordinarily, they are simply atoms, which stand for themselves as. For example: @smallexample :options '("foo" "bar" "baz") @end smallexample @noindent specifies that there are three ``known'' keys, namely @code{"foo"}, @code{"bar"} and @code{"baz"}, which will always be shown first. You may want to restrict the value type for specific keys, for example, the value associated with the @code{"bar"} key can only be an integer. You can specify this by using a list instead of an atom in the list. The first element will specify the key, like before, while the second element will specify the value type. For example: @smallexample :options '("foo" ("bar" integer) "baz") @end smallexample Finally, you may want to change how the key is presented. By default, the key is simply shown as a @code{const}, since the user cannot change the special keys specified with the @code{:options} keyword. However, you may want to use a more specialized type for presenting the key, like @code{function-item} if you know it is a symbol with a function binding. This is done by using a customization type specification instead of a symbol for the key. @smallexample :options '("foo" ((function-item some-function) integer) "baz") @end smallexample Many alists use lists with two elements, instead of cons cells. For example, @smallexample (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) "Each element is a list of the form (KEY VALUE).") @end smallexample @noindent instead of @smallexample (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3)) "Each element is a cons-cell (KEY . VALUE).") @end smallexample Because of the way lists are implemented on top of cons cells, you can treat @code{list-alist} in the example above as a cons cell alist, where the value type is a list with a single element containing the real value. @smallexample (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) "Each element is a list of the form (KEY VALUE)." :type '(alist :value-type (group integer))) @end smallexample The @code{group} widget is used here instead of @code{list} only because the formatting is better suited for the purpose. Similarly, you can have alists with more values associated with each key, using variations of this trick: @smallexample (defcustom person-data '(("brian" 50 t) ("dorith" 55 nil) ("ken" 52 t)) "Alist of basic info about people. Each element has the form (NAME AGE MALE-FLAG)." :type '(alist :value-type (group integer boolean))) (defcustom pets '(("brian") ("dorith" "dog" "guppy") ("ken" "cat")) "Alist of people's pets. In an element (KEY . VALUE), KEY is the person's name, and the VALUE is a list of that person's pets." :type '(alist :value-type (repeat string))) @end smallexample @item plist The @code{plist} custom type is similar to the @code{alist} (see above), except that the information is stored as a property list, i.e. a list of this form: @smallexample (@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{}) @end smallexample The default @code{:key-type} for @code{plist} is @code{symbol}, rather than @code{sexp}. @item symbol The value must be a symbol. It appears in the customization buffer as the name of the symbol. @item function The value must be either a lambda expression or a function name. When it is a function name, you can do completion with @kbd{M-@key{TAB}}. @item variable The value must be a variable name, and you can do completion with @kbd{M-@key{TAB}}. @item face The value must be a symbol which is a face name, and you can do completion with @kbd{M-@key{TAB}}. @item boolean The value is boolean---either @code{nil} or @code{t}. Note that by using @code{choice} and @code{const} together (see the next section), you can specify that the value must be @code{nil} or @code{t}, but also specify the text to describe each value in a way that fits the specific meaning of the alternative. @item coding-system The value must be a coding-system name, and you can do completion with @kbd{M-@key{TAB}}. @item color The value must be a valid color name, and you can do completion with @kbd{M-@key{TAB}}. A sample is provided. @end table @node Composite Types @subsection Composite Types @cindex Composite Types (customization) When none of the simple types is appropriate, you can use composite types, which build new types from other types or from specified data. The specified types or data are called the @dfn{arguments} of the composite type. The composite type normally looks like this: @example (@var{constructor} @var{arguments}@dots{}) @end example @noindent but you can also add keyword-value pairs before the arguments, like this: @example (@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{}) @end example Here is a table of constructors and how to use them to write composite types: @table @code @item (cons @var{car-type} @var{cdr-type}) The value must be a cons cell, its @sc{car} must fit @var{car-type}, and its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string symbol)} is a customization type which matches values such as @code{("foo" . foo)}. In the customization buffer, the @sc{car} and the @sc{cdr} are displayed and edited separately, each according to the type that you specify for it. @item (list @var{element-types}@dots{}) The value must be a list with exactly as many elements as the @var{element-types} given; and each element must fit the corresponding @var{element-type}. For example, @code{(list integer string function)} describes a list of three elements; the first element must be an integer, the second a string, and the third a function. In the customization buffer, each element is displayed and edited separately, according to the type specified for it. @item (group @var{element-types}@dots{}) This works like @code{list} except for the formatting of text in the Custom buffer. @code{list} labels each element value with its tag; @code{group} does not. @item (vector @var{element-types}@dots{}) Like @code{list} except that the value must be a vector instead of a list. The elements work the same as in @code{list}. @item (choice @var{alternative-types}@dots{}) The value must fit at least one of @var{alternative-types}. For example, @code{(choice integer string)} allows either an integer or a string. In the customization buffer, the user selects an alternative using a menu, and can then edit the value in the usual way for that alternative. Normally the strings in this menu are determined automatically from the choices; however, you can specify different strings for the menu by including the @code{:tag} keyword in the alternatives. For example, if an integer stands for a number of spaces, while a string is text to use verbatim, you might write the customization type this way, @example (choice (integer :tag "Number of spaces") (string :tag "Literal text")) @end example @noindent so that the menu offers @samp{Number of spaces} and @samp{Literal text}. In any alternative for which @code{nil} is not a valid value, other than a @code{const}, you should specify a valid default for that alternative using the @code{:value} keyword. @xref{Type Keywords}. If some values are covered by more than one of the alternatives, customize will choose the first alternative that the value fits. This means you should always list the most specific types first, and the most general last. Here's an example of proper usage: @example (choice (const :tag "Off" nil) symbol (sexp :tag "Other")) @end example @noindent This way, the special value @code{nil} is not treated like other symbols, and symbols are not treated like other Lisp expressions. @item (radio @var{element-types}@dots{}) This is similar to @code{choice}, except that the choices are displayed using `radio buttons' rather than a menu. This has the advantage of displaying documentation for the choices when applicable and so is often a good choice for a choice between constant functions (@code{function-item} customization types). @item (const @var{value}) The value must be @var{value}---nothing else is allowed. The main use of @code{const} is inside of @code{choice}. For example, @code{(choice integer (const nil))} allows either an integer or @code{nil}. @code{:tag} is often used with @code{const}, inside of @code{choice}. For example, @example (choice (const :tag "Yes" t) (const :tag "No" nil) (const :tag "Ask" foo)) @end example @noindent describes a variable for which @code{t} means yes, @code{nil} means no, and @code{foo} means ``ask.'' @item (other @var{value}) This alternative can match any Lisp value, but if the user chooses this alternative, that selects the value @var{value}. The main use of @code{other} is as the last element of @code{choice}. For example, @example (choice (const :tag "Yes" t) (const :tag "No" nil) (other :tag "Ask" foo)) @end example @noindent describes a variable for which @code{t} means yes, @code{nil} means no, and anything else means ``ask.'' If the user chooses @samp{Ask} from the menu of alternatives, that specifies the value @code{foo}; but any other value (not @code{t}, @code{nil} or @code{foo}) displays as @samp{Ask}, just like @code{foo}. @item (function-item @var{function}) Like @code{const}, but used for values which are functions. This displays the documentation string as well as the function name. The documentation string is either the one you specify with @code{:doc}, or @var{function}'s own documentation string. @item (variable-item @var{variable}) Like @code{const}, but used for values which are variable names. This displays the documentation string as well as the variable name. The documentation string is either the one you specify with @code{:doc}, or @var{variable}'s own documentation string. @item (set @var{types}@dots{}) The value must be a list, and each element of the list must match one of the @var{types} specified. This appears in the customization buffer as a checklist, so that each of @var{types} may have either one corresponding element or none. It is not possible to specify two different elements that match the same one of @var{types}. For example, @code{(set integer symbol)} allows one integer and/or one symbol in the list; it does not allow multiple integers or multiple symbols. As a result, it is rare to use nonspecific types such as @code{integer} in a @code{set}. Most often, the @var{types} in a @code{set} are @code{const} types, as shown here: @example (set (const :bold) (const :italic)) @end example Sometimes they describe possible elements in an alist: @example (set (cons :tag "Height" (const height) integer) (cons :tag "Width" (const width) integer)) @end example @noindent That lets the user specify a height value optionally and a width value optionally. @item (repeat @var{element-type}) The value must be a list and each element of the list must fit the type @var{element-type}. This appears in the customization buffer as a list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding more elements or removing elements. @item (restricted-sexp :match-alternatives @var{criteria}) This is the most general composite type construct. The value may be any Lisp object that satisfies one of @var{criteria}. @var{criteria} should be a list, and each element should be one of these possibilities: @itemize @bullet @item A predicate---that is, a function of one argument that has no side effects, and returns either @code{nil} or non-@code{nil} according to the argument. Using a predicate in the list says that objects for which the predicate returns non-@code{nil} are acceptable. @item A quoted constant---that is, @code{'@var{object}}. This sort of element in the list says that @var{object} itself is an acceptable value. @end itemize For example, @example (restricted-sexp :match-alternatives (integerp 't 'nil)) @end example @noindent allows integers, @code{t} and @code{nil} as legitimate values. The customization buffer shows all legitimate values using their read syntax, and the user edits them textually. @end table Here is a table of the keywords you can use in keyword-value pairs in a composite type: @table @code @item :tag @var{tag} Use @var{tag} as the name of this alternative, for user communication purposes. This is useful for a type that appears inside of a @code{choice}. @item :match-alternatives @var{criteria} @kindex match-alternatives@r{, customization keyword} Use @var{criteria} to match possible values. This is used only in @code{restricted-sexp}. @item :args @var{argument-list} @kindex args@r{, customization keyword} Use the elements of @var{argument-list} as the arguments of the type construct. For instance, @code{(const :args (foo))} is equivalent to @code{(const foo)}. You rarely need to write @code{:args} explicitly, because normally the arguments are recognized automatically as whatever follows the last keyword-value pair. @end table @node Splicing into Lists @subsection Splicing into Lists The @code{:inline} feature lets you splice a variable number of elements into the middle of a list or vector. You use it in a @code{set}, @code{choice} or @code{repeat} type which appears among the element-types of a @code{list} or @code{vector}. Normally, each of the element-types in a @code{list} or @code{vector} describes one and only one element of the list or vector. Thus, if an element-type is a @code{repeat}, that specifies a list of unspecified length which appears as one element. But when the element-type uses @code{:inline}, the value it matches is merged directly into the containing sequence. For example, if it matches a list with three elements, those become three elements of the overall sequence. This is analogous to using @samp{,@@} in the backquote construct. For example, to specify a list whose first element must be @code{baz} and whose remaining arguments should be zero or more of @code{foo} and @code{bar}, use this customization type: @example (list (const baz) (set :inline t (const foo) (const bar))) @end example @noindent This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)} and @code{(baz foo bar)}. When the element-type is a @code{choice}, you use @code{:inline} not in the @code{choice} itself, but in (some of) the alternatives of the @code{choice}. For example, to match a list which must start with a file name, followed either by the symbol @code{t} or two strings, use this customization type: @example (list file (choice (const t) (list :inline t string string))) @end example @noindent If the user chooses the first alternative in the choice, then the overall list has two elements and the second element is @code{t}. If the user chooses the second alternative, then the overall list has three elements and the second and third must be strings. @node Type Keywords @subsection Type Keywords You can specify keyword-argument pairs in a customization type after the type name symbol. Here are the keywords you can use, and their meanings: @table @code @item :value @var{default} This is used for a type that appears as an alternative inside of @code{choice}; it specifies the default value to use, at first, if and when the user selects this alternative with the menu in the customization buffer. Of course, if the actual value of the option fits this alternative, it will appear showing the actual value, not @var{default}. If @code{nil} is not a valid value for the alternative, then it is essential to specify a valid default with @code{:value}. @item :format @var{format-string} @kindex format@r{, customization keyword} This string will be inserted in the buffer to represent the value corresponding to the type. The following @samp{%} escapes are available for use in @var{format-string}: @table @samp @item %[@var{button}%] Display the text @var{button} marked as a button. The @code{:action} attribute specifies what the button will do if the user invokes it; its value is a function which takes two arguments---the widget which the button appears in, and the event. There is no way to specify two different buttons with different actions. @item %@{@var{sample}%@} Show @var{sample} in a special face specified by @code{:sample-face}. @item %v Substitute the item's value. How the value is represented depends on the kind of item, and (for variables) on the customization type. @item %d Substitute the item's documentation string. @item %h Like @samp{%d}, but if the documentation string is more than one line, add an active field to control whether to show all of it or just the first line. @item %t Substitute the tag here. You specify the tag with the @code{:tag} keyword. @item %% Display a literal @samp{%}. @end table @item :action @var{action} @kindex action@r{, customization keyword} Perform @var{action} if the user clicks on a button. @item :button-face @var{face} @kindex button-face@r{, customization keyword} Use the face @var{face} (a face name or a list of face names) for button text displayed with @samp{%[@dots{}%]}. @item :button-prefix @var{prefix} @itemx :button-suffix @var{suffix} @kindex button-prefix@r{, customization keyword} @kindex button-suffix@r{, customization keyword} These specify the text to display before and after a button. Each can be: @table @asis @item @code{nil} No text is inserted. @item a string The string is inserted literally. @item a symbol The symbol's value is used. @end table @item :tag @var{tag} Use @var{tag} (a string) as the tag for the value (or part of the value) that corresponds to this type. @item :doc @var{doc} @kindex doc@r{, customization keyword} Use @var{doc} as the documentation string for this value (or part of the value) that corresponds to this type. In order for this to work, you must specify a value for @code{:format}, and use @samp{%d} or @samp{%h} in that value. The usual reason to specify a documentation string for a type is to provide more information about the meanings of alternatives inside a @code{:choice} type or the parts of some other composite type. @item :help-echo @var{motion-doc} @kindex help-echo@r{, customization keyword} When you move to this item with @code{widget-forward} or @code{widget-backward}, it will display the string @var{motion-doc} in the echo area. In addition, @var{motion-doc} is used as the mouse @code{help-echo} string and may actually be a function or form evaluated to yield a help string. If it is a function, it is called with one argument, the widget. @item :match @var{function} @kindex match@r{, customization keyword} Specify how to decide whether a value matches the type. The corresponding value, @var{function}, should be a function that accepts two arguments, a widget and a value; it should return non-@code{nil} if the value is acceptable. @item :validate @var{function} Specify a validation function for input. @var{function} takes a widget as an argument, and should return @code{nil} if the widget's current value is valid for the widget. Otherwise, it should return the widget containing the invalid data, and set that widget's @code{:error} property to a string explaining the error. @ignore @item :indent @var{columns} Indent this item by @var{columns} columns. The indentation is used for @samp{%n}, and automatically for group names, for checklists and radio buttons, and for editable lists. It affects the whole of the item except for the first line. @item :offset @var{extra} Indent the subitems of this item @var{extra} columns more than this item itself. By default, subitems are indented the same as their parent. @item :extra-offset @var{n} Add @var{n} extra spaces to this item's indentation, compared to its parent's indentation. @item :notify @var{function} Call @var{function} each time the item or a subitem is changed. The function gets two or three arguments. The first argument is the item itself, the second argument is the item that was changed, and the third argument is the event leading to the change, if any. @item :menu-tag @var{tag-string} Use @var{tag-string} in the menu when the widget is used as an option in a @code{menu-choice} widget. @item :menu-tag-get A function used for finding the tag when the widget is used as an option in a @code{menu-choice} widget. By default, the tag used will be either the @code{:menu-tag} or @code{:tag} property if present, or the @code{princ} representation of the @code{:value} property if not. @item :tab-order Specify the order in which widgets are traversed with @code{widget-forward} or @code{widget-backward}. This is only partially implemented. @enumerate a @item Widgets with tabbing order @code{-1} are ignored. @item (Unimplemented) When on a widget with tabbing order @var{n}, go to the next widget in the buffer with tabbing order @var{n+1} or @code{nil}, whichever comes first. @item When on a widget with no tabbing order specified, go to the next widget in the buffer with a positive tabbing order, or @code{nil} @end enumerate @item :parent The parent of a nested widget (e.g., a @code{menu-choice} item or an element of a @code{editable-list} widget). @item :sibling-args This keyword is only used for members of a @code{radio-button-choice} or @code{checklist}. The value should be a list of extra keyword arguments, which will be used when creating the @code{radio-button} or @code{checkbox} associated with this item. @end ignore @end table @node Defining New Types @subsection Defining New Types In the previous sections we have described how to construct elaborate type specifications for @code{defcustom}. In some cases you may want to give such a type specification a name. The obvious case is when you are using the same type for many user options: rather than repeat the specification for each option, you can give the type specification a name, and use that name each @code{defcustom}. The other case is when a user option's value is a recursive data structure. To make it possible for a datatype to refer to itself, it needs to have a name. Since custom types are implemented as widgets, the way to define a new customize type is to define a new widget. We are not going to describe the widget interface here in details, see @ref{Top, , Introduction, widget, The Emacs Widget Library}, for that. Instead we are going to demonstrate the minimal functionality needed for defining new customize types by a simple example. @example (define-widget 'binary-tree-of-string 'lazy "A binary tree made of cons-cells and strings." :offset 4 :tag "Node" :type '(choice (string :tag "Leaf" :value "") (cons :tag "Interior" :value ("" . "") binary-tree-of-string binary-tree-of-string))) (defcustom foo-bar "" "Sample variable holding a binary tree of strings." :type 'binary-tree-of-string) @end example The function to define a new widget is called @code{define-widget}. The first argument is the symbol we want to make a new widget type. The second argument is a symbol representing an existing widget, the new widget is going to be defined in terms of difference from the existing widget. For the purpose of defining new customization types, the @code{lazy} widget is perfect, because it accepts a @code{:type} keyword argument with the same syntax as the keyword argument to @code{defcustom} with the same name. The third argument is a documentation string for the new widget. You will be able to see that string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string @key{RET}} command. After these mandatory arguments follow the keyword arguments. The most important is @code{:type}, which describes the data type we want to match with this widget. Here a @code{binary-tree-of-string} is described as being either a string, or a cons-cell whose car and cdr are themselves both @code{binary-tree-of-string}. Note the reference to the widget type we are currently in the process of defining. The @code{:tag} attribute is a string to name the widget in the user interface, and the @code{:offset} argument is there to ensure that child nodes are indented four spaces relative to the parent node, making the tree structure apparent in the customization buffer. The @code{defcustom} shows how the new widget can be used as an ordinary customization type. The reason for the name @code{lazy} is that the other composite widgets convert their inferior widgets to internal form when the widget is instantiated in a buffer. This conversion is recursive, so the inferior widgets will convert @emph{their} inferior widgets. If the data structure is itself recursive, this conversion is an infinite recursion. The @code{lazy} widget prevents the recursion: it convert its @code{:type} argument only when needed. @ignore arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2 @end ignore