Add more documentation for the keys of package-vc-selected-packages.
* doc/emacs/package.texi (Specifying Package Sources): List the accepted keys in a new subsection of Fetching Package Sources. * lisp/emacs-lisp/package-vc.el (package-vc-selected-packages): Mention the `:doc` key. Add the `:doc` key to the Customize form, mention the new Info node, correct "TexInfo" to "Texinfo", avoid Git-specific terms for the description of `:branch`, mention guessing `:vc-backend` based on the URL.
This commit is contained in:
Earl Hyatt
Philip Kaludercic
parent
7972b76c2c
commit
6e6e8b5c97
2 changed files with 81 additions and 26 deletions
|
|
@ -578,3 +578,80 @@ from the package directory (@pxref{Package Files}) to your checkout
|
|||
and initializes the code. Note that you might have to use
|
||||
@code{package-vc-refresh} to repeat the initialization and update the
|
||||
autoloads.
|
||||
|
||||
@subsection Specifying Package Sources
|
||||
@cindex package specification
|
||||
@cindex specification, for source packages
|
||||
|
||||
To install a package from source, Emacs must know where to get the
|
||||
package's source code (such as a code repository) and basic
|
||||
information about the structure of the code (such as the main file in
|
||||
a multi-file package). A @dfn{package specification} describes these
|
||||
properties.
|
||||
|
||||
When supported by a package archive (@pxref{Package
|
||||
Archives,,,elisp, The Emacs Lisp Reference Manual}), Emacs can
|
||||
automatically download a package's specification from said archive.
|
||||
If the first argument passed to @code{package-vc-install} is a symbol
|
||||
naming a package, then Emacs will use the specification provided by
|
||||
the archive for that package.
|
||||
|
||||
@example
|
||||
@group
|
||||
;; Emacs will download BBDB's specification from GNU ELPA:
|
||||
(package-vc-install 'bbdb)
|
||||
@end group
|
||||
@end example
|
||||
|
||||
The first argument to @code{package-vc-install} may also be a
|
||||
package specification. This allows you to install source packages
|
||||
from locations other than the known archives listed in the user option
|
||||
@code{package-archives}. A package specification is a list of the
|
||||
form @code{(@var{name} . @var{spec})}, in which @var{spec} should be a
|
||||
property list using any of the keys in the table below.
|
||||
|
||||
For definitions of basic terms for working with code repositories and
|
||||
version control systems, see @ref{VCS Concepts,,,emacs, The GNU Emacs
|
||||
Manual}.
|
||||
|
||||
@table @code
|
||||
@item :url
|
||||
A string providing the URL that specifies the repository from which to
|
||||
fetch the package's source code.
|
||||
|
||||
@item :branch
|
||||
A string providing the revision of the code to install. Do not
|
||||
confuse this with a package's version number.
|
||||
|
||||
@item :lisp-dir
|
||||
A string providing the repository-relative name of the directory to
|
||||
use for loading the Lisp sources, which defaults to the root directory
|
||||
of the repository.
|
||||
|
||||
@item :main-file
|
||||
A string providing the main file of the project, from which to gather
|
||||
package metadata. If not given, the default is the package name with
|
||||
".el" appended to it.
|
||||
|
||||
@item :doc
|
||||
A string providing the repository-relative name of the documentation
|
||||
file from which to build an Info file. This can be a Texinfo file or
|
||||
an Org file.
|
||||
|
||||
@item :vc-backend
|
||||
A symbol naming the VC backend to use for downloading a copy of the
|
||||
package's repository (@pxref{Version Control Systems,,,emacs, The GNU
|
||||
Emacs Manual}). If omitted, Emacs will attempt to make a guess based
|
||||
on the provided URL, or, failing that, the process will fall back onto
|
||||
the value of @code{package-vc-default-backend}.
|
||||
@end table
|
||||
|
||||
@example
|
||||
@group
|
||||
;; Specifying information manually:
|
||||
(package-vc-install
|
||||
'(bbdb :url "https://git.savannah.nongnu.org/git/bbdb.git"
|
||||
:lisp-dir "lisp"
|
||||
:doc "doc/bbdb.texi"))
|
||||
@end group
|
||||
@end example
|
||||
|
|
|
|||
|
|
@ -142,32 +142,9 @@ is a symbol designating the package and SPEC is one of:
|
|||
|
||||
- nil, if any package version can be installed;
|
||||
- a version string, if that specific revision is to be installed;
|
||||
- a property list, describing a package specification. Valid
|
||||
key/value pairs are
|
||||
|
||||
`:url' (string)
|
||||
The URL of the repository used to fetch the package source.
|
||||
|
||||
`:branch' (string)
|
||||
If given, the name of the branch to checkout after cloning the directory.
|
||||
|
||||
`:lisp-dir' (string)
|
||||
The repository-relative name of the directory to use for loading the Lisp
|
||||
sources. If not given, the value defaults to the root directory
|
||||
of the repository.
|
||||
|
||||
`:main-file' (string)
|
||||
The main file of the project, relevant to gather package metadata.
|
||||
If not given, the assumed default is the package name with \".el\"
|
||||
appended to it.
|
||||
|
||||
`:vc-backend' (symbol)
|
||||
A symbol of the VC backend to use for cloning the package. The
|
||||
value ought to be a member of `vc-handled-backends'. If omitted,
|
||||
`vc-clone' will fall back onto the archive default or on
|
||||
`package-vc-default-backend'.
|
||||
|
||||
All other keys are ignored.
|
||||
- a property list, describing a package specification. For more
|
||||
details, please consult the subsection \"Specifying Package
|
||||
Sources\" in the Info node `(emacs)Fetching Package Sources'.
|
||||
|
||||
This user option will be automatically updated to store package
|
||||
specifications for packages that are not specified in any
|
||||
|
|
@ -181,6 +158,7 @@ archive."
|
|||
(:branch string)
|
||||
(:lisp-dir string)
|
||||
(:main-file string)
|
||||
(:doc string)
|
||||
(:vc-backend symbol)))))
|
||||
:version "29.1")
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue