[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: How to install documentation in sub-directory with Package VC?
From: |
Okamsn |
Subject: |
Re: How to install documentation in sub-directory with Package VC? |
Date: |
Sun, 02 Apr 2023 00:41:43 +0000 |
On 2023-03-28 07:41 UTC, Philip Kaludercic wrote:
>> From 1d4d4ebfd874d99d5e2d29078f3316f49dcf3136 Mon Sep 17 00:00:00 2001
>> From: Earl Hyatt <okamsn@protonmail.com>
>> 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.
0001-Add-more-documentation-for-the-keys-of-package-vc-se.patch
Description: Text Data
- Re: How to install documentation in sub-directory with Package VC?,
Okamsn <=
- Re: How to install documentation in sub-directory with Package VC?, Eli Zaretskii, 2023/04/02
- Re: How to install documentation in sub-directory with Package VC?, Philip Kaludercic, 2023/04/05
- Re: How to install documentation in sub-directory with Package VC?, Okamsn, 2023/04/06
- Re: How to install documentation in sub-directory with Package VC?, Philip Kaludercic, 2023/04/06
- Re: How to install documentation in sub-directory with Package VC?, Philip Kaludercic, 2023/04/10
- Re: How to install documentation in sub-directory with Package VC?, Okamsn, 2023/04/12
- Re: How to install documentation in sub-directory with Package VC?, Philip Kaludercic, 2023/04/12
- Re: How to install documentation in sub-directory with Package VC?, Eli Zaretskii, 2023/04/12
- Re: How to install documentation in sub-directory with Package VC?, Philip Kaludercic, 2023/04/12