[emacs-pms] Package information on the Emacsmirror (epkgs)

[Jonas Bernoulli]

Hello

As I have mentioned I automatically extract information from packages
and make it available at https://github.com/emacsmirror/epkgs. I also
mentioned that I would like other people to use that information and
today Johan contacted my on github as he does intend to use it but
needs more information:

---

Every regular file in the repository contains information about a
particular revision of some package.

E.g. epkg/master/0.6.0 contains:

(:summary    "The stupid package tracker for Emacs"
 :created    "20100101"
 :updated    "20101214"
 :license    "GPL-3"
 :authors    (("Jonas Bernoulli" . "address@hidden"))
 :maintainer ("Jonas Bernoulli" . "address@hidden")
 :provided   (epkg epkg-ui)
 :required   ((("emacs" cl help-mode)
               ("listing" listing)
               ("magit" magit)
               ("vcomp" vcomp))
              (("oddmuse" oddmuse)
               ("yaoddmuse" yaoddmuse)))
 :keywords   ("git" "libraries" "packages")
 :homepage   "https://github.com/tarsius/epkg";
 :commentary "\
The stupid package tracker for Emacs.

       ,- going to be
       |
Epkg is a package manager for Emacs packages.  It makes heavy use of
Git - the stupid content tracker.  Packages are installed by cloning
the package's git repository from the Emacsmirror.
...")

Except for the following this is pretty self explanatory, I think:

(1) `:provided' is a list of provided features. If the package bundles
libraries from other packages then these features are not included
here, except when I am not aware that a library is actually from
another package because I do not mirror that package yet, and my
scripts therefor did not have a change of informing my about conflicts
yet. However any feature always only appears in `:provided' of one and
only one package.

(2) The car of `:required' is a list of the hard required packages,
the cadr is a list of soft required packages. The car of each entry is
the name of a package and the cdr is a list of features required from
that library. "emacs" stands for any package distributed with Emacs
(24.0.50 as of now). Even if a package is mirrored on the Emacsmirror,
if it is also part of Emacs then "emacs" is always used for now. This
will change but for this I first have to split Emacs into packages
(help welcome!).

The features required and provided by a package are extracted using
regular expression search and might not always be perfect.

All other information is extracted from the "main" file of the
package, for the package "foo" this normally is "foo.el". In cases
where no obvious main file exists I have just picked on. This is e.g.
the case when a package contains various related libraries that do not
depend on one another and can be used independently.

Also if the author of a package does not follow the header conventions
my scripts might not be able to extract any useful information.

---

The tree structure *currently* looks like this:

epkgs
|-- epkg
|   `-- master
|       |-- 0.6
|       `-- tip
|-- lacarte
|   `-- emacswiki
|       |-- 22.0.632
|       `-- tip
...

Here "master" and "emacswiki" are (the only) branches of the
respective packages on the Emacsmirror.  If a package has a "master"
branch this means that the package is mirrored from the version
control repository of (what I believe to be) upstream.  "emacswiki"
indicates that the package is mirrored from the Emacswiki - this might
be how upstream distributes the package or the file might have been
uploaded by someone else. "web-import" is similar to "master" but
indicates that the import is from a file or archive found on upstreams
page.  "manual-import" indicates that the package has been imported
once and from whatever source - in most cases because the package is
not available anymore or was only ever posted on gnu-emacs-sources,
but sometimes also because of technical problems.

Currently (virtually) every package on the Emacsmirror has only one
branch.  If a package is available from upstream but also from the
Emacswiki then the copy from the latter is not mirrored.  In the
future I might also mirror forks - the respective branches will be
named after the nickname of the person who maintains the fork or
something like that.

"tip" describes the tip/trunk/HEAD of the respective branch as found
on the Emacsmirror.

"0.6" describes a tagged (version control vise) release which my
script was able to parse.  It is always a version string even if the
tag is actually something like "v0.6" or "epkg-0.6".

When the branch was created on the mirror by importing from e.g. a
tarball or the Emacswiki then the tags are created by my import
scripts.  If upstream uses a vcs but doesn't tag releases in a way my
scripts understand then there is only "tip" (even if that information
could theoretically be extracted from the library header as for
packages from the Emacsmirror).

Currently there always is a "tip" file for each branch but I am
thinking about not providing that file if the tip of a branch is also
tagged.

---

Likewise I am thinking about changing the directory structure.  The
previous example would then become:

epkgs
|-- epkg
|   |-- master
|   `-- 0.6
|-- lacarte
|   |-- emacswiki
|   `-- 22.0.632
...

The current structure reflects the fact that I intended to support
versions from forks not only upstream in my own package manager.  But
it currently looks like I won't do this.  Instead I will only pull
tags from upstream and setup rules to ignore does from anywhere else.

---

Things are not set in stone yet.  So please if you intend to use the
epkgs please let me know what your needs are.

-- Jonas