(M)Elpa & info/diir files ?

(M)Elpa & info/diir files ?

[David Masterson]

In an Emacs package that has a README.org, it's easy to build a Makefile
which generates an .info file for inclusion in the package.  However,
does this imply that the .info file must be checked into the git repo
for (M)Elpa to pick it up for inclusion in the package?  Is this the
standard?  I don't like checking in derivative files unnecessarily.

-- 
David Masterson

Re: (M)Elpa & info/diir files ?

[Philip Kaludercic]

David Masterson <dsmasterson@gmail.com> writes:

> In an Emacs package that has a README.org, it's easy to build a Makefile
> which generates an .info file for inclusion in the package.  However,
> does this imply that the .info file must be checked into the git repo
> for (M)Elpa to pick it up for inclusion in the package?  Is this the
> standard?  I don't like checking in derivative files unnecessarily.

I can only speak for {GNU,NonGNU} ELPA, but no the build system can
generate .info files from .org or .texi files (which also means that you
don't need to check in .texi files if your manual is written using
org-mode and exported using ox-texinfo).

But on a different note, I would advise against using the README file as
the manual.  The README is IMO better suited as a brief explanation of a
package with a few pointers than an exhaustive resource.  When I want to
check out a package using C-h P, I'd rather have the content fit on my
screen without having to scroll.

-- 
Philip Kaludercic

Re: (M)Elpa & info/diir files ?

[David Masterson]

Philip Kaludercic <philipk@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>> In an Emacs package that has a README.org, it's easy to build a Makefile
>> which generates an .info file for inclusion in the package.  However,
>> does this imply that the .info file must be checked into the git repo
>> for (M)Elpa to pick it up for inclusion in the package?  Is this the
>> standard?  I don't like checking in derivative files unnecessarily.
>
> I can only speak for {GNU,NonGNU} ELPA, but no the build system can
> generate .info files from .org or .texi files (which also means that you
> don't need to check in .texi files if your manual is written using
> org-mode and exported using ox-texinfo).

A few questions:
1. Does Elpa kick the Makefile in a package?
2. How does it know what arguments to give Make?  Package recipe file?
3. How does Elpa ensure it is picking up (say) the right Org for org->texi?

MELPA.org has some documentation in its Github repo.  Does ELPA have
similar documentation? If so, where?

> But on a different note, I would advise against using the README file as
> the manual.  The README is IMO better suited as a brief explanation of a
> package with a few pointers than an exhaustive resource.  When I want to
> check out a package using C-h P, I'd rather have the content fit on my
> screen without having to scroll.

Understood.  Goal was to get the flow working.  Then we can create a
PKG.org file from which a small README.org (or .md) and full PKG.info
can be generated.

-- 
David Masterson

Re: (M)Elpa & info/diir files ?

[Philip Kaludercic]

David Masterson <dsmasterson@gmail.com> writes:

> Philip Kaludercic <philipk@posteo.net> writes:
>
>> David Masterson <dsmasterson@gmail.com> writes:
>>
>>> In an Emacs package that has a README.org, it's easy to build a Makefile
>>> which generates an .info file for inclusion in the package.  However,
>>> does this imply that the .info file must be checked into the git repo
>>> for (M)Elpa to pick it up for inclusion in the package?  Is this the
>>> standard?  I don't like checking in derivative files unnecessarily.
>>
>> I can only speak for {GNU,NonGNU} ELPA, but no the build system can
>> generate .info files from .org or .texi files (which also means that you
>> don't need to check in .texi files if your manual is written using
>> org-mode and exported using ox-texinfo).
>
> A few questions:
> 1. Does Elpa kick the Makefile in a package?

I belive it doesn't do so by default, but it can be told to do so either
in the package specification or in the .elpaignore file that you would
host in your repository (like a .gitignore).

> 2. How does it know what arguments to give Make?  Package recipe file?

Make will not be invoked by default, that has to be requested in the
package specification, where you would also give it the target or
targets.  FYI, it would be better if one could avoid using this feature,
because package-vc from Emacs 29 does not support it (for security
reasons).

> 3. How does Elpa ensure it is picking up (say) the right Org for org->texi?

Again, the package specification indicates what file is the right one to
use.

You can find out more about the package specification in the ELPA
README:

https://git.savannah.gnu.org/cgit/emacs/elpa.git/tree/README#n117

> MELPA.org has some documentation in its Github repo.  Does ELPA have
> similar documentation? If so, where?

See above.

>> But on a different note, I would advise against using the README file as
>> the manual.  The README is IMO better suited as a brief explanation of a
>> package with a few pointers than an exhaustive resource.  When I want to
>> check out a package using C-h P, I'd rather have the content fit on my
>> screen without having to scroll.
>
> Understood.  Goal was to get the flow working.  Then we can create a
> PKG.org file from which a small README.org (or .md) and full PKG.info
> can be generated.

That would be nice.

-- 
Philip Kaludercic