From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <gentoo-commits+bounces-1079995-garchives=archives.gentoo.org@lists.gentoo.org>
Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80])
(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
(No client certificate requested)
by finch.gentoo.org (Postfix) with ESMTPS id 7B4D7138335
for <garchives@archives.gentoo.org>; Thu, 28 Mar 2019 07:23:07 +0000 (UTC)
Received: from pigeon.gentoo.org (localhost [127.0.0.1])
by pigeon.gentoo.org (Postfix) with SMTP id 43950E0B4C;
Thu, 28 Mar 2019 07:23:06 +0000 (UTC)
Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183])
(using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits))
(No client certificate requested)
by pigeon.gentoo.org (Postfix) with ESMTPS id EF555E0B58
for <gentoo-commits@lists.gentoo.org>; Thu, 28 Mar 2019 07:23:05 +0000 (UTC)
Received: from oystercatcher.gentoo.org (unknown [IPv6:2a01:4f8:202:4333:225:90ff:fed9:fc84])
(using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits))
(No client certificate requested)
by smtp.gentoo.org (Postfix) with ESMTPS id 9C63D335CEF
for <gentoo-commits@lists.gentoo.org>; Thu, 28 Mar 2019 07:23:04 +0000 (UTC)
Received: from localhost.localdomain (localhost [IPv6:::1])
by oystercatcher.gentoo.org (Postfix) with ESMTP id AF58A57E
for <gentoo-commits@lists.gentoo.org>; Thu, 28 Mar 2019 07:23:02 +0000 (UTC)
From: "Ulrich Müller" <ulm@gentoo.org>
To: gentoo-commits@lists.gentoo.org
Content-Transfer-Encoding: 8bit
Content-type: text/plain; charset=UTF-8
Reply-To: gentoo-dev@lists.gentoo.org, "Ulrich Müller" <ulm@gentoo.org>
Message-ID: <1553442964.4761fe1f5f5b9ba75abcf7f974e2ebf3f8966cec.ulm@gentoo>
Subject: [gentoo-commits] proj/pms:master commit in: /
X-VCS-Repository: proj/pms
X-VCS-Files: appendices.tex dependencies.tex ebuild-env-vars.tex ebuild-format.tex ebuild-functions.tex ebuild-vars.tex eclasses.tex glossary.tex introduction.tex metadata-cache.tex profile-variables.tex profiles.tex tree-layout.tex
X-VCS-Directories: /
X-VCS-Committer: ulm
X-VCS-Committer-Name: Ulrich Müller
X-VCS-Revision: 4761fe1f5f5b9ba75abcf7f974e2ebf3f8966cec
X-VCS-Branch: master
Date: Thu, 28 Mar 2019 07:23:02 +0000 (UTC)
Precedence: bulk
List-Post: <mailto:gentoo-commits@lists.gentoo.org>
List-Help: <mailto:gentoo-commits+help@lists.gentoo.org>
List-Unsubscribe: <mailto:gentoo-commits+unsubscribe@lists.gentoo.org>
List-Subscribe: <mailto:gentoo-commits+subscribe@lists.gentoo.org>
List-Id: Gentoo Linux mail <gentoo-commits.gentoo.org>
X-BeenThere: gentoo-commits@lists.gentoo.org
X-Auto-Response-Suppress: DR, RN, NRN, OOF, AutoReply
X-Archives-Salt: 3c210f38-5cfc-4bf6-8288-45d65b5c7d6b
X-Archives-Hash: 1579df33671967464958d6fd905f1dc4
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 :