bug#50825: master 44dbc11: Note that the Packaging sub-nodes are mostly for maintainers

[Stefan Kangas]

larsi@gnus.org (Lars Ingebrigtsen) writes:

> branch: master
> commit 44dbc11ff7bdccc8af2cdd311e6ebacfef2c43a7
> Author: Lars Ingebrigtsen <larsi@gnus.org>
> Commit: Lars Ingebrigtsen <larsi@gnus.org>
>
>     Note that the Packaging sub-nodes are mostly for maintainers
>
>     * doc/lispref/package.texi (Packaging): Note that the information
>     is mostly for ELPA maintainers (bug#50825).
> ---
>  doc/lispref/package.texi | 5 +++++
>  1 file changed, 5 insertions(+)
>
> diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi
> index 9c033fe..aeb455b 100644
> --- a/doc/lispref/package.texi
> +++ b/doc/lispref/package.texi
> @@ -17,6 +17,11 @@ put it in a @dfn{package archive} for others to download.
>  @xref{Packages,,, emacs, The GNU Emacs Manual}, for a description of
>  user-level features of the packaging system.
>
> +  These sections are mostly directed towards package archive
> +maintainers---much of this information is not relevant for package
> +authors (i.e., people who write code that will be distributed via
> +these archives).
> +
>  @menu
>  * Packaging Basics::        The basic concepts of Emacs Lisp packages.
>  * Simple Packages::         How to package a single .el file.

If this entire section is only relevant for package archive maintainers,
I think it should be wrapped in "@ifnottex" so it's excluded from the
printed manual.

But it seems to me that, while of the information indeed almost only
relevant for package maintainers, at least some part of it is useful for
package developers.  Do you agree?  See for example this paragraph in
(info "(elisp) Packaging Basics").

       Installing a package, either via the command ‘package-install-file’,
    or via the Package Menu, creates a subdirectory of ‘package-user-dir’
    named ‘NAME-VERSION’, where NAME is the package’s name and VERSION its
    version (e.g., ‘~/.emacs.d/elpa/auctex-11.86/’).

And then it repeats some stuff about `package-activate-all' that is
presumably already said in the user manual.

See also (info "(elisp) Simple Packages").

Perhaps we should think about it a bit more and make it more clear who
this documentation is intended for?  Once we know that, it should be
easier to make any necessary changes.

For example, if this is indeed all mixed up, could we split this up into
two subchapters or something?  In the more user-oriented section, we
could skip many of the more low-level details and just focus on: here's
what you need to do to produce a valid package.  Or perhaps that should
be documented by the package archives themselves?  Or is that in the
user manual?  Etc.