Now on revision 107780. ------------------------------------------------------------ revno: 107780 committer: Chong Yidong branch nick: trunk timestamp: Fri 2012-04-06 14:39:35 +0800 message: * doc/lispref/minibuf.texi (Programmed Completion): Document metadata method. (Completion Variables): Document completion-category-overrides. diff: === modified file 'doc/lispref/ChangeLog' --- doc/lispref/ChangeLog 2012-04-05 14:47:41 +0000 +++ doc/lispref/ChangeLog 2012-04-06 06:39:35 +0000 @@ -1,9 +1,12 @@ +2012-04-06 Chong Yidong + + * minibuf.texi (Programmed Completion): Document metadata method. + (Completion Variables): Document completion-category-overrides. + 2012-04-05 Chong Yidong * anti.texi (Antinews): Rewrite for Emacs 23. - * minibuf.texi (Programmed Completion): Document metadata method. - 2012-04-04 Chong Yidong * minibuf.texi (Programmed Completion): Remove obsolete variable === modified file 'doc/lispref/minibuf.texi' --- doc/lispref/minibuf.texi 2012-04-04 10:32:35 +0000 +++ doc/lispref/minibuf.texi 2012-04-06 06:39:35 +0000 @@ -1575,12 +1575,10 @@ @cindex completion styles @defopt completion-styles -The value of this variable is a list of completion styles to use for -performing completion. A @dfn{completion style} is a set of rules for -generating completions. - -Each style listed in this variable must be one of those defined in -@code{completion-styles-alist}. +The value of this variable is a list of completion style (symbols) to +use for performing completion. A @dfn{completion style} is a set of +rules for generating completions. Each symbol in occurring this list +must have a corresponding entry in @code{completion-styles-alist}. @end defopt @defvar completion-styles-alist @@ -1588,15 +1586,16 @@ element in the list has the form @example -(@var{name} @var{try-completion} @var{all-completions} @var{doc}) +(@var{style} @var{try-completion} @var{all-completions} @var{doc}) @end example @noindent -Here, @var{name} is the name of the completion style (a symbol), which -may be used in @code{completion-styles-alist} to refer to this style; -@var{try-completion} is the function that does the completion; -@var{all-completions} is the function that lists the completions; and -@var{doc} is a string describing the completion style. +Here, @var{style} is the name of the completion style (a symbol), +which may be used in the @code{completion-styles} variable to refer to +this style; @var{try-completion} is the function that does the +completion; @var{all-completions} is the function that lists the +completions; and @var{doc} is a string describing the completion +style. The @var{try-completion} and @var{all-completions} functions should each accept four arguments: @var{string}, @var{collection}, @@ -1622,6 +1621,31 @@ description of the available completion styles. @end defvar +@defopt completion-category-overrides +This variable specifies special completion styles and other completion +behaviors to use when completing certain types of text. Its value +should be a list of the form @code{(@var{category} . @var{alist})}. +@var{category} is a symbol describing what is being completed; +currently, the @code{buffer} and @code{file} categories are defined, +but others can be defined via specialized completion functions +(@pxref{Programmed Completion}). @var{alist} is an association list +describing how completion should behave for the corresponding +category. The following alist keys are supported: + +@table @code +@item styles +The value should be a list of completion styles (symbols). + +@item cycle +The value should be a value for @code{completion-cycle-threshold} +(@pxref{Completion Options,,, emacs, The GNU Emacs Manual}) for this +category. +@end table + +@noindent +Additional alist entries may be defined in the future. +@end defopt + @defvar completion-extra-properties This variable is used to specify extra properties of the current completion command. It is intended to be let-bound by specialized @@ -1706,9 +1730,48 @@ should return @code{(boundaries START . END)}, where START is the position of the beginning boundary in the specified string, and END is the position of the end boundary in SUFFIX. + +@item metadata +This specifies a request for information about the state of the +current completion. The function should return an alist, as described +below. The alist may contain any number of elements. @end table + +@noindent +If the flag has any other value, the completion function should return +@code{nil}. @end itemize +The following is a list of metadata entries that a completion function +may return in response to a @code{metadata} flag argument: + +@table @code +@item category +The value should be a symbol describing what kind of text the +completion function is trying to complete. If the symbol matches one +of the keys in @code{completion-category-overrides}, the usual +completion behavior is overridden. @xref{Completion Variables}. + +@item annotation-function +The value should be a function for @dfn{annotating} completions. The +function should take one argument, @var{string}, which is a possible +completion. It should return a string, which is displayed after the +completion @var{string} in the @samp{*Completions*} buffer. + +@item display-sort-function +The value should be a function for sorting completions. The function +should take one argument, a list of completion strings, and return a +sorted list of completion strings. It is allowed to alter the input +list destructively. + +@item cycle-sort-function +The value should be a function for sorting completions, when +@code{completion-cycle-threshold} is non-@code{nil} and the user is +cycling through completion alternatives. @xref{Completion Options,,, +emacs, The GNU Emacs Manual}. Its argument list and return value are +the same as for @code{display-sort-function}. +@end table + @defun completion-table-dynamic function This function is a convenient way to write a function that can act as programmed completion function. The argument @var{function} should be ------------------------------------------------------------ revno: 107779 author: Teodor Zlatanov committer: Katsumi Yamaoka branch nick: trunk timestamp: Fri 2012-04-06 01:56:38 +0000 message: auth.texi (Secret Service API): Adjust @samp to @code for collection names diff: === modified file 'doc/misc/ChangeLog' --- doc/misc/ChangeLog 2012-04-05 13:55:55 +0000 +++ doc/misc/ChangeLog 2012-04-06 01:56:38 +0000 @@ -1,6 +1,7 @@ 2012-04-05 Teodor Zlatanov * auth.texi (Secret Service API): Edit further and give examples. + (Secret Service API): Adjust @samp to @code for collection names. 2012-04-04 Glenn Morris === modified file 'doc/misc/auth.texi' --- doc/misc/auth.texi 2012-04-05 13:55:55 +0000 +++ doc/misc/auth.texi 2012-04-06 01:56:38 +0000 @@ -260,12 +260,12 @@ and KDE Wallet but it's the same thing, a group of secrets. Collections are personal and protected so only the owner can open them. -The most common collection is called @samp{login}. +The most common collection is called @code{"login"}. -A collection can have an alias. The alias @samp{default} is +A collection can have an alias. The alias @code{"default"} is commonly used so the clients don't have to know the specific name of the collection they open. Other aliases are not supported yet. -Since aliases are globally accessible, set the @samp{default} alias +Since aliases are globally accessible, set the @code{"default"} alias only when you're sure it's appropriate. @defun secrets-list-collections @@ -274,27 +274,27 @@ @defun secrets-set-alias collection alias Set @var{alias} as alias of collection labeled @var{collection}. -Currently only the alias @samp{default} is supported. +Currently only the alias @code{"default"} is supported. @end defun @defun secrets-get-alias alias Return the collection name @var{alias} is referencing to. -Currently only the alias @samp{default} is supported. +Currently only the alias @code{"default"} is supported. @end defun Collections can be created and deleted by the functions @code{secrets-create-collection} and @code{secrets-delete-collection}. Usually, this is not done from within Emacs. Do not delete standard -collections such as @samp{login}. +collections such as @code{"login"}. -The special collection @samp{session} exists for the lifetime of the +The special collection @code{"session"} exists for the lifetime of the corresponding client session (in our case, Emacs's lifetime). It is created automatically when Emacs uses the Secret Service interface and it is deleted when Emacs is killed. Therefore, it can be used to -store and retrieve secret items temporarily. The @samp{session} +store and retrieve secret items temporarily. The @code{"session"} collection is better than a persistent collection when the secret items should not live longer than Emacs. The session collection can -be specified either by the string @samp{session}, or by @code{nil}, +be specified either by the string @code{"session"}, or by @code{nil}, whenever a collection parameter is needed in the following functions. @defun secrets-list-items collection @@ -359,12 +359,12 @@ The auth-source library uses the @file{secrets.el} library and thus the Secret Service API when you specify a source matching -@samp{secrets:COLLECTION}. For instance, you could use -@samp{secrets:session} to use the @samp{session} collection, open only -for the lifetime of Emacs. Or you could use @samp{secrets:Login} to -open the @samp{Login} collection. As a special case, you can use the +@code{"secrets:COLLECTION"}. For instance, you could use +@code{"secrets:session"} to use the @code{"session"} collection, open only +for the lifetime of Emacs. Or you could use @code{"secrets:Login"} to +open the @code{"Login"} collection. As a special case, you can use the symbol @code{default} in @code{auth-sources} (not a string, but a -symbol) to specify the @samp{default} alias. Here is a contrived +symbol) to specify the @code{"default"} alias. Here is a contrived example that sets @code{auth-sources} to search three collections and then fall back to @file{~/.authinfo.gpg}. ------------------------------------------------------------ revno: 107778 committer: Lars Magne Ingebrigtsen branch nick: trunk timestamp: Fri 2012-04-06 00:26:20 +0200 message: `shrink-window' doc fix * window.el (shrink-window): Mention the `window-min-height' variable in the doc string. diff: === modified file 'lisp/ChangeLog' --- lisp/ChangeLog 2012-04-05 07:29:19 +0000 +++ lisp/ChangeLog 2012-04-05 22:26:20 +0000 @@ -1,3 +1,8 @@ +2012-04-05 Lars Magne Ingebrigtsen + + * window.el (shrink-window): Mention the `window-min-height' + variable in the doc string. + 2012-04-05 Bastien Guerry * color.el (color-lighten-name): Fix typo. === modified file 'lisp/window.el' --- lisp/window.el 2012-03-27 09:22:01 +0000 +++ lisp/window.el 2012-04-05 22:26:20 +0000 @@ -2117,6 +2117,7 @@ one line smaller. If optional argument HORIZONTAL is non-nil, make selected window narrower by DELTA columns. If DELTA is negative, enlarge selected window by -DELTA lines or columns. +Also see the `window-min-height' variable. Return nil." (interactive "p") (cond ------------------------------------------------------------ revno: 107777 committer: Glenn Morris branch nick: trunk timestamp: Thu 2012-04-05 14:32:38 -0400 message: Update lispref antinews menu descriptions per comment in anti.texi diff: === modified file 'doc/lispref/elisp.texi' --- doc/lispref/elisp.texi 2012-04-04 09:19:32 +0000 +++ doc/lispref/elisp.texi 2012-04-05 18:32:38 +0000 @@ -163,7 +163,7 @@ Appendices -* Antinews:: Info for users downgrading to Emacs 22. +* Antinews:: Info for users downgrading to Emacs 23. * GNU Free Documentation License:: The license for this documentation. * GPL:: Conditions for copying and changing GNU Emacs. * Tips:: Advice and coding conventions for Emacs Lisp. === modified file 'doc/lispref/vol1.texi' --- doc/lispref/vol1.texi 2012-04-04 09:19:32 +0000 +++ doc/lispref/vol1.texi 2012-04-05 18:32:38 +0000 @@ -181,7 +181,7 @@ Appendices -* Antinews:: Info for users downgrading to Emacs 22. +* Antinews:: Info for users downgrading to Emacs 23. * GNU Free Documentation License:: The license for this documentation. * GPL:: Conditions for copying and changing GNU Emacs. * Tips:: Advice and coding conventions for Emacs Lisp. === modified file 'doc/lispref/vol2.texi' --- doc/lispref/vol2.texi 2012-04-04 09:19:32 +0000 +++ doc/lispref/vol2.texi 2012-04-05 18:32:38 +0000 @@ -180,7 +180,7 @@ Appendices -* Antinews:: Info for users downgrading to Emacs 22. +* Antinews:: Info for users downgrading to Emacs 23. * GNU Free Documentation License:: The license for this documentation. * GPL:: Conditions for copying and changing GNU Emacs. * Tips:: Advice and coding conventions for Emacs Lisp. ------------------------------------------------------------ revno: 107776 committer: Eli Zaretskii branch nick: trunk timestamp: Thu 2012-04-05 19:52:56 +0300 message: Fix a typo in doc/lispref/anti.texi. diff: === modified file 'doc/lispref/anti.texi' --- doc/lispref/anti.texi 2012-04-05 14:47:41 +0000 +++ doc/lispref/anti.texi 2012-04-05 16:52:56 +0000 @@ -6,7 +6,7 @@ @c This node must have no pointers. @node Antinews, GNU Free Documentation License, Packaging, Top -@appendix Emacs 22 Antinews +@appendix Emacs 23 Antinews @c Update the elisp.texi, vol1.texi, vol2.texi Antinews menu entries @c with the above version number. ------------------------------------------------------------ revno: 107775 committer: Chong Yidong branch nick: trunk timestamp: Thu 2012-04-05 22:47:41 +0800 message: * doc/lispref/anti.texi (Antinews): Rewrite for Emacs 23. * etc/NEWS: Some minor rearrangement. diff: === modified file 'doc/lispref/ChangeLog' --- doc/lispref/ChangeLog 2012-04-04 10:32:35 +0000 +++ doc/lispref/ChangeLog 2012-04-05 14:47:41 +0000 @@ -1,3 +1,9 @@ +2012-04-05 Chong Yidong + + * anti.texi (Antinews): Rewrite for Emacs 23. + + * minibuf.texi (Programmed Completion): Document metadata method. + 2012-04-04 Chong Yidong * minibuf.texi (Programmed Completion): Remove obsolete variable === modified file 'doc/lispref/anti.texi' --- doc/lispref/anti.texi 2012-03-04 06:50:18 +0000 +++ doc/lispref/anti.texi 2012-04-05 14:47:41 +0000 @@ -11,145 +11,129 @@ @c with the above version number. For those users who live backwards in time, here is information about -downgrading to Emacs version 22.3. We hope you will enjoy the greater +downgrading to Emacs version 23.4. We hope you will enjoy the greater simplicity that results from the absence of many Emacs @value{EMACSVER} features. -@section Old Lisp Features in Emacs 22 +@section Old Lisp Features in Emacs 23 @itemize @bullet @item -The internal character representation used by Emacs is not longer -based on Unicode. In this representation, called @code{emacs-mule}, -each character belongs to one and only one script. Emacs makes no -attempt to distinguish between ``similar'' characters occurring in -different scripts. - -@item -The @code{^} interactive spec code, the function -@code{handle-shift-selection}, and the variable -@code{this-command-keys-shift-translated} have all been removed. -Shift-translated keys are no longer treated specially, making Emacs's -handling of keybindings much more consistent. - -@item -Temporarily-active regions are not created by giving the variable -@code{transient-mark-mode} values of the form @code{(only -. @var{oldvar})}. We instead use a more complicated scheme: -setting @code{transient-mark-mode} to @code{only} enables Transient -Mark mode for the following command only, during which the value of -@code{transient-mark-mode} is set to @code{identity}; if it is still -@code{identity} at the end of the command, Transient Mark mode is -disabled. - -@item -Many minibuffer functions, such as @code{read-file-name} and -@code{minibuffer-complete}, have been rewritten in C for greater -speed. The completion code has been considerably simplified; the -completion style can no longer be changed via -@code{completion-styles-alist}, and @code{completing-read} no longer -recognizes the special values @code{confirm-only} and -@code{confirm-after-completion} for its @var{require-match} argument. - -@item -Emacs no longer supports explicitly-numbered groups in regular -expressions. - -@item -The @code{permanent-local-hook} function property has no special -meaning. - -@item -The @code{functionp} function now returns @code{t} for special forms. - -@item -The @code{interactive-form} symbol property has no special meaning. -Once you supply a function with an interactive form, the only way to -change it is to redefine the function. - -@item -The @code{ignore-errors} macro has been moved into the @code{cl} -package. - -@item -Variables can now be both buffer-local and frame-local; buffer-local -bindings take precedence over frame-local bindings. - -@item -Faces can no longer be remapped. - -@item -Lisp programs now specify fonts by their names, which are strings -following the XLFD (X logical font descriptor) format. Fonts are no -longer represented using a special set of ``font'' data types. The -various functions that act on these data types, such as @code{fontp}, -@code{font-spec}, and @code{list-fonts}, have all been deleted. - -@item -Emacs does not recognize the @code{FontBackend} X resource and the -@code{font-backend} frame parameter. On the X Window System, fonts -are always drawn using the X core font driver. - -@item -Display terminals are no longer represented using a ``terminal'' data -type; this is not necessary, because we have removed the ability to -display on graphical and text terminals simultaneously. For the same -reason, the @code{window-system} variable is no longer frame-local, -and the @code{window-system} function has been removed. - -@item -The functions @code{list-system-processes} and -@code{process-attributes} have been removed. To get information about -system processes, call an external program, such as @command{ps}. - -@item -The function @code{locate-user-emacs-file} and the variable -@code{user-emacs-directory} have been removed. Instead, use -hard-coded values pointing to @file{~/.emacs.d}. - -@item -@code{vertical-motion} can no longer be told to move to a specific -column; it always puts point on the first column of a line. - -@item -Windows no longer have parameters. - -@item -The @code{display-buffer} function has been rewritten in C. Its -window-splitting heuristics are a little less sophisticated, and a -little less documented. Window-splitting is handled internally, -instead of using @code{split-window-preferred-function} (which has -been removed). Windows are never split horizontally; the variable -@code{split-width-threshold} has been removed. - -@item -The @code{mode-name} variable now accepts only string values, and -cannot take the form of a mode-line construct. - -@item -The behavior of @code{map-char-table} has changed. It calls the -mapping function for every single character in the table, instead of -using cons cells to represent contiguous character code ranges. - -@item -Several keymaps have been eliminated: @code{input-decode-map}, -@code{local-function-key-map}, @code{search-map}, -@code{multi-query-replace-map}, and -@code{minibuffer-local-shell-command-map}. - -@item -Many functions have been removed, including: @code{buffer-swap-text}, -@code{emacs-init-time}, @code{emacs-uptime}, @code{use-region-p}, -@code{region-active-p}, @code{start-file-process}, -@code{process-lines}, @code{image-refresh}, -@code{match-substitute-replacement}, @code{word-search-forward-lax}, -and @code{word-search-backward-lax}. - -@item -Many variables have been removed, including @code{read-circle}, -@code{after-init-time} and @code{before-init-time}, -@code{generate-autoload-cookie}, @code{file-local-variables-alist}, -@code{replace-search-function} and @code{replace-re-search-function}, -@code{inhibit-changing-match-data}, @code{wrap-prefix}, and -@code{line-prefix}, +Support for lexical scoping has been removed; all variables are +dynamically scoped. The @code{lexical-binding} variable has been +removed, and so has the @var{lexical} argument to @code{eval}. The +@code{defvar} and @code{defconst} forms no longer mark variables as +dynamic, since all variables are dynamic. + +Having only dynamic binding follows the spirit of Emacs extensibility, +for it allows any Emacs code to access any defined variable with a +minimum of fuss. But @xref{Dynamic Binding Tips}, for tips to avoid +making your programs hard to understand. + +@item +Calling a minor mode function from Lisp with a nil or omitted argument +does not enable the minor mode unconditionally; instead, it toggles +the minor mode---which is the straightforward thing to do, since that +is the behavior when invoked interactively. One downside is that it +is more troublesome to enable minor modes from hooks; you have to do +something like + +@example +(add-hook 'foo-hook (lambda () (bar-mode 1))) +@end example + +@noindent +or define @code{turn-on-bar-mode} and call that from the hook. + +@item +The @code{prog-mode} dummy major mode has been removed. Instead of +using it as a crutch to meet programming mode conventions, you should +explicitly ensure that your mode follows those conventions. +@xref{Major Mode Conventions}. + +@item +Emacs no longer supports bidirectional display and editing. Since +there is no need to worry about the insertion of right-to-left text +messing up how lines and paragraphs are displayed, the function +@code{bidi-string-mark-left-to-right} has been removed; so have many +other functions and variables related to bidirectional display. +Unicode directionality characters like @code{U+200E} ("left-to-right +mark") have no special effect on display. + +@item +Emacs windows now have most of their internal state hidden from Lisp. +Internal windows are no longer visible to Lisp; functions such as +@code{window-parent}, window parameters related to window arrangement, +and window-local buffer lists have all been removed. Functions for +resizing windows can delete windows if when they become too small. + +The @dfn{action function} feature for controlling buffer display has +been removed, including @code{display-buffer-overriding-action} and +related variables, as well as the @var{action} argument to +@code{display-buffer} and other functions. The way to +programmatically control how Emacs chooses a window to display a +buffer is to bind the right combination of +@code{special-display-regexps}, @code{pop-up-frames}, and other +variables. + +@item +The standard completion interface has been simplified, eliminating the +@code{completion-extra-properties} variable, the @code{metadata} +action flag for completion functions, and the concept of +@dfn{completion categories}. Lisp programmers may now find the choice +of methods for tuning completion less bewildering, but if a package +finds the streamlined interface insufficient for its needs, it must +implement its own specialized completion feature. + +@item +@code{copy-directory} now behaves the same whether or not the +destination is an existing directory: if the destination exists, the +@emph{contents} of the first directory are copied into it (with +subdirectories handled recursively), rather than copying the first +directory into a subdirectory. + +@item +The @var{trash} arguments for @code{delete-file} and +@code{delete-directory} have been removed. The variable +@code{delete-by-moving-to-trash} must now be used with care; whenever +it is non-@code{nil}, all calls to @code{delete-file} or +@code{delete-directory} use the trash. + +@item +Because Emacs no longer supports SELinux file contexts, the +@var{preserve-selinux-context} argument to @code{copy-file} has been +removed. The return value of @code{backup-buffer} no longer has an +entry for the SELinux file context. + +@item +For mouse click input events in the text area, the Y pixel coordinate +in the @var{position} list (@pxref{Click Events}) now counts from the +top of the header line, if there is one, rather than the top of the +text area. + +@item +Bindings in menu keymaps (@pxref{Format of Keymaps}) now sometimes get +an additional @var{cache} entry in their definitions, like this: + +@example +(@var{type} @var{item-name} @var{cache} . @var{binding}) +@end example + +@noindent +The @var{cache} entry is used internally by Emacs to record equivalent +keyboard key sequences for invoking the same command; Lisp programs +should never use it. + +@item +The @code{open-network-stream} function has been removed, and so has +the @code{gnutls} library. Lisp programs that want an encrypted +network connection must now call external utilities such as +@command{starttls} or @command{gnutls-cli}. + +@item +Tool bars can no longer display separators, which frees up several +pixels of space on each graphical frame. + +@item +Many other functions and variables have been eliminated. @end itemize === modified file 'etc/NEWS' --- etc/NEWS 2012-04-05 06:54:40 +0000 +++ etc/NEWS 2012-04-05 14:47:41 +0000 @@ -82,8 +82,6 @@ ** Completion -*** Shell mode uses pcomplete rules, with the standard completion UI. - *** Many packages now use the `completion-at-point' command, rather than implementing separate completion commands. @@ -313,6 +311,9 @@ ** Window changes +*** The `quit-window' command now restores the last buffer displayed +in the quitted window. + *** Resizing an Emacs frame now preserves proportional window sizes, modulo restrictions like window minimum sizes and fixed-size windows. @@ -339,6 +340,10 @@ other windows in the same combination. Subsequent resizing or deletion of the window will resize all windows in the same combination as well. +*** New option `frame-auto-hide-function' lets you choose between +iconifying or deleting a frame when burying a buffer in a dedicated +frame, or quitting a window showing a buffer in a frame of its own. + *** New commands `maximize-window' and `minimize-window'. These maximize and minimize the size of a window within its frame. @@ -1149,14 +1154,6 @@ See the docstring of `display-buffer' for details. -*** New behavior of `quit-window'. -The behavior of `quit-window' has been changed in order to restore the -state before the last buffer display operation in that window. - -*** The new option `frame-auto-hide-function' lets you choose between -iconifying or deleting a frame when burying a buffer shown in a dedicated -frame or quitting a window showing a buffer in a frame of its own. - *** New functions `window-state-get' and `window-state-put'. These functions allow to save and restore the state of an arbitrary frame or window as an Elisp object. ------------------------------------------------------------ revno: 107774 author: Teodor Zlatanov committer: Katsumi Yamaoka branch nick: trunk timestamp: Thu 2012-04-05 13:55:55 +0000 message: auth.texi (Secret Service API): Edit further and give examples. diff: === modified file 'doc/misc/ChangeLog' --- doc/misc/ChangeLog 2012-04-04 20:44:56 +0000 +++ doc/misc/ChangeLog 2012-04-05 13:55:55 +0000 @@ -1,3 +1,7 @@ +2012-04-05 Teodor Zlatanov + + * auth.texi (Secret Service API): Edit further and give examples. + 2012-04-04 Glenn Morris * auth.texi (Secret Service API): Copyedits. === modified file 'doc/misc/auth.texi' --- doc/misc/auth.texi 2012-04-04 20:44:56 +0000 +++ doc/misc/auth.texi 2012-04-05 13:55:55 +0000 @@ -229,13 +229,14 @@ The @dfn{Secret Service API} is a standard from @uref{http://www.freedesktop.org/wiki/Specifications/secret-storage-spec,,freedesktop.org} -to securely store passwords and other confidential information. -Implementations of compliant daemons are the GNOME Keyring and the KDE -Wallet. +to securely store passwords and other confidential information. This +API is implemented by system daemons such as the GNOME Keyring and the +KDE Wallet (these are GNOME and KDE packages respectively and should +be available on most modern GNU/Linux systems). -The auth-source library uses the @file{secrets.el} library as an -interface to this feature. You can also use that library in other -packages. +The auth-source library uses the @file{secrets.el} library to connect +through the Secret Service API. You can also use that library in +other packages, it's not exclusive to auth-source. @defvar secrets-enabled After loading @file{secrets.el}, a non-@code{nil} value of this @@ -244,63 +245,60 @@ @end defvar @deffn Command secrets-show-secrets -This command inspects all collections, items, and their attributes. +This command shows all collections, items, and their attributes. @end deffn -The atomic objects to be managed by the Secret Service API are -@dfn{secret items}, which are something an application wishes to store -securely. A good example is a password that an application needs to -save and use at a later date. +The atomic objects managed by the Secret Service API are @dfn{secret +items}, which contain things an application wishes to store securely, +like a password. Secret items have a label (a name), the @dfn{secret} +(which is the string we want, like a password), and a set of lookup +attributes. The attributes can be used to search and retrieve a +secret item at a later date. Secret items are grouped in @dfn{collections}. A collection is -similar in concept to the terms @samp{keyring} or @samp{wallet}. A -common collection is called @samp{"login"}. A collection is stored -permanently under the user's permissions, and can be accessed in a -user session context. - -A collection can have an alias name. The use case for this is to -set the alias @samp{"default"} for a given collection, making it -transparent to clients as to which collection is used. Other aliases -are not supported (yet). Since an alias is visible to all -applications, this setting should be performed with care. +sometimes called a @samp{keyring} or @samp{wallet} in GNOME Keyring +and KDE Wallet but it's the same thing, a group of secrets. +Collections are personal and protected so only the owner can open them. + +The most common collection is called @samp{login}. + +A collection can have an alias. The alias @samp{default} is +commonly used so the clients don't have to know the specific name of +the collection they open. Other aliases are not supported yet. +Since aliases are globally accessible, set the @samp{default} alias +only when you're sure it's appropriate. @defun secrets-list-collections -This function returns a list of collection names. +This function returns all the collection names as a list. @end defun @defun secrets-set-alias collection alias Set @var{alias} as alias of collection labeled @var{collection}. -For the time being, only the alias @samp{"default"} is supported. +Currently only the alias @samp{default} is supported. @end defun @defun secrets-get-alias alias Return the collection name @var{alias} is referencing to. -For the time being, only the alias @samp{"default"} is supported. +Currently only the alias @samp{default} is supported. @end defun Collections can be created and deleted by the functions @code{secrets-create-collection} and @code{secrets-delete-collection}. -Usually, this is not applied from within Emacs. Common collections, -like @samp{"login"}, should never be deleted. - -There exists a special collection called @samp{"session"}, which has -the lifetime of the corresponding client session (aka Emacs's -lifetime). It is created automatically when Emacs uses the Secret -Service interface, and it is deleted when Emacs is killed. Therefore, -it can be used to store and retrieve secret items temporarily. This -should be preferred over creation of a persistent collection, when the -information should not live longer than Emacs. The session collection -can be addressed either by the string @samp{"session"}, or by -@code{nil}, whenever a collection parameter is needed in the following -functions. - -As already said, a collection is a group of secret items. A secret -item has a label, the @dfn{secret} (which is a string), and a set of -lookup attributes. The attributes can be used to search and retrieve -a secret item at a later date. +Usually, this is not done from within Emacs. Do not delete standard +collections such as @samp{login}. + +The special collection @samp{session} exists for the lifetime of the +corresponding client session (in our case, Emacs's lifetime). It is +created automatically when Emacs uses the Secret Service interface and +it is deleted when Emacs is killed. Therefore, it can be used to +store and retrieve secret items temporarily. The @samp{session} +collection is better than a persistent collection when the secret +items should not live longer than Emacs. The session collection can +be specified either by the string @samp{session}, or by @code{nil}, +whenever a collection parameter is needed in the following functions. @defun secrets-list-items collection -Returns a list of all item labels of @var{collection}. +Returns all the item labels of @var{collection} as a list. @end defun @defun secrets-create-item collection item password &rest attributes @@ -310,6 +308,8 @@ symbols, starting with a colon. Example: @example +;;; The session "session", the label is "my item" +;;; and the secret (password) is "geheim" (secrets-create-item "session" "my item" "geheim" :method "sudo" :user "joe" :host "remote-host") @end example @@ -327,7 +327,7 @@ The lookup attributes, which are specified during creation of a secret item, must be a key-value pair. Keys are keyword symbols, starting with a colon; values are strings. They can be retrieved -from a given secret item, and they can be used for searching of items. +from a given secret item and they can be used for searching of items. @defun secrets-get-attribute collection item attribute Returns the value of key @var{attribute} of item labeled @var{item} in @@ -347,9 +347,9 @@ @end defun @defun secrets-search-items collection &rest attributes -Search items in @var{collection} with @var{attributes}. -@var{attributes} are key-value pairs, as used in -@code{secrets-create-item}. Example: +Search for the items in @var{collection} with matching +@var{attributes}. The @var{attributes} are key-value pairs, as used +in @code{secrets-create-item}. Example: @example (secrets-search-items "session" :user "joe") @@ -357,6 +357,24 @@ @end example @end defun +The auth-source library uses the @file{secrets.el} library and thus +the Secret Service API when you specify a source matching +@samp{secrets:COLLECTION}. For instance, you could use +@samp{secrets:session} to use the @samp{session} collection, open only +for the lifetime of Emacs. Or you could use @samp{secrets:Login} to +open the @samp{Login} collection. As a special case, you can use the +symbol @code{default} in @code{auth-sources} (not a string, but a +symbol) to specify the @samp{default} alias. Here is a contrived +example that sets @code{auth-sources} to search three collections and +then fall back to @file{~/.authinfo.gpg}. + +@example +(setq auth-sources '(default + "secrets:session" + "secrets:Login" + "~/.authinfo.gpg")) +@end example + @node Help for developers @chapter Help for developers ------------------------------------------------------------ revno: 107773 committer: Bastien Guerry branch nick: trunk timestamp: Thu 2012-04-05 09:29:19 +0200 message: Fix typo in color.el. Thanks to Brad Town for spotting this. diff: === modified file 'lisp/ChangeLog' --- lisp/ChangeLog 2012-04-04 17:13:00 +0000 +++ lisp/ChangeLog 2012-04-05 07:29:19 +0000 @@ -1,3 +1,7 @@ +2012-04-05 Bastien Guerry + + * color.el (color-lighten-name): Fix typo. + 2012-04-04 Stefan Monnier * server.el (server--on-display-p): New function. === modified file 'lisp/color.el' --- lisp/color.el 2012-01-24 12:06:51 +0000 +++ lisp/color.el 2012-04-05 07:29:19 +0000 @@ -394,7 +394,7 @@ See `color-lighten-hsl'." (apply 'color-rgb-to-hex (apply 'color-hsl-to-rgb - (apply 'color-lighten--hsl + (apply 'color-lighten-hsl (append (apply 'color-rgb-to-hsl (color-name-to-rgb name)) ------------------------------------------------------------ revno: 107772 committer: Glenn Morris branch nick: trunk timestamp: Wed 2012-04-04 23:54:40 -0700 message: NEWS typo fix and punctuation tweaks diff: === modified file 'etc/NEWS' --- etc/NEWS 2012-04-05 04:29:22 +0000 +++ etc/NEWS 2012-04-05 06:54:40 +0000 @@ -95,7 +95,7 @@ *** New option `completion-cycle-threshold' allows completion cycling. *** New option `completion-category-overrides' for overriding the -default completion style in certain cirucmstances. +default completion style in certain circumstances. *** New completion style `substring'. @@ -829,14 +829,14 @@ *** pc-mode.el is obsolete (CUA mode is much more comprehensive). -*** pgg is obsolete (use EasyPG instead) +*** pgg is obsolete (use EasyPG instead). *** sregex.el is obsolete, since rx.el is a strict superset. *** s-region.el and pc-select.el are obsolete. They are superseded by shift-select-mode, enabled by default since 23.1. -*** vc-mcvs.el is obsolete (for lack of a maintainer) +*** vc-mcvs.el is obsolete (for lack of a maintainer). ** Miscellaneous @@ -989,7 +989,7 @@ *** `frame-update-faces' (not needed) *** `frame-update-face-colors' (`frame-set-background-mode') *** `x-frob-font-weight' and `x-frob-font-slant' (`make-face-*' functions) -*** `x-make-font-bold and x-make-font-demibold (make-face-bold) +*** `x-make-font-bold and x-make-font-demibold (`make-face-bold') *** `x-make-font-italic' and `x-make-font-oblique' (`make-face-italic') *** `x-make-font-bold-italic' (`make-face-bold-italic') *** `x-make-font-unbold' (`make-face-unbold')