On 2023-03-28 07:41 UTC, Philip Kaludercic wrote: >> From 1d4d4ebfd874d99d5e2d29078f3316f49dcf3136 Mon Sep 17 00:00:00 2001 >> From: Earl Hyatt >> Date: Mon, 27 Mar 2023 20:57:31 -0400 >> Subject: [PATCH] Add more documentation for the keys of >> `package-vc-selected-packages`. >> >> * doc/emacs/package.texi (Fetching Package Sources): List the >> accepted keys. >> * lisp/emacs-lisp/package-vc.el (package-vc-selected-packages): >> Mention the `:doc` key. >> --- >> doc/emacs/package.texi | 53 +++++++++++++++++++++++++++++++++++ >> lisp/emacs-lisp/package-vc.el | 4 +++ >> 2 files changed, 57 insertions(+) >> >> diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi >> index 7a2bc11d03c..6f1fad2291a 100644 >> --- a/doc/emacs/package.texi >> +++ b/doc/emacs/package.texi >> @@ -578,3 +578,56 @@ Fetching Package Sources >> and initializes the code. Note that you might have to use >> @code{package-vc-refresh} to repeat the initialization and update the >> autoloads. > > Should a sub-heading inside the same node be added here? I have added one. > >> + >> +There are two ways for Emacs to learn how and whence to install a >> +package from source. The first way, when supported, is to > ^ > > The phrasing "when supported" doesn't sound clear. The user doesn't > know what this depends on. I have tried to make it clear that it depends on the archive. >> +automatically download the needed information from a package archive >> +(@pxref{Package Archives,,,elisp, The Emacs Lisp Reference Manual}). >> +This is what is done when only specifying the symbol of a package. > > I have the feeling the phrase "package specification" should be > mentioned somewhere here. I added this phrase. >> +@example >> +@group >> +(package-vc-install 'csv-mode) >> +@end group >> +@end example >> + >> +The second way is to specify this information manually in the first >> +argument of @code{package-vc-install}, in the form of >> +@samp{(@var{name} . @var{spec})}. @var{spec} should be a property >> +list using any of the following keys: >> + >> +@itemize @bullet >> +@item @code{:url} >> +A URL specifying the repository from which to fetch the package's >> +source code. >> + >> +@item @code{:branch} >> +The name of the branch to checkout after cloning the directory. > > At the risk of being pedantic, we check out the right branch /while/ > cloning, not /after/ cloning and I don't know if that matters. (I also > just now noticed that I used the same phrasing in the documentation > string for `package-vc-selected-packages'). I tried to do as Eli Zaretskii asked and changed it to be less Git specific. Does it still convey what you want? >> +@item @code{:lisp-dir} >> +The repository-relative name of the directory to use for loading the >> +Lisp sources, if not the root directory of the repository. >> + >> +@item @code{:main-file} >> +The main file of the project, from which to gather package metadata. >> +If not given, the assumed default is the package name with ".el" >> +appended to it. >> + >> +@item @code{:doc} >> +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 @code{:vc-backend} >> +The VC backend to use for cloning the package. If omitted, >> +the process will fall back onto the archive default or onto >> +the value of @code{package-vc-default-backend}. > > Should we link to (emacs) Version Control here? Linked to the VC Concepts above the list. >> +;; Specifying information manually: >> +(package-vc-install >> + '(csv-mode :url "https://git.sv.gnu.org/git/emacs/elpa.git" >> + :branch "externals/csv-mode")) > > I worry that this example might be confusing, for those people who don't > know how ELPA works. It would either be worth mentioning that elpa.git > is a mirror with different packages on different branches, or to take > some other example (like AucTeX). I switched it to BBDB, which uses several keys. > I guess it will be good to also add :doc to the user option type. Done. On 2023-03-28 11:48 UTC, Eli Zaretskii wrote: >> +There are two ways for Emacs to learn how and whence to install a >> +package from source. The first way, when supported, is to >> +automatically download the needed information from a package archive >> +(@pxref{Package Archives,,,elisp, The Emacs Lisp Reference Manual}). >> +This is what is done when only specifying the symbol of a package. > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > Passive voice alert! Could you perhaps rephrase this avoiding the > passive voice? I have reworded it. Please check again. >> +The second way is to specify this information manually in the first >> +argument of @code{package-vc-install}, in the form of >> +@samp{(@var{name} . @var{spec})}. @var{spec} should be a property > > This should be @code, not @samp. Done. >> +list using any of the following keys: >> + >> +@itemize @bullet > > This should be "@table @code", not @itemize. The result is more > readable. @itemize is for free text, not for systematic description > of several optional features and attributes. Done. >> +@item @code{:branch} >> +The name of the branch to checkout after cloning the directory. > ^^^^^^^^^^^^^^^^^^ ^^^^^^^^ ^^^^^^^ > Can we make this less Git-specific? Attempted, but I have only used Git. I linked to the VCS Concepts section above the list. >> +@item @code{:lisp-dir} >> +The repository-relative name of the directory to use for loading the >> +Lisp sources, if not the root directory of the repository. > > The "if not" part is confusing. I suggest ", which defaults to the > root directory of the repository" instead. Done. >> +@item @code{:main-file} >> +The main file of the project, from which to gather package metadata. >> +If not given, the assumed default is the package name with ".el" >> +appended to it. > > I'd drop the "assumed" part. It adds nothing to the description. Done. >> +@item @code{:doc} >> +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. > ^^ > Two spaces there, please. Also, the spelling is "Texinfo", not > "TexInfo". Done. >> +@item @code{:vc-backend} >> +The VC backend to use for cloning the package. If omitted, > > A cross-reference here to the place where VC backends are described > would be good. Done. >> +the process will fall back onto the archive default or onto >> +the value of @code{package-vc-default-backend}. > > What does it mean to "fall back onto the archive default"? Each archive has a default backend. As that's not relevant to specifying the information manually, I've removed it. >> + `:doc' (string) >> + The documentation file from which to build an Info file. >> + This can be a TexInfo file or an Org file. > ^^^^^^^ > Spelling again. Fixed.