[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: How to install documentation in sub-directory with Package VC?
From: |
Philip Kaludercic |
Subject: |
Re: How to install documentation in sub-directory with Package VC? |
Date: |
Thu, 06 Apr 2023 15:42:02 +0000 |
Okamsn <okamsn@protonmail.com> writes:
> On 2023-04-05 07:30 UTC, Philip Kaludercic wrote:
>>> + 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). These things are described by a package's
>> ^
>> a bit informal? I think you can just
>> drop the word and still convey the same
>> information.
>
> I acknowledge that "things" is unspecific, but I do think that the
> paragraph flows better with a noun there. What if "things" was swapped
> out for "properties"? I think that it would work well with the use of
> "property list" a few sentences later.
That sounds good!
>
>>> + 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.
>>
>> Not sure if this might be confusing. package-vc has heuristics to try
>> and guess how to install a package, so it is /possible/ but not
>> /reliable/ to install a package from a third-party archive like MELPA.
>> Then again, perhaps we don't have to mention that at all in the manual,
>> so as to not promote an unreliable trick.
>
> I wasn't aware of these heuristics. In this paragraph, I was trying to
> describe where the known specifications come from, as in the
> "elpa-package.eld" file.
The point here is that you can install a package listed in an archive,
even though the archive doesn't generate a elpa-package.eld. It works
most of the time, in the remaining cases the heuristics help but it is
not ideal. Should this be explained?
>>> +@item :main-file
>>> +A string containing 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.
>>
>> (This is true most of the time, but if you check out what
>> `package-vc--main-file' does, then you will see that this is not
>> necessary. Again, I don't think this implementation detail is worth
>> documenting publicly.)
>
> Are you saying that you don't want to describe the heuristic, or that
> you don't want to describe the default behavior? I would like to keep
> the mention of the default behavior.
I don't want to document the heuristic, as IMO this is an implementation
detail. Lets keep this the way it is.
>>> + A package's specification can also be given manually as the first
>>> +argument to @code{package-vc-install}. 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 following keys.
>>>
>>> +For definitions of basic terms for working with code repositories and
>>> +version control systems, see @xref{VCS Concepts,,,emacs, The GNU Emacs
>>> +Manual}.
>>
>> Should this paragraph be moved down below the table? Otherwise the "any
>> of the following" reads funnily.
>
> I don't think that this paragraph should be moved to after the table. In
> my opinion, it is better to have the link, which defines the terms,
> placed before the using of the terms.
Another idea would be to mark the paragraph up using @quotation,
@cartouche or a Footnote?
> Instead, what if the sentence ended like "using any of the keys in the
> table below"?
That would also be fine.
>>> diff --git a/lisp/emacs-lisp/package-vc.el b/lisp/emacs-lisp/package-vc.el
>>> index 253b35f1f1a..cbc9a1ecece 100644
>>> --- a/lisp/emacs-lisp/package-vc.el
>>> +++ b/lisp/emacs-lisp/package-vc.el
>>> @@ -152,25 +152,31 @@ package-vc-selected-packages
>>
>> I believe I mentioned this before, but what do you think about just
>> linking to the manual, and not duplicating the information here and
>> there? It would make maintenance easier, but might not be nice for
>> users on systems that do not come installed with documentation like
>> Debian... Then again, this wouldn't be the only place where this would
>> affect users.
>
> Some of the information in the documentation string is probably not
> relevant for users wishing to give their own specification. For example,
> the information about a package archive's default VC backend that Eli
> Zaretskii pointed out. Would you like to limit the information in the
> table to what is relevant for giving a manual specification, or should
> the table be a description of the behavior for all specifications?
What I had in mind was just replace the ad-hoc list in the docstring
with a reference to the new section in the manual:
diff --git a/lisp/emacs-lisp/package-vc.el b/lisp/emacs-lisp/package-vc.el
index ddc7ec4679b..6fe30e08830 100644
--- a/lisp/emacs-lisp/package-vc.el
+++ b/lisp/emacs-lisp/package-vc.el
@@ -147,32 +147,9 @@ package-vc-selected-packages
- 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 \"Package specification\" subsection
+ under 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
> If it is made more general, then I have no strong reason to disagree
> with keeping the information in only one place. However, I will defer to
> others on this.
I am just making suggestions here and am interested in what you think.
My opinion isn't worth more than yours.
- Re: How to install documentation in sub-directory with Package VC?, Okamsn, 2023/04/02
- 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 <=
- 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