From: Philip Kaludercic <philipk@posteo.net>
To: Okamsn <okamsn@protonmail.com>
Cc: emacs-devel@gnu.org
Subject: Re: How to install documentation in sub-directory with Package VC?
Date: Mon, 10 Apr 2023 13:39:13 +0000 [thread overview]
Message-ID: <871qkreu0u.fsf@posteo.net> (raw)
In-Reply-To: <87zg7lf25x.fsf@posteo.net> (Philip Kaludercic's message of "Thu, 06 Apr 2023 17:42:02 +0200")
Just pinging to see if you want to finish this or if I should modify the
patch? Seeing as the Emacs 29 release is coming closer, I'd rather have
this fixed sooner than later.
Philip Kaludercic <philipk@posteo.net> writes:
> 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.
next prev parent reply other threads:[~2023-04-10 13:39 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-03-14 3:13 How to install documentation in sub-directory with Package VC? Okamsn
2023-03-14 15:56 ` Philip Kaludercic
2023-03-15 9:41 ` Philip Kaludercic
2023-03-16 1:37 ` Okamsn
2023-03-16 8:44 ` Philip Kaludercic
2023-03-28 1:50 ` Okamsn
2023-03-28 7:41 ` Philip Kaludercic
2023-04-02 0:41 ` Okamsn
2023-04-02 5:24 ` Eli Zaretskii
2023-04-05 7:30 ` Philip Kaludercic
2023-04-06 3:52 ` Okamsn
2023-04-06 15:42 ` Philip Kaludercic
2023-04-10 13:39 ` Philip Kaludercic [this message]
2023-04-12 0:04 ` Okamsn
2023-04-12 7:27 ` Philip Kaludercic
2023-04-12 7:41 ` Eli Zaretskii
2023-04-12 7:48 ` Philip Kaludercic
2023-04-07 21:46 ` Jonas Bernoulli
2023-04-08 8:36 ` Philip Kaludercic
2023-04-09 18:39 ` Jonas Bernoulli
2023-04-09 20:44 ` Lynn Winebarger
2023-04-09 21:55 ` Philip Kaludercic
2023-03-28 11:48 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=871qkreu0u.fsf@posteo.net \
--to=philipk@posteo.net \
--cc=emacs-devel@gnu.org \
--cc=okamsn@protonmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).