Re: How to install documentation in sub-directory with Package VC?

[Okamsn <okamsn@protonmail.com>]

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.


>> +  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.

>> +@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.

>> +  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.

Instead, what if the sentence ended like "using any of the keys in the
table below"?


>> 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?

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.