[elpa] main e57178b913 2/2: * README: Copyedits.

[Stefan Kangas]

branch: main
commit e57178b9137b967935b99e27cb6567683ed1ac41
Author: Stefan Kangas <stefan@marxist.se>
Commit: Stefan Kangas <stefan@marxist.se>

    * README: Copyedits.
---
 README | 71 +++++++++++++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 51 insertions(+), 20 deletions(-)

diff --git a/README b/README
index 5bc5638342..d1e68a1406 100644
--- a/README
+++ b/README
@@ -1,5 +1,5 @@
 #+TITLE: GNU ELPA README
-#+DATE: 2020-11-28
+#+DATE: 2021-12-30
 
 Copyright (C) 2010-2021 Free Software Foundation, Inc. \\
 See the end of the file for license conditions.
@@ -13,32 +13,56 @@ both locations to avoid introducing additional differences. 
 This
 duplication will be removed eventually.
 #+END_COMMENT
 
-This branch contains auxiliary files for [[https://elpa.gnu.org/][GNU ELPA]].
+This repository contains the sources, deployment scripts, and
+auxiliary files for [[https://elpa.gnu.org/][GNU ELPA]].  GNU ELPA is a 
[[https://www.gnu.org/philosophy/free-sw.html][free software]] Emacs Lisp
+Package Archive (ELPA) with extensions to 
[[https://www.gnu.org/software/emacs/][GNU Emacs]].
 
-The sources are stashed in auxiliary branches,
-and the deployment scripts, are in the =elpa-admin= branch.
-The =Makefile= will automatically pull that last branch
-to populate the =admin= subdirectory, whose own makefile
-will in turn populate the =packages= subdirectories from
-the relevant sources.
+This file explains the repository layout, how to add and edit
+packages, and how to deploy the archive (either on =elpa.gnu.org=,
+or a local copy for testing purposes).
 
-This file explains the branch layout, how to add and edit packages,
-and how to deploy the archive (either on =elpa.gnu.org=, or a local copy
-for testing purposes).
+* Repository layout of elpa.git
 
+The layout of the =elpa.git= repository is as follows:
+
+- The =main= branch holds the list of specifications of the packages
+  included.  It does not hold the scripts to build them.
+
+- The copy of the code for a package =<pkg-name>= is not kept in
+  =main= but in a branch named =externals/<pkg-name>=.
+  Package branches are normally placed as git worktrees in the
+  subdirectory =packages/<pkg-name>= (see below).
+
+- The package archive deployment scripts are in the =elpa-admin=
+  branch.  This branch is normally put as a git worktree in the
+  =admin= subdirectory.
 
 * Getting the source
 
-Start with source that is cloned directly from Savannah.  See 
[[https://savannah.gnu.org/git/?group=emacs][the Savannah page]]
-and look for "ELPA".  Using a clone of a clone does not work.
+Start with source that is cloned directly from Savannah.  See 
[[https://savannah.gnu.org/git/?group=emacs][the
+Savannah page]] and look for "GNU ELPA".  Using a clone of a clone does
+not work.
+
+The =Makefile= in =main= will automatically pull the =elpa-admin=
+branch to populate the =admin= subdirectory.  This is done by:
 
-You must then do some setup:
 #+begin_src shell
    make setup
 #+end_src
 
-That leaves the =packages= directory empty; you must check out the
-ones you want.
+This will checkout the =elpa-admin= branch to the subdirectory
+=admin=.
+
+However, it leaves the =packages= directory empty; you must check out
+the ones you want.  The =Makefile= in the =admin= subdirectory is
+responsible for populating the =packages= subdirectories from the
+relevant sources.
+
+Note that this =Makefile= is symlinked to the root of the repository
+by the above =make setup= command.  This means that you can run
+targets directly from
+
+** Check out all packages
 
 If you wish to check out all the packages into the =packages=
 directory, you can run the command:
@@ -47,6 +71,8 @@ directory, you can run the command:
    make worktrees
 #+end_src
 
+** Check out specific package
+
 You can check out a specific package =<pkgname>= into the =packages=
 directory with this command:
 
@@ -54,6 +80,8 @@ directory with this command:
    make packages/<pkgname>
 #+end_src
 
+** Updating a package directory
+
 If you already have a =packages/<pkgname>= directory with a previous
 checkout, you can update it like this:
 
@@ -256,12 +284,14 @@ Delete all the files generated by =make 
packages/[PKGNAME]=.
 * Packages
 
 ** Contents of the =packages/= directory:
+
 This directory holds the package sources, with one subdirectory for
 each package.
 
 Each directory in here corresponds to a package.
 
-A nightly cron job refreshes the GNU ELPA archive from this repository.
+A nightly cron job on the server hosting =elpa.gnu.org= refreshes the
+GNU ELPA archive from this repository.
 
 This cron job only creates a new package when the "version" (as specified in
 the =Version:= header) of a package is modified.  This means that you can
@@ -381,7 +411,7 @@ and the web-pages from this source code:
   auto-generated from it.
 - Every package should have both a =Version:= /and/ a =Maintainer:=.
 - The =Version:= must be acceptable to =version-to-list=.
-- The =URL:= header can be used to specify the home page
+- The =URL:= header can be used to specify the website
   of the package, if it's maintained externally.
 - A =News:= section (or "NEWS" file) can/should be used to list the
   user-visible changes of each version.
@@ -418,8 +448,8 @@ The copy of the code is not kept in =main= but in the
 To add a new package, first add this =elpa.git= repository as a
 new remote in your existing repository.
 
-Then push a local branch to a
-new remote branch in =elpa.git=, named =externals/<pkgname>=.  For example:
+Then push a local branch to a new remote branch in =elpa.git=, named
+=externals/<pkgname>=.  For example:
 
 #+begin_src shell
    git push elpa <mybranch>:refs/heads/externals/<pkgname>
@@ -557,6 +587,7 @@ along with GNU Emacs.  If not, see 
<https://www.gnu.org/licenses/>.
 #+BEGIN_COMMENT
 Local variables:
 mode: org
+fill-column: 70
 paragraph-separate: "[         ]*$"
 time-stamp-pattern: "4/#\\+DATE: %Y-%02m-%02d$"
 end: