annotate doc/misc/auth.texi @ 110523:a5ad4f188e19

Synch Semantic to CEDET 1.0. Move CEDET ChangeLog entries to new file lisp/cedet/ChangeLog. * semantic.el (semantic-version): Update to 2.0. (semantic-mode-map): Add "," and "m" bindings. (navigate-menu): Update. * semantic/symref.el (semantic-symref-calculate-rootdir): New function. (semantic-symref-detect-symref-tool): Use it. * semantic/symref/grep.el (semantic-symref-grep-shell): New var. (semantic-symref-perform-search): Use it. Calculate root dir with semantic-symref-calculate-rootdir. (semantic-symref-derive-find-filepatterns): Improve error message. * semantic/symref/list.el (semantic-symref-results-mode-map): New bindings. (semantic-symref-auto-expand-results): New option. (semantic-symref-results-dump): Obey auto-expand. (semantic-symref-list-expand-all, semantic-symref-regexp) (semantic-symref-list-contract-all) (semantic-symref-list-map-open-hits) (semantic-symref-list-update-open-hits) (semantic-symref-list-create-macro-on-open-hit) (semantic-symref-list-call-macro-on-open-hits): New functions. (semantic-symref-list-menu-entries) (semantic-symref-list-menu): New vars. (semantic-symref-list-map-open-hits): Move cursor to beginning of match before calling the mapped function. * semantic/doc.el (semantic-documentation-comment-preceeding-tag): Do nothing if the mode doesn't provide comment-start-skip. * semantic/scope.el (semantic-analyze-scope-nested-tags-default): Strip duplicates. (semantic-analyze-scoped-inherited-tag-map): Take the tag we are looking for as part of the scoped tags list. * semantic/html.el (semantic-default-html-setup): Add senator-step-at-tag-classes. * semantic/decorate/include.el (semantic-decoration-on-unknown-includes): Change light bgcolor. (semantic-decoration-on-includes-highlight-default): Check that the include tag has a postion. * semantic/complete.el (semantic-collector-local-members): (semantic-complete-read-tag-local-members) (semantic-complete-jump-local-members): New class and functions. (semantic-complete-self-insert): Save excursion before completing. * semantic/analyze/complete.el (semantic-analyze-possible-completions-default): If no completions are found, return the raw by-name-only completion list. Add FLAGS arguments. Add support for 'no-tc (type constraint) and 'no-unique, or no stripping duplicates. (semantic-analyze-possible-completions-default): Add FLAGS arg. * semantic/util-modes.el (semantic-stickyfunc-show-only-functions-p): New option. (semantic-stickyfunc-fetch-stickyline): Don't show stickytext for the very first line in a buffer. * semantic/util.el (semantic-hack-search) (semantic-recursive-find-nonterminal-by-name) (semantic-current-tag-interactive): Deleted. (semantic-describe-buffer): Fix expand-nonterminal. Add lex-syntax-mods, type relation separator char, and command separation char. (semantic-sanity-check): Only message if called interactively. * semantic/tag.el (semantic-tag-deep-copy-one-tag): Copy the :filename property and the tag position. * semantic/lex-spp.el (semantic-lex-spp-lex-text-string): Add recursion limit. * semantic/imenu.el (semantic-imenu-bucketize-type-members): Make this buffer local, not the obsoleted variable. * semantic/idle.el: Add breadcrumbs support. (semantic-idle-summary-current-symbol-info-default) (semantic-idle-tag-highlight) (semantic-idle-completion-list-default): Use semanticdb-without-unloaded-file-searches for speed, and to conform to the controls that specify if the idle timer is supposed to be parsing unparsed includes. (semantic-idle-symbol-highlight-face) (semantic-idle-symbol-maybe-highlight): Rename from *-summary-*. Callers changed. (semantic-idle-work-parse-neighboring-files-flag): Default to nil. (semantic-idle-work-update-headers-flag): New var. (semantic-idle-work-for-one-buffer): Use it. (semantic-idle-local-symbol-highlight): Rename from semantic-idle-tag-highlight. (semantic-idle-truncate-long-summaries): New option. * semantic/ia.el (semantic-ia-cache) (semantic-ia-get-completions): Deleted. Callers changed. (semantic-ia-show-variants): New command. (semantic-ia-show-doc): If doc is empty, don't make a temp buffer. (semantic-ia-show-summary): If there isn't anything to show, say so. * semantic/grammar.el (semantic-grammar-create-package): Save the buffer even in batch mode. * semantic/fw.el (semanticdb-without-unloaded-file-searches): New macro. * semantic/dep.el (semantic-dependency-find-file-on-path): Fix case dereferencing ede-object when it is a list. * semantic/db-typecache.el (semanticdb-expand-nested-tag) (semanticdb-typecache-faux-namespace): New functions. (semanticdb-typecache-file-tags) (semanticdb-typecache-merge-streams): Use them. (semanticdb-typecache-file-tags): When deriving tags from a file, give the mode a chance to monkey with the tag copy. (semanticdb-typecache-find-default): Wrap find in save-excursion. (semanticdb-typecache-find-by-name-helper): Merge found names down. * semantic/db-global.el (semanticdb-enable-gnu-global-in-buffer): Don't show messages if GNU Global is not available and we don't want to throw an error. * semantic/db-find.el (semanticdb-find-result-nth-in-buffer): When trying to normalize the tag to a buffer, don't error if set-buffer method doesn't exist. * semantic/db-file.el (semanticdb-save-db): Simplify msg. * semantic/db.el (semanticdb-refresh-table): If forcing a refresh on a file not in a buffer, use semantic-find-file-noselect and delete the buffer after use. (semanticdb-current-database-list): When calculating root via hooks, force it through true-filename and skip the list of possible roots. * semantic/ctxt.el (semantic-ctxt-imported-packages): New. * semantic/analyze/debug.el (semantic-analyzer-debug-insert-tag): Reset standard output to current buffer. (semantic-analyzer-debug-global-symbol) (semantic-analyzer-debug-missing-innertype): Change "prefix" to "symbol" in messages. * semantic/analyze/refs.el: (semantic-analyze-refs-impl) (semantic-analyze-refs-proto): When calculating value, make sure the found tag is 'similar' to the originating tag. (semantic--analyze-refs-find-tags-with-parent): Attempt to identify matches via imported symbols of parents. (semantic--analyze-refs-full-lookup-with-parents): Do a deep search during the brute search. * semantic/analyze.el (semantic-analyze-find-tag-sequence-default): Be robust to calculated scopes being nil. * semantic/bovine/c.el (semantic-c-describe-environment): Add project macro symbol array. (semantic-c-parse-lexical-token): Add recursion limit. (semantic-ctxt-imported-packages, semanticdb-expand-nested-tag): New overrides. (semantic-expand-c-tag-namelist): Split a full type from a typedef out to its own tag. (semantic-expand-c-tag-namelist): Do not split out a typedef'd inline type if it is an anonymous type. (semantic-c-reconstitute-token): Use the optional initializers as a clue that some function is probably a constructor. When defining the type of these constructors, split the parent name, and use only the class part, if applicable. * semantic/bovine/c-by.el: * semantic/wisent/python-wy.el: Regenerate.

\input texinfo                  @c -*-texinfo-*-
@setfilename ../../info/auth
@settitle Emacs auth-source Library @value{VERSION}

@set VERSION 0.2

@copying
This file describes the Emacs auth-source library.

Copyright @copyright{} 2008, 2009, 2010 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License''
in the Emacs manual.

(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual.  Buying copies from the FSF supports it in
developing GNU and promoting software freedom.''

This document is part of a collection distributed under the GNU Free
Documentation License.  If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying

@dircategory Emacs
@direntry
* Auth-source: (auth).          The Emacs auth-source library.
@end direntry

@titlepage
@title Emacs auth-source Library
@author by Ted Zlatanov
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Emacs auth-source
This manual describes the Emacs auth-source library.

It is a way for multiple applications to share a single configuration
(in Emacs and in files) for user convenience.

@insertcopying

@menu
* Overview::                    Overview of the auth-source library.
* Help for users::              
* Help for developers::         
* Index::                       
* Function Index::              
* Variable Index::              
@end menu
@end ifnottex

@node Overview
@chapter Overview

The auth-source library is simply a way for Emacs and Gnus, among
others, to find the answer to the old burning question ``I have a
server name and a port, what are my user name and password?''

The auth-source library actually supports more than just the user name
(known as the login) or the password, but only those two are in use
today in Emacs or Gnus.  Similarly, the auth-source library can in
theory support multiple storage formats, but currently it only
understands the classic ``netrc'' format, examples of which you can
see later in this document.

@node Help for users
@chapter Help for users

``Netrc'' files are a de facto standard.  They look like this:
@example
machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport}
@end example

The machine is the server (either a DNS name or an IP address).

The port is optional.  If it's missing, auth-source will assume any
port is OK.  Actually the port is a protocol name or a port number so
you can have separate entries for port @var{143} and for protocol
@var{imap} if you fancy that.  Anyway, you can just omit the port if
you don't need it.

The login and password are simply your login credentials to the server.

``Netrc'' files are usually called @code{.authinfo} or @code{.netrc};
nowadays @code{.authinfo} seems to be more popular and the auth-source
library encourages this confusion by making it the default, as you'll
see later.

If you have problems with the port, set @code{auth-source-debug} to
@code{t} and see what port the library is checking in the
@code{*Messages*} buffer.  Ditto for any other problems, your first
step is always to see what's being checked.  The second step, of
course, is to write a blog entry about it and wait for the answer in
the comments.

You can customize the variable @code{auth-sources}.  The following may
be needed if you are using an older version of Emacs or if the
auth-source library is not loaded for some other reason.

@lisp
(require 'auth-source)             ;; probably not necessary
(customize-variable 'auth-sources) ;; optional, do it once
@end lisp

@defvar auth-sources

The @code{auth-sources} variable tells the auth-source library where
your netrc files live for a particular host and protocol.  While you
can get fancy, the default and simplest configuration is:

@lisp
(setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t)))
@end lisp

This says ``for any host and any protocol, use just that one file.''
Sweet simplicity.  In fact, this is already the default, so unless you
want to move your netrc file, it will just work if you have that
file.  You may not, though, so make sure it exists.

By adding multiple entries to @code{auth-sources} with a particular
host or protocol, you can have specific netrc files for that host or
protocol.  Usually this is unnecessary but may make sense if you have
shared netrc files or some other unusual setup (90% of Emacs users
have unusual setups and the remaining 10% are @emph{really} unusual).

@end defvar

If you don't customize @code{auth-sources}, you'll have to live with
the defaults: any host and any port are looked up in the netrc
file @code{~/.authinfo.gpg}.  This is an encrypted file if and only if
you set up EPA, which is strongly recommended.

@lisp
(require 'epa-file)
(epa-file-enable)
;;; VERY important if you want symmetric encryption
;;; irrelevant if you don't
(setq epa-file-cache-passphrase-for-symmetric-encryption t)
@end lisp

The simplest working netrc line example is one without a port.

@example
machine YOURMACHINE login YOU password YOURPASSWORD
@end example

This will match any authentication port.  Simple, right?  But what if
there's a SMTP server on port 433 of that machine that needs a
different password from the IMAP server?

@example
machine YOURMACHINE login YOU password SMTPPASSWORD port 433
machine YOURMACHINE login YOU password GENERALPASSWORD
@end example

For url-auth authentication (HTTP/HTTPS), you need to put this in your
netrc file:

@example
machine yourmachine.com:80 port http login testuser password testpass
@end example

This will match any realm and authentication method (basic or digest)
over HTTP.  HTTPS is set up similarly.  If you want finer controls,
explore the url-auth source code and variables.

For Tramp authentication, use:

@example
machine yourmachine.com port scp login testuser password testpass
@end example

Note that the port denotes the Tramp connection method.  When you
don't use a port entry, you match any Tramp method, as explained
earlier.  Since Tramp has about 88 connection methods, this may be
necessary if you have an unusual (see earlier comment on those) setup.

@node Help for developers
@chapter Help for developers

The auth-source library only has one function for external use.

@defun auth-source-user-or-password mode host port

Retrieve appropriate authentication tokens, determined by @var{mode},
for host @var{host} and @var{port}.  If @code{auth-source-debug} is t,
debugging messages will be printed.  Set @code{auth-source-debug} to a
function to use that function for logging.  The parameters passed will
be the same that the @code{message} function takes, that is, a string
formatting spec and optional parameters.

If @var{mode} is a list of strings, the function will return a list of
strings or @code{nil} objects (thus you can avoid parsing the netrc
file more than once).  If it's a string, the function will return a
string or a @code{nil} object.  Currently only the modes ``login'' and
``password'' are recognized but more may be added in the future.

@var{host} is a string containing the host name.

@var{port} contains the protocol name (e.g. ``imap'') or
a port number.  It must be a string, corresponding to the port in the
users' netrc files.

@example
;; IMAP example
(setq auth (auth-source-user-or-password
            '("login" "password")
            "anyhostnamehere"
            "imap"))
(nth 0 auth) ; the login name
(nth 1 auth) ; the password
@end example

@end defun

@node Index
@chapter Index
@printindex cp

@node Function Index
@chapter Function Index
@printindex fn

@node Variable Index
@chapter Variable Index
@printindex vr

@bye

@c End:

@ignore
   arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94
@end ignore