Okamsn 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: