[gentoo-pms] [PATCH v2] Refer to chapters as chapters.

[Ulrich Müller]

Date: Sat, 23 Mar 2019 22:30:07 +0100

Also rename label prefixes, "ch:" for chapters, "app:" for appendices,
as suggested by Michael Orlitzky.

Signed-off-by: Ulrich Müller <ulm@g.o>
---
>>>>> On Sun, 24 Mar 2019, Michael Orlitzky wrote:

> Please change those labels to e.g. "chap:ebuild-vars" in the process.
> Every "chapter" reference to a "sec" label looks like a bug to me.

Good idea, done.

> I don't know how everyone feels about additional TeX dependencies,
> but the cleveref package is designed to solve exactly this problem:

>   https://ctan.org/pkg/cleveref

> Instead of "chapter~\ref{chap:...}", cleveref lets you write only
> "\cref{chap:...}", and the correct word, capitalization, and
> non-breaking spaces are inserted automatically.

Too clever, for my taste. :-) It is the sort of over-engineering that
deteriorates readability of the LaTeX source.

Besides, cleveref would break HTML generation with TeX4ht.

 appendices.tex        |  2 +-
 dependencies.tex      |  2 +-
 ebuild-format.tex     |  4 ++--
 ebuild-functions.tex  |  2 +-
 ebuild-vars.tex       | 10 +++++-----
 eclasses.tex          |  2 +-
 glossary.tex          |  2 +-
 introduction.tex      |  4 ++--
 metadata-cache.tex    |  2 +-
 profile-variables.tex |  2 +-
 profiles.tex          |  2 +-
 tree-layout.tex       | 20 +++++++++-----------
 12 files changed, 26 insertions(+), 28 deletions(-)

diff --git a/appendices.tex b/appendices.tex
index 434aa3f..7e849f2 100644
--- a/appendices.tex
+++ b/appendices.tex
@@ -1,5 +1,5 @@
 \chapter{metadata.xml}
-\label{sec:metadata-xml}
+\label{app: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 7ce9860..07a990f 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-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..f5afacb 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}
 
diff --git a/ebuild-vars.tex b/ebuild-vars.tex
index 47720bb..a8aa528 100644
--- a/ebuild-vars.tex
+++ b/ebuild-vars.tex
@@ -1,5 +1,5 @@
 \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
 are passed from the package manager to the ebuild, see section~\ref{sec:ebuild-env-vars}.}
@@ -79,12 +79,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..60f6def 100644
--- a/glossary.tex
+++ b/glossary.tex
@@ -1,5 +1,5 @@
 \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
 be immediately obvious.
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..86d60d9 100644
--- a/profile-variables.tex
+++ b/profile-variables.tex
@@ -75,7 +75,7 @@ The following variables have specific meanings when set in profiles.
     section~\ref{arch.list} 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..88bf08b 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
diff --git a/tree-layout.tex b/tree-layout.tex
index 9397e4b..9a5c8b4 100644
--- a/tree-layout.tex
+++ b/tree-layout.tex
@@ -29,7 +29,7 @@ Each category provided by the repository (see also: the
 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{app: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 +49,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{app: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 +73,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
@@ -241,7 +239,7 @@ human-readable form. Plain text format is strongly preferred but not required.
 \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 +253,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 :
 
-- 
2.21.0