all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* (M)Elpa & info/diir files ?
@ 2023-03-12  3:01 David Masterson
  2023-03-12 12:23 ` Philip Kaludercic
  0 siblings, 1 reply; 4+ messages in thread
From: David Masterson @ 2023-03-12  3:01 UTC (permalink / raw)
  To: emacs-devel

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



^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: (M)Elpa & info/diir files ?
  2023-03-12  3:01 (M)Elpa & info/diir files ? David Masterson
@ 2023-03-12 12:23 ` Philip Kaludercic
  2023-03-12 20:34   ` David Masterson
  0 siblings, 1 reply; 4+ messages in thread
From: Philip Kaludercic @ 2023-03-12 12:23 UTC (permalink / raw)
  To: David Masterson; +Cc: emacs-devel

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



^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: (M)Elpa & info/diir files ?
  2023-03-12 12:23 ` Philip Kaludercic
@ 2023-03-12 20:34   ` David Masterson
  2023-03-12 23:00     ` Philip Kaludercic
  0 siblings, 1 reply; 4+ messages in thread
From: David Masterson @ 2023-03-12 20:34 UTC (permalink / raw)
  To: Philip Kaludercic; +Cc: emacs-devel

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



^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: (M)Elpa & info/diir files ?
  2023-03-12 20:34   ` David Masterson
@ 2023-03-12 23:00     ` Philip Kaludercic
  0 siblings, 0 replies; 4+ messages in thread
From: Philip Kaludercic @ 2023-03-12 23:00 UTC (permalink / raw)
  To: David Masterson; +Cc: emacs-devel

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



^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2023-03-12 23:00 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-03-12  3:01 (M)Elpa & info/diir files ? David Masterson
2023-03-12 12:23 ` Philip Kaludercic
2023-03-12 20:34   ` David Masterson
2023-03-12 23:00     ` Philip Kaludercic

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.