commit: 4761fe1f5f5b9ba75abcf7f974e2ebf3f8966cec
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat Mar 23 21:30:07 2019 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sun Mar 24 15:56:04 2019 +0000
URL: https://gitweb.gentoo.org/proj/pms.git/commit/?id=4761fe1f
Refer to chapters as chapters.
Also rename label prefixes, "ch:" for chapters, "sec:" for sections,
as suggested by Michael Orlitzky.
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
appendices.tex | 2 +-
dependencies.tex | 2 +-
ebuild-env-vars.tex | 3 +--
ebuild-format.tex | 4 ++--
ebuild-functions.tex | 4 ++--
ebuild-vars.tex | 14 +++++++-------
eclasses.tex | 2 +-
glossary.tex | 4 ++--
introduction.tex | 4 ++--
metadata-cache.tex | 2 +-
profile-variables.tex | 6 +++---
profiles.tex | 4 ++--
tree-layout.tex | 38 +++++++++++++++++---------------------
13 files changed, 42 insertions(+), 47 deletions(-)
diff --git a/appendices.tex b/appendices.tex
index 434aa3f..ee537f7 100644
--- a/appendices.tex
+++ b/appendices.tex
@@ -1,5 +1,5 @@
\chapter{metadata.xml}
-\label{sec:metadata-xml}
+\label{ch:metadata-xml}
The \t{metadata.xml} file is used to contain extra package- or category-level
information beyond
what is stored in ebuild metadata. Its exact format is strictly beyond the
scope of this document,
diff --git a/dependencies.tex b/dependencies.tex
index 09becdb..89d1405 100644
--- a/dependencies.tex
+++ b/dependencies.tex
@@ -1,5 +1,5 @@
\chapter{Dependencies}
-\label{sec:dependencies}
+\label{ch:dependencies}
\section{Dependency Classes}
\label{sec:dependency-classes}
diff --git a/ebuild-env-vars.tex b/ebuild-env-vars.tex
index 1b53f20..56f959c 100644
--- a/ebuild-env-vars.tex
+++ b/ebuild-env-vars.tex
@@ -98,8 +98,7 @@ variable.
\t{WORKDIR} &
Ditto &
Yes &
- The full path to the ebuild's working directory, where all build data
should be contained.%
- \label{env-var-WORKDIR} \\
+ The full path to the ebuild's working directory, where all build data
should be contained. \\
\t{S} &
\t{src_*} &
Yes &
diff --git a/ebuild-format.tex b/ebuild-format.tex
index e7b8133..d53d773 100644
--- a/ebuild-format.tex
+++ b/ebuild-format.tex
@@ -1,5 +1,5 @@
\chapter{Ebuild File Format}
-\label{sec:ebuild-format}
+\label{ch:ebuild-format}
\featurelabel{bash-version} The ebuild file format is in its basic form a
subset of the format of
a bash script. The interpreter is assumed to be GNU bash, version as listed in
@@ -12,7 +12,7 @@ option of bash is set in the global scope of ebuilds. If set,
failed pattern mat
filename expansion result in an error when the ebuild is being sourced.
The file encoding must be UTF-8 with Unix-style newlines. When sourced, the
ebuild must define
-certain variables and functions (see sections~\ref{sec:ebuild-vars}
and~\ref{sec:ebuild-functions}
+certain variables and functions (see chapters~\ref{ch:ebuild-vars}
and~\ref{ch:ebuild-functions}
for specific information), and must not call any external programs, write
anything to standard
output or standard error, or modify the state of the system in any way.
diff --git a/ebuild-functions.tex b/ebuild-functions.tex
index 5c675ab..10247a8 100644
--- a/ebuild-functions.tex
+++ b/ebuild-functions.tex
@@ -1,5 +1,5 @@
\chapter{Ebuild-defined Functions}
-\label{sec:ebuild-functions}
+\label{ch:ebuild-functions}
\section{List of Functions}
@@ -7,7 +7,7 @@ The following is a list of functions that an ebuild, or eclass,
may define, and
by the package manager as part of the build and/or install process. In all
cases the package manager
must provide a default implementation of these functions; unless otherwise
stated this must be a
no-op. Most functions must assume only that they have write access to the
package's working
-directory (the \t{WORKDIR} environment variable; see
section~\ref{env-var-WORKDIR}), and the
+directory (the \t{WORKDIR} environment variable; see
section~\ref{sec:ebuild-env-vars}), and the
temporary directory \t{T}; exceptions are noted below. All functions may
assume that they have read
access to all system libraries, binaries and configuration files that are
accessible to normal
users.
diff --git a/ebuild-vars.tex b/ebuild-vars.tex
index c1b8b73..2ca30f2 100644
--- a/ebuild-vars.tex
+++ b/ebuild-vars.tex
@@ -1,7 +1,7 @@
\chapter{Ebuild-defined Variables}
-\label{sec:ebuild-vars}
+\label{ch:ebuild-vars}
-\note{This section describes variables that may or must be defined by ebuilds.
For variables that
+\note{This chapter describes variables that may or must be defined by ebuilds.
For variables that
are passed from the package manager to the ebuild, see
section~\ref{sec:ebuild-env-vars}.}
If any of these variables are set to invalid values, or if any of the
mandatory variables are
@@ -41,6 +41,7 @@ All ebuilds must define at least the following variables:
\end{description}
\section{Optional Ebuild-defined Variables}
+\label{sec:optional-vars}
Ebuilds may define any of the following variables:
@@ -56,7 +57,6 @@ Ebuilds may define any of the following variables:
\item[LICENSE] The package's license. Each text token must be a valid license
name, as per
section~\ref{sec:license-names}, and must correspond to a tree
``licenses/'' entry
(see section~\ref{sec:licenses-dir}). See
section~\ref{sec:dependency-spec} for full syntax.
- \label{ebuild-var-LICENSE}
\item[KEYWORDS] A whitespace separated list of keywords for the ebuild. Each
token must be a valid
keyword name, as per section~\ref{sec:keyword-names}. See
section~\ref{sec:keywords} for full
syntax.
@@ -80,12 +80,12 @@ Ebuilds may define any of the following variables:
any way.
\item[RESTRICT] Zero or more behaviour restrictions for this package. See
section~\ref{sec:restrict}
for value meanings and section~\ref{sec:dependency-spec} for full syntax.
-\item[DEPEND] See section~\ref{sec:dependencies}.
-\item[RDEPEND] See section~\ref{sec:dependencies}. For some EAPIs, \t{RDEPEND}
has special behaviour
+\item[DEPEND] See chapter~\ref{ch:dependencies}.
+\item[RDEPEND] See chapter~\ref{ch:dependencies}. For some EAPIs, \t{RDEPEND}
has special behaviour
for its value if unset and when used with an eclass. See
section~\ref{sec:rdepend-depend} for
details.
-\item[PDEPEND] See section~\ref{sec:dependencies}.
-\item[BDEPEND] See section~\ref{sec:dependencies}.
+\item[PDEPEND] See chapter~\ref{ch:dependencies}.
+\item[BDEPEND] See chapter~\ref{ch:dependencies}.
\end{description}
\ChangeWhenAddingAnEAPI{7}
diff --git a/eclasses.tex b/eclasses.tex
index 8305504..bf0007b 100644
--- a/eclasses.tex
+++ b/eclasses.tex
@@ -1,5 +1,5 @@
\chapter{Eclasses}
-\label{sec:eclasses}
+\label{ch:eclasses}
Eclasses serve to store common code that is used by more than one ebuild,
which greatly aids
maintainability and reduces the tree size. However, due to metadata cache
issues, care must be taken
diff --git a/glossary.tex b/glossary.tex
index 100c09a..5666aa2 100644
--- a/glossary.tex
+++ b/glossary.tex
@@ -1,7 +1,7 @@
\chapter{Glossary}
-\label{sec:glossary}
+\label{ch:glossary}
-This section contains explanations of some of the terms used in this document
whose meaning may not
+This chapter contains explanations of some of the terms used in this document
whose meaning may not
be immediately obvious.
\begin{description}
diff --git a/introduction.tex b/introduction.tex
index b5b63c6..8d1f793 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -7,7 +7,7 @@ well as certain aspects of package manager behaviour required
to support such a
This document is \e{not} designed to be an introduction to ebuild development.
Prior knowledge of
ebuild creation and an understanding of how the package management system
works is assumed; certain
-less familiar terms are explained in the Glossary in
chapter~\ref{sec:glossary}.
+less familiar terms are explained in the Glossary in chapter~\ref{ch:glossary}.
This document does not specify any user or package manager configuration
information.
@@ -60,7 +60,7 @@ applicable to tools or other applications that interact with
ebuilds or ebuild r
\section{Acknowledgements}
Thanks to Mike Kelly (package manager provided utilities,
section~\ref{sec:pkg-mgr-commands}),
-Danny van Dyk (ebuild functions, section~\ref{sec:ebuild-functions}), David
Leverton (various
+Danny van Dyk (ebuild functions, chapter~\ref{ch:ebuild-functions}), David
Leverton (various
sections), Petteri Räty (environment state,
section~\ref{sec:ebuild-env-state}), Michał Górny
(various sections), Andreas K. Hüttel (stable use masking,
section~\ref{sec:use-masking}),
Zac Medico (sub-slots, section~\ref{sec:mandatory-vars}) and James Le Cuirot
(build dependencies,
diff --git a/metadata-cache.tex b/metadata-cache.tex
index 3ac64a6..33574c4 100644
--- a/metadata-cache.tex
+++ b/metadata-cache.tex
@@ -1,5 +1,5 @@
\chapter{Metadata Cache}
-\label{sec:metadata-cache}
+\label{ch:metadata-cache}
\section{Directory Contents}
diff --git a/profile-variables.tex b/profile-variables.tex
index 6cd770c..f34c7c5 100644
--- a/profile-variables.tex
+++ b/profile-variables.tex
@@ -72,10 +72,10 @@ completely override those in parent profiles.
The following variables have specific meanings when set in profiles.
\begin{description}
\item[ARCH] The system's architecture. Must be a value listed in
\t{profiles/arch.list}; see
- section~\ref{arch.list} for more information. Must be equal to the primary
\t{KEYWORD} for this
- profile.
+ section~\ref{sec:profiles-dir} for more information. Must be equal to the
primary \t{KEYWORD}
+ for this profile.
\item[CONFIG_PROTECT, CONFIG_PROTECT_MASK] Contain whitespace-delimited lists
used to control the
- configuration file protection. Described more fully in
chapter~\ref{sec:config-protect}.
+ configuration file protection. Described more fully in
section~\ref{sec:config-protect}.
\item[USE] Defines the list of default USE flags for this profile. Flags may
be added or removed by
the user's configuration. \t{USE_EXPAND} values must not be specified in
this way.
\item[USE_EXPAND] Defines a list of variables which are to be treated
incrementally and whose
diff --git a/profiles.tex b/profiles.tex
index b423697..38e1be1 100644
--- a/profiles.tex
+++ b/profiles.tex
@@ -1,5 +1,5 @@
\chapter{Profiles}
-\label{sec:profiles}
+\label{ch:profiles}
\section{General Principles}
Generally, a profile defines information specific to a certain `type' of
system---it lies somewhere
@@ -111,7 +111,7 @@ installed unless unmasked by the user's configuration. In
some EAPIs, \t{package
directory instead of a regular file as per section~\ref{sec:line-stacking}.
Note that the \t{-spec} syntax can be used to remove a mask in a parent
profile, but not
-necessarily a global mask (from \t{profiles/package.mask},
section~\ref{profiles-package.mask}).
+necessarily a global mask (from \t{profiles/package.mask},
section~\ref{sec:profiles-dir}).
\note{Portage currently treats \t{profiles/package.mask} as being on the
leftmost branch of the
inherit tree when it comes to \t{-lines}. This behaviour may not be relied
upon.}
diff --git a/tree-layout.tex b/tree-layout.tex
index 9397e4b..0ff1ec9 100644
--- a/tree-layout.tex
+++ b/tree-layout.tex
@@ -24,12 +24,11 @@ An ebuild repository shall occupy one directory on disk,
with the following subd
\section{Category Directories}
\label{sec:category-dirs}
-Each category provided by the repository (see also: the
-\t{profiles/categories} file, section~\ref{profiles-categories}) shall
-be contained in one directory, whose name shall be that of the
-category. Each category directory shall contain:
+Each category provided by the repository (see also: the
\t{profiles/categories} file,
+section~\ref{sec:profiles-dir}) shall be contained in one directory, whose
name shall be that of
+the category. Each category directory shall contain:
\begin{compactitem}
-\item A \t{metadata.xml} file, as described in
appendix~\ref{sec:metadata-xml}\@. Optional.
+\item A \t{metadata.xml} file, as described in
appendix~\ref{ch:metadata-xml}\@. Optional.
\item Zero or more package directories, one for each package in the category,
as described in
section~\ref{sec:package-dirs}. The name of the package directory shall be
the corresponding
package name.
@@ -49,8 +48,8 @@ a package manager may treat an empty category as a category
that does not exist)
A package directory contains the following:
\begin{compactitem}
-\item Zero or more ebuilds. These are as described in
section~\ref{sec:ebuild-format} and others.
-\item A \t{metadata.xml} file, as described in
appendix~\ref{sec:metadata-xml}\@. Optional only for
+\item Zero or more ebuilds. These are as described in
chapter~\ref{ch:ebuild-format} and others.
+\item A \t{metadata.xml} file, as described in
appendix~\ref{ch:metadata-xml}\@. Optional only for
legacy support.
\item A \t{ChangeLog}, in a format determined by the provider of the
repository. Optional.
\item A \t{Manifest} file, whose format is described in~\cite{Glep44}. Can be
omitted if the file
@@ -73,12 +72,10 @@ this specification.
\section{The Profiles Directory}
\label{sec:profiles-dir}
-The profiles directory shall contain zero or more profile directories
-as described in section~\ref{sec:profiles}, as well as the following files
-and directories. In any line-based file, lines beginning with a \#
-character are treated as comments, whilst blank lines are ignored. All
-contents of this directory, with the exception of \t{repo_name}, are
-optional.
+The profiles directory shall contain zero or more profile directories as
described in
+chapter~\ref{ch:profiles}, as well as the following files and directories. In
any line-based file,
+lines beginning with a \# character are treated as comments, whilst blank
lines are ignored.
+All contents of this directory, with the exception of \t{repo_name}, are
optional.
The profiles directory may contain an \t{eapi} file. This file, if it exists,
must contain a single
line with the name of an EAPI\@. This specifies the EAPI to use when handling
the profiles
@@ -92,10 +89,9 @@ Other files not described by this specification may exist,
but may not be relied
manager must ignore any files in this directory that it does not recognise.
\begin{description}
-\item[arch.list] \label{arch.list} Contains a list, one entry per line, of
permissible values for
- the \t{ARCH} variable, and hence permissible keywords for packages in this
repository.
-\item[categories] \label{profiles-categories} Contains a list, one entry per
line, of categories
- provided by this repository.
+\item[arch.list] Contains a list, one entry per line, of permissible values
for the \t{ARCH}
+ variable, and hence permissible keywords for packages in this repository.
+\item[categories] Contains a list, one entry per line, of categories provided
by this repository.
\item[eapi] See above.
\item[info_pkgs] Contains a list, one entry per line, of qualified package
names. Any package
matching one of these is to be listed when a package manager displays a
`system information'
@@ -103,7 +99,7 @@ manager must ignore any files in this directory that it does
not recognise.
\item[info_vars] Contains a list, one entry per line, of profile,
configuration, and environment
variables which are considered to be of interest. The value of each of
these variables may be
shown when the package manager displays a `system information' listing.
-\item[package.mask] \label{profiles-package.mask}
+\item[package.mask]
Contains a list, one entry per line, of package dependency specifications
(using the directory's
EAPI). Any package version matching one of these is considered to be
masked, and will not be
installed regardless of profile unless it is unmasked by the user
configuration.
@@ -234,14 +230,14 @@ that slot move in the future.
The \t{licenses} directory shall contain copies of the licenses used by
packages in the
repository. Each file will be named according to the name used in the
\t{LICENSE} variable as
-described in section~\ref{ebuild-var-LICENSE}, and will contain the complete
text of the license in
+described in section~\ref{sec:optional-vars}, and will contain the complete
text of the license in
human-readable form. Plain text format is strongly preferred but not required.
\section{The Eclass Directory}
\label{sec:eclass-dir}
The \t{eclass} directory shall contain copies of the eclasses provided by this
repository. The
-format of these files is described in section~\ref{sec:eclasses}. It may also
contain, in their own
+format of these files is described in chapter~\ref{ch:eclasses}. It may also
contain, in their own
directory, support files needed by these eclasses.
\section{The Metadata Directory}
@@ -255,7 +251,7 @@ various XML files used in the repository, and repository
timestamps.
\subsection{The metadata cache}
The \t{metadata/cache} directory may contain a cached form of all important
ebuild metadata
-variables. The contents of this directory are described in
chapter~\ref{sec:metadata-cache}.
+variables. The contents of this directory are described in
chapter~\ref{ch:metadata-cache}.
% vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :
