aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKylie McClain <kylie@somas.is>2020-07-07 09:34:00 -0400
committerKylie McClain <kylie@somas.is>2020-07-07 09:34:00 -0400
commitbc7a4da7bee4556eaf56165f1946d49d4358a45a (patch)
tree69254f58dc06cf8f646ac895d0bdd8a1e7976525
parent0a26ebe23943048f7bc6781e02e9402f5f07d1fe (diff)
downloadpraxis-bc7a4da7bee4556eaf56165f1946d49d4358a45a.tar.gz
praxis-bc7a4da7bee4556eaf56165f1946d49d4358a45a.tar.xz
praxis-bc7a4da7bee4556eaf56165f1946d49d4358a45a.zip
doc: regenerate manpages and README
-rw-r--r--README51
-rw-r--r--praxis.790
-rw-r--r--theory-construct-action.18
-rw-r--r--theory-construct-metadata.18
-rw-r--r--theory.5239
5 files changed, 192 insertions, 204 deletions
diff --git a/README b/README
index dbaaf48..bb8b05d 100644
--- a/README
+++ b/README
@@ -17,12 +17,14 @@ PHILOSOPHY
providing a lot of useful functionality for developers, metadata
consumers, and users.
- No code evaluation is used at any point. All code is generated purely
- by following hierarchies of inheritance for actions (build scripts) and
- metadata. Concepts like envdirs
- <https://skarnet.org/software/s6/s6-envdir.html> are used to
- additionally ease the amount of parsing that must be done to files in
- order to construct metadata for packages, repositories, and libraries.
+ No code evaluation is used, up until the actual building of packages.
+ All code is generated purely by following hierarchies of inheritance
+ for actions and metadata.
+
+ Concepts like envdirs <https://skarnet.org/software/s6/s6-envdir.html>
+ are used to additionally ease the amount of parsing that must be done
+ to files in order to construct metadata for packages, repositories, and
+ libraries.
Furthermore, another goal is ensuring that it should be possible to get
metadata from packages without having to call out to a shell running
@@ -33,9 +35,14 @@ PHILOSOPHY
other than running the actual actions that build a package.
DEPENDENCIES
+ • A POSIX-compliant shell: on Mutiny this is oksh(1)
+ <https://github.com/ibara/oksh>, but it is written with intent that
+ anything vaguely POSIX compliant should function properly.
+
• idioms <https://git.mutiny.red/mutiny/idioms>
- • A POSIX-compliant shell
+ • Used in lieu of implementing a bunch of small flow functions
+ into the package API.
• s6-portable-utils <https://skarnet.org/software/s6-portable-utils>
@@ -60,15 +67,15 @@ ROADMAP
• Tests
- • Build theory construction utilities
+ • Build theory utilities
- • theory-action - resolve and print all action (build script)
- parts of a theory.
+ • theory-resolve-action - resolve and print all action (build
+ script) parts of a theory.
• Tests
- • theory-metadata - resolve and print all metadata parts of a
- theory.
+ • theory-resolve-metadata - resolve and print all metadata parts
+ of a theory.
• Tests
@@ -90,6 +97,10 @@ ROADMAP
• See the first open question above to understand my
anxieties with this format.
+ • pkg-build - run each phase of a package script
+
+ • Tests
+
WISHLIST
• Multiple repositories
@@ -97,7 +108,7 @@ WISHLIST
• Priority levels
- • ::mutiny is the most important repository.
+ • ::primary is the most important repository.
• Other repositories should always be able to depend on
libraries in repositories that are have a higher priority.
@@ -139,18 +150,6 @@ WISHLIST
mpd
passage
-GLOSSARY
- actions
- The actual executable code used to build a package.
-
- theory
-
- 1. The package API. See theory(5).
-
- 2. A directory containing the data used to build a package. A
- directory contains a package if it has either an action, or a
- library (which creates actions).
-
ETYMOLOGY
Named as such to conform with the rest of the Mutiny naming scheme.
"Praxis," the word, means in the original Greek, "action." Packages are
@@ -179,4 +178,4 @@ LICENSE
-Mutiny 2020-07-04 PRAXIS(7)
+Mutiny 2020-07-07 PRAXIS(7)
diff --git a/praxis.7 b/praxis.7
index ec39078..466ef5c 100644
--- a/praxis.7
+++ b/praxis.7
@@ -2,12 +2,12 @@
.\" Title: praxis
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.10
-.\" Date: 2020-07-04
+.\" Date: 2020-07-07
.\" Manual: Mutineer's Guide - praxis
.\" Source: Mutiny
.\" Language: English
.\"
-.TH "PRAXIS" "7" "2020-07-04" "Mutiny" "Mutineer\(aqs Guide \- praxis"
+.TH "PRAXIS" "7" "2020-07-07" "Mutiny" "Mutineer\(aqs Guide \- praxis"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -39,8 +39,9 @@ thing, so as to ease frontend development and more importantly, to make the surf
very small. With this design in mind, \fBpraxis\fP can be fast and very compact, while providing a lot
of useful functionality for developers, metadata consumers, and users.
.sp
-No code evaluation is used at any point. All code is generated purely by following hierarchies of
-inheritance for actions (build scripts) and metadata.
+No code evaluation is used, up until the actual building of packages.
+All code is generated purely by following hierarchies of inheritance for actions and metadata.
+.sp
Concepts like \c
.URL "https://skarnet.org/software/s6/s6\-envdir.html" "envdirs" " "
are used to additionally ease
@@ -62,7 +63,10 @@ require a shell parser for anything other than running the actual actions that b
. sp -1
. IP \(bu 2.3
.\}
-.URL "https://git.mutiny.red/mutiny/idioms" "\f(CRidioms\fP" ""
+A POSIX\-compliant shell: on Mutiny this is \c
+.URL "https://github.com/ibara/oksh" "oksh(1)" ","
+but it is
+written with intent that anything vaguely POSIX compliant should function properly.
.RE
.sp
.RS 4
@@ -73,7 +77,18 @@ require a shell parser for anything other than running the actual actions that b
. sp -1
. IP \(bu 2.3
.\}
-A POSIX\-compliant shell
+.URL "https://git.mutiny.red/mutiny/idioms" "\f(CRidioms\fP" ""
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Used in lieu of implementing a bunch of small flow functions into the package API.
+.RE
.RE
.sp
.RS 4
@@ -184,7 +199,7 @@ Tests
. sp -1
. IP \(bu 2.3
.\}
-Build theory construction utilities
+Build theory utilities
.sp
.RS 4
.ie n \{\
@@ -194,7 +209,7 @@ Build theory construction utilities
. sp -1
. IP \(bu 2.3
.\}
-\f(CRtheory\-action\fP \- resolve and print all action (build script) parts of a theory.
+\f(CRtheory\-resolve\-action\fP \- resolve and print all action (build script) parts of a theory.
.sp
.RS 4
.ie n \{\
@@ -216,7 +231,7 @@ Tests
. sp -1
. IP \(bu 2.3
.\}
-\f(CRtheory\-metadata\fP \- resolve and print all metadata parts of a theory.
+\f(CRtheory\-resolve\-metadata\fP \- resolve and print all metadata parts of a theory.
.sp
.RS 4
.ie n \{\
@@ -298,6 +313,28 @@ Tests
See the first open question above to understand my anxieties with this format.
.RE
.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+\f(CRpkg\-build\fP \- run each phase of a package script
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+Tests
+.RE
+.RE
.RE
.SH "WISHLIST"
.sp
@@ -340,7 +377,7 @@ Priority levels
. sp -1
. IP \(bu 2.3
.\}
-\f(CR::mutiny\fP is the most important repository.
+\f(CR::primary\fP is the most important repository.
.RE
.sp
.RS 4
@@ -434,39 +471,6 @@ mpd
passage
.fi
.if n .RE
-.SH "GLOSSARY"
-.sp
-actions
-.RS 4
-The actual executable code used to build a package.
-.RE
-.sp
-theory
-.RS 4
-.sp
-.RS 4
-.ie n \{\
-\h'-04' 1.\h'+01'\c
-.\}
-.el \{\
-. sp -1
-. IP " 1." 4.2
-.\}
-The package API. See theory(5).
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04' 2.\h'+01'\c
-.\}
-.el \{\
-. sp -1
-. IP " 2." 4.2
-.\}
-A directory containing the data used to build a package. A directory contains a package if it
-has either an action, or a library (which creates actions).
-.RE
-.RE
.SH "ETYMOLOGY"
.sp
Named as such to conform with the rest of the Mutiny naming scheme. "Praxis," the word, means in the
diff --git a/theory-construct-action.1 b/theory-construct-action.1
index 997dbbe..69865e7 100644
--- a/theory-construct-action.1
+++ b/theory-construct-action.1
@@ -1,13 +1,13 @@
'\" t
-.\" Title: theory-action
+.\" Title: theory-construct-action
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.10
-.\" Date: 2020-06-29
+.\" Date: 2020-07-07
.\" Manual: Mutineer's Guide - praxis
.\" Source: Mutiny
.\" Language: English
.\"
-.TH "THEORY\-ACTION" "1" "2020-06-29" "Mutiny" "Mutineer\(aqs Guide \- praxis"
+.TH "THEORY\-CONSTRUCT\-ACTION" "1" "2020-07-07" "Mutiny" "Mutineer\(aqs Guide \- praxis"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -28,7 +28,7 @@
. LINKSTYLE blue R < >
.\}
.SH "NAME"
-theory\-action \- resolve dependencies of a theory and print all action parts
+theory\-construct\-action \- resolve dependencies of a theory and print all action parts
.SH "DESCRIPTION"
.sp
TODO
diff --git a/theory-construct-metadata.1 b/theory-construct-metadata.1
index 493c436..cf8373f 100644
--- a/theory-construct-metadata.1
+++ b/theory-construct-metadata.1
@@ -1,13 +1,13 @@
'\" t
-.\" Title: theory-metadata
+.\" Title: theory-construct-metadata
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.10
-.\" Date: 2020-06-29
+.\" Date: 2020-07-07
.\" Manual: Mutineer's Guide - praxis
.\" Source: Mutiny
.\" Language: English
.\"
-.TH "THEORY\-METADATA" "1" "2020-06-29" "Mutiny" "Mutineer\(aqs Guide \- praxis"
+.TH "THEORY\-CONSTRUCT\-METADATA" "1" "2020-07-07" "Mutiny" "Mutineer\(aqs Guide \- praxis"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -28,7 +28,7 @@
. LINKSTYLE blue R < >
.\}
.SH "NAME"
-theory\-metadata \- print all metadata of a theory
+theory\-construct\-metadata \- print all metadata of a theory
.SH "DESCRIPTION"
.sp
TODO
diff --git a/theory.5 b/theory.5
index f641814..2dc29c3 100644
--- a/theory.5
+++ b/theory.5
@@ -2,12 +2,12 @@
.\" Title: theory
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.10
-.\" Date: 2020-07-04
+.\" Date: 2020-07-07
.\" Manual: Mutineer's Guide - praxis
.\" Source: Mutiny
.\" Language: English
.\"
-.TH "THEORY" "5" "2020-07-04" "Mutiny" "Mutineer\(aqs Guide \- praxis"
+.TH "THEORY" "5" "2020-07-07" "Mutiny" "Mutineer\(aqs Guide \- praxis"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -32,17 +32,17 @@ theory \- package API used by Mutiny
.SH "SYNOPSIS"
.sp
This document aims to explain the API available for writing packages for Mutiny. This should be
-considered the definitive document to consult when writing packages, or when developing package
-managers.
+considered the definitive document to consult when writing packages, libraries, package managers,
+or anything that consumes the data.
.SH "REPOSITORIES"
.sp
Package managers \fBmust\fP support multiple repositories. The internal prioritization of these
-repositories is dictated by the [priority]. User\-facing sort (ex. when listing repositories
-installed on the system) is not defined.
+repositories is dictated by the priority. User\-facing sort (ex. when listing
+repositories installed on the system) is not defined, but praxis(7) sorts them alphabetically.
.sp
Repository names are alphanumeric plus \f(CR_\fP and \f(CR\-\fP.
.sp
-The file and directory layout of a valid repository is as follows, \fIitalicized\fP items representing
+The file and directory layout of a repository is as follows, \fIitalicized\fP items representing
optional items, anything else required:
.sp
.RS 4
@@ -53,7 +53,7 @@ optional items, anything else required:
. sp -1
. IP \(bu 2.3
.\}
-<repository name>/
+\f(CR<repository>\fP/
.sp
.RS 4
.ie n \{\
@@ -63,7 +63,8 @@ optional items, anything else required:
. sp -1
. IP \(bu 2.3
.\}
-metadata/
+\fIdependencies\fP
+.RE
.sp
.RS 4
.ie n \{\
@@ -73,8 +74,7 @@ metadata/
. sp -1
. IP \(bu 2.3
.\}
-\fIdependencies\fP
-.RE
+metadata/
.sp
.RS 4
.ie n \{\
@@ -84,7 +84,7 @@ metadata/
. sp -1
. IP \(bu 2.3
.\}
-\fIsummary\fP
+priority
.RE
.sp
.RS 4
@@ -95,7 +95,7 @@ metadata/
. sp -1
. IP \(bu 2.3
.\}
-priority
+\fIsummary\fP
.RE
.RE
.sp
@@ -117,7 +117,7 @@ priority
. sp -1
. IP \(bu 2.3
.\}
-library1
+action
.RE
.RE
.sp
@@ -139,29 +139,7 @@ packages/
. sp -1
. IP \(bu 2.3
.\}
-openssh#1.2.3/ \- This directory\(cqs path is exported as \f(CR${PKGDIR}\fP.
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-. sp -1
-. IP \(bu 2.3
-.\}
-\fIdependencies\fP
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-. sp -1
-. IP \(bu 2.3
-.\}
-\fIlibraries\fP \- Libraries to be used for constructing the package\(cqs theory.
-.RE
+openssh#1.2.3/
.sp
.RS 4
.ie n \{\
@@ -171,7 +149,7 @@ openssh#1.2.3/ \- This directory\(cqs path is exported as \f(CR${PKGDIR}\fP.
. sp -1
. IP \(bu 2.3
.\}
-\fIsha256sum\fP
+action
.RE
.sp
.RS 4
@@ -182,7 +160,7 @@ openssh#1.2.3/ \- This directory\(cqs path is exported as \f(CR${PKGDIR}\fP.
. sp -1
. IP \(bu 2.3
.\}
-\fIsources\fP
+\fIdependencies\fP
.RE
.sp
.RS 4
@@ -193,7 +171,7 @@ openssh#1.2.3/ \- This directory\(cqs path is exported as \f(CR${PKGDIR}\fP.
. sp -1
. IP \(bu 2.3
.\}
-theory0
+\fIlibraries\fP \- Libraries to be combined together to create the package.
.RE
.sp
.RS 4
@@ -276,33 +254,15 @@ after importing all libraries.
.RE
.RE
.RE
-.SS "Repository metadata"
+.SS "Metadata"
.sp
Repositories \fBmust\fP have a directory in their root named \f(CRmetadata\fP.
-.SS "Dependencies (optional)"
-.sp
-Repositories \fBmay\fP contain a file in \f(CRmetadata\fP, named \f(CRdependencies\fP. The \f(CRdependencies\fP file \fBmust\fP
-contain a single repository on each line. Repositories listed in this file are repositories which the
-package manager \fBmust\fP have installed prior to the installation of the repository depending on them.
-The order in which they are listed is unspecified.
-.sp
-Any repository listed will have its \f(CRlibraries\fP directory searched when parsing package files; the order
-in which they are searched is determined by the \f(CRpriority\fP value of the repository.
-.sp
-Do not add repositories to \f(CRdependencies\fP simply because a package in your repository depends on something
-in another repository. The package manager \fBshall\fP deal with determining what repository needs to be
-installed to satisfy a dependency through usage of the \c
-.URL "#universe" "\f(CRuniverse\fP meta\-repository" "."
-.SS "Summary"
-.sp
-Repositories \fBshould\fP have a summary. The summary should be a short, one\-line blurb describing the
-repository\(cqs contents or objective.
.SS "Priority"
.sp
Repositories \fBmust\fP have a file within \f(CRmetadata\fP named \f(CRpriority\fP.
The \f(CRpriority\fP file \fBmust\fP contain a non\-negative integer.
.sp
-The intended scheme goes like so:
+There \fIare\fP meanings that go with each number, and they go like so:
.sp
.RS 4
.ie n \{\
@@ -349,16 +309,54 @@ First\-party tertiary repository. (ex. A distribution developer\(cqs repository.
.\}
Third\-party repository. (ex. A distribution user\(cqs repository.)
.RE
+.SS "Summary"
+.sp
+Repositories \fBshould\fP have a summary. The contents should be a short, one\-line blurb, describing
+the repository\(cqs contents, objective, or theme.
+.sp
+For example, in listings, a package manager could show the summary next to the repository\(cqs name.
+.SS "Dependencies (optional)"
+.sp
+Repositories can optionally have a file in \f(CRmetadata\fP, named \f(CRdependencies\fP.
+.sp
+The file should be a list of the names of repositories on each line. Repositories listed in this
+file are dependent repositories, with which the package manager \fBmust\fP have installed prior to the
+installation of the repository declaring these dependencies. The order in which they are listed in
+the file is unimportant.
+.sp
+Any repository listed will have its \f(CRlibraries\fP directory searched when parsing package files; the order
+in which they are searched is determined by the \f(CRpriority\fP value of the repository.
+.sp
+Do not add repositories to \f(CRdependencies\fP simply because a package in your repository depends on something
+in another repository. The package manager should deal with determining what repository needs to be
+installed to satisfy a dependency through usage of the \f(CRuniverse\fP meta\-repository.
.SS "Packages"
.sp
-Repositories \fBshould\fP contain a directory named \f(CRpackages\fP; if they do not, package managers \fBmay\fP
+Repositories should contain a directory named \f(CRpackages\fP; if they do not, package managers can
ignore them entirely, as there\(cqs not much use to a repository with no package.
-.SS "Package specifications"
+.sp
+See the packages section for details about what goes on within.
+.SH "PACKAGES"
+.sp
+This term can be a bit overloaded. It\(cqs just too useful of a term.
+When I say package, I mean "a collection containing instructions to build a piece of software".
+.sp
+In theory(5), a package means a directory containing an action, libraries, or both. If it\(cqs just a
+directory with metadata, it is not a package, because there\(cqs no actual build script. And, in fact,
+if you depend on libraries that also don\(cqt provide any action file, your directory is not a package.
+.sp
+Why so lenient? Because a package can add actions on top of the actions declared in the libraries it
+uses, and same with metadata. It is a hierarchy of inheritance. It all gets combined to create a
+self\-sufficient script, which is what\(cqs actually used when building.
+.sp
+Unlike other, simpler formats which provide simpler build scripts, this allows for reducing code
+duplication in a tree of packages.
+.SS "Specifications"
.sp
Package specifications (informally referred to as "specs") are strings which describe a package.
.sp
-Specifications take on multiple permutations, because they are made up of four different parts, of
-which only the name is required.
+Specifications take on multiple permutations, because they are made up of four different parts,
+of which only the name is required.
.sp
Given the fully\-qualified spec \f(CRpackage#1.0::repository\fP...
.sp
@@ -437,74 +435,28 @@ Repository is alphanumeric plus \f(CR_\fP, and \f(CR\-\fP. It must start with an
All parts of a package spec are case\-sensitive.
.SS "Disambiguation"
.sp
-The only strictly \fBrequired\fP part of a spec is the inclusion of the
-package name. If any other part other than the name is omitted, it will
-be disambiguated in order to determine what packages can satisfy the
-specification given.
+When used as user input, the only strictly \fBrequired\fP part of a spec is the inclusion of the package
+name. If any other part other than the name is omitted, it will be disambiguated in order to
+determine what packages can satisfy it.
.sp
-If more than one package matches a specification, the package manager
-\fBmay\fP prompt the user in some fashion to be more specific.
-.SS "Format"
+If more than one package matches a specification, the package manager \fBshould\fP prompt the user in
+some fashion to be more specific.
+.SS "Action"
.sp
-\f(CRtheory0\fP files and \f(CRlib0\fP files are effectively just shell scripts. Package managers \fBshould\fP
-avoid locking the user into any particular Bourne\-style shell implementation; as such, the format
-of these files should adhere to shell syntax as defined in
+\f(CRaction\fP files are really just shell scripts. These files should adhere to shell syntax as defined
+in \c
.URL "http://pubs.opengroup.org/onlinepubs/9699919799/" "POSIX 2016" "."
+.SH "BUILDING"
.sp
-That said, a few exceptions are made for functionality that is deemed too
-useful to be given up, and isn\(cqt yet specified in POSIX...
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-. sp -1
-. IP \(bu 2.3
-.\}
-Declaring arrays (\f(CRarray=( "foo" "bar" "baz" )\fP)
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-. sp -1
-. IP \(bu 2.3
-.\}
-Iterating through arrays (\f(CRfor item in "${array[@]}";do ... done\fP)
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-. sp -1
-. IP \(bu 2.3
-.\}
-Appending to arrays (\f(CRarray+=( "xyzzy" )\fP)
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-. sp -1
-. IP \(bu 2.3
-.\}
-Local\-scope variables (\f(CRlocal var="value"\fP)
-.RE
-.SH "BUILD ENVIRONMENT"
+This section is about the environment a package is built in.
.sp
When referring to a "build environment", this document is referring to the literal shell environment
which the shell process is running in. This means it consists of things such as variables,
-functions, and current working directory.
+functions, and the current working directory.
.SS "Phases"
.sp
-Everything in this section is \fBrequired\fP of any package manager implementation.
+Everything in this section is \fBrequired\fP of any package manager implementation. If this isn\(cqt
+adhered to, we\(cqll have issues with some packages building in one implementation but not another.
.sp
"By default" refers to a package which does not define any phases or import any libraries which
define phases.
@@ -514,16 +466,16 @@ defined, regardless of if they have any function; if a phase listed here is not
the package manager, or the package (or a library used by the package), the package manager \fBmust\fP
error out and fail, because that is an invalid package.
.sp
-"Does nothing" would mean something like \f(CRpkg_init() { true; }\fP. "Not defined" would mean no
-definition of the function.
+"Does nothing" would mean something like \f(CRpkg_init() { true; }\fP.
+"Not defined" would mean no definition of the function.
(ex. Attempting to run function that is not defined would give an unknown command error)
.SS "\f(CRpkg_init()\fP"
.sp
This phase is ran when a build environment is created for a package building session. Normally
nothing is done, and this is a dummy function.
.sp
-Examples of other defintions could be creating a custom \f(CRPATH\fP and script wrappers to be used for
-build systems that are stubborn to cooperate with cross\-compilation.
+Examples of other definitions could be creating a custom \f(CRPATH\fP and script wrappers to be used for
+build systems that are too stubborn to cooperate with cross\-compilation.
.SS "\f(CRsrc_fetch()\fP"
.sp
\fBOnly ran during installation.\fP
@@ -625,6 +577,39 @@ are ran.
The directories in which a build is executed are undefined. However, it is a good idea to use
something located in a good location for temporary work. A directory in \f(CR/var/tmp\fP is a good idea;
\f(CR/tmp\fP, not so much, as build directories \fBshould\fP be allowed to persist for long periods of time.
+.SH "GLOSSARY"
+.sp
+actions
+.RS 4
+The actual executable code used to build a package.
+.RE
+.sp
+theory
+.RS 4
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 1.\h'+01'\c
+.\}
+.el \{\
+. sp -1
+. IP " 1." 4.2
+.\}
+The package API. You are reading the documentation for it right now.
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04' 2.\h'+01'\c
+.\}
+.el \{\
+. sp -1
+. IP " 2." 4.2
+.\}
+A directory containing the data used to build a package. A directory contains a package if it
+has either an action, or a library (which creates actions).
+.RE
+.RE
.SH "CONTRIBUTING"
.sp
The canonical URL of this repository is \c