bug#65027: 30.0.50; [PATCH] Document .elpaignore behavior in the Emacs Lisp manual

[Corwin Brust]

On Fri, Aug 4, 2023 at 8:58 PM Richard Stallman <rms@gnu.org> wrote:
>
> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>   > Yeah, something more general that I've noticed is that as a package
>   > author, the documentation for how to make a package for GNU ELPA is
>   > split between the GNU ELPA README and the Emacs Lisp manual.
>
> It could be an improvement to merge all that documentation into one
> text and rewrite it for coherence and clarity.

I have been discussing a similar ideal with some others off list, of
whom I'm tagging in (potentially sharing blame with ;) only prot.

> That has a drawback: it would make the Emacs Lisp Reference Manual
> substantially bigger.  Copies would be less convenient and more
> expensive.
>
> I think there is no need for this material to be in the Emacs Lisp
> Reference Manual.  So I suggest making a separate short manual about
> adding a package to GNU ELPA.  The Emacs Lisp Reference Manual can
> direct people to it.

My/our suggestion is to create a new manual ("ELPA: the missing
manual") that should be provided with Emacs releases, with the current
version available online via gnu.org.

This new manual can start with some new (and/or moved, consolidated,
expanded, ...) sections aimed at Emacs users wanting a deeper
understanding of Emacs packaging.  Following that, it can include some
specifics ("best practices"?) especially for package authors, with the
remainder being collected manuals for ELPA packages.

A slight twist on this idea could be to frame more generally, for
example "Emacs Features and Packaging" (instead of anything about
ELPA).  This might allow

In any event, if this seems worth discussing further, I think work
could begin with agreeing on the specific (and probably rather narrow)
scope. I think we need, for example, to describe the criteria used to
decide what goes into the proposed addition manual.  We might also
want to create a "rubric" (simple rule, or very simple flow chart)
that helps us understand when a feature's documentation will be in the
Emacs manual, the elisp manual, or this new manual, and so on, until
the task beings to look ominously do-able or all volunteers are scared
off >:)

Prot, am I right that you (still, also) have energy for something like
this?  Other thoughts as you consider in the context of this thread?