Re: package-vc-install fails to build docs

[Philip Kaludercic]

Joseph Turner <joseph@breatheoutbreathe.in> writes:

> Thank you Ruijie Yu and Philip Kaludercic for your help!
>
> Philip Kaludercic <philipk@posteo.net> writes:
>
>> Ruijie Yu via Users list for the GNU Emacs text editor
>> <help-gnu-emacs@gnu.org> writes:
>>> I'm looking at the package-vc source code, and it doesn't seem to try to
>>> autodetect any doc files at the moment.  Try adding `:doc` in your
>>> `package-vc-install' call and see if anything changes.
>
> Actually, it looks like extra plist elements like :doc are stripped away
> in package-vc--unpack. package-vc--unpack doesn't pass its pkg-spec arg
> along to package-vc--unpack-1. package-vc--unpack-1 then calls
> package-vc--desc->spec, which gets the spec anew from ELPA IIUC.
>
> Regardless, I believe the issue lies elsewhere, see below.
>
>> Right, if you just pass a URL, then package-vc has no metadata.  But
>> since org-transclusion is on ELPA, you can invoke it like this:
>>
>>   (package-vc-install 'org-transclusion)
>>
>> then it should re-use the package specification that GNU ELPA provides.
>> If you invoke package-vc-install interactively, it would also prompt you
>> with this package name.
>>
>> That being said, I just tried it out and it seems that it still doesn't
>> work because of a discrepancy between the package specification on ELPA
>> that mentions docs/org-transclusion.org to be the documentation file
>>
>>  (org-transclusion   :url "https://github.com/nobiot/org-transclusion";
>>   :make "org-transclusion.org"
>>   :doc "docs/org-transclusion.org"
>>   :readme "README.org")
>>
>> and as you say the fact that the actual manual lies in
>> docs/org-transclusion-manual.org.  But this is an issue that should
>> either be fixed in ELPA if the maintainer wishes this file to be used,
>> or upstream if this is a mistake.
>
> nobiot (org-transclusion author) points out here
> https://github.com/nobiot/org-transclusion/issues/182#issuecomment-1518676316
> that docs/org-transclusion.org needs to be generated from
> docs/org-transclusion-manual.org according to
>
> :make "org-transclusion.org"
>
> (search for ":make" in
> https://git.savannah.gnu.org/cgit/emacs/elpa.git/plain/README )
>
> It appears that package-vc hasn't been taught to make use of the :make
> package spec key. A quick search inside of
> https://git.savannah.gnu.org/cgit/emacs/elpa.git/tree/elpa-packages#n491
> reveals only two other packages besides org-transclusion that use it.

You are right (and I totally missed the :make entry in the specification
above).  Package-vc did intentionally NOT add :make or :shell-command
support, for the sake of user safety.  It wouldn't be difficult to
implement this, if we could find a way to make it reasonably safe
(e.g. if the user has to opt-in or we trust package specifications if
they were delivered by a trusted package archive).

>>> I'm on recent master, what is your Emacs version?
>
> GNU Emacs 30.0.50 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.30,
> cairo version 1.16.0)
>
> In conclusion, I think the issue is that package-vc doesn't yet support
> the package spec :make key.
>
> Cheers,
>
> Joseph