Re: [gentoo-pms] Title Case versus sentence case

[Ulrich Mueller]

>>>>> On Wed, 12 Apr 2017, Ulrich Mueller wrote:

> Fine with me. We start with \chapter though, so \subsection is at
> level 3 already (and should be the first level with sentence case
> if we follow APA).

Patch is below.

Ulrich


From ce8990bdcf56da5a9360cc273e4f8661af5497a6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ulrich=20M=C3=BCller?= <ulm@g.o>
Date: Fri, 14 Apr 2017 10:21:27 +0200
Subject: [PATCH] More consistent capitalisation of headings.

Use title case for first and second level headings (i.e., \chapter
and \section in the main text, \section and \subsection in the EAPI
cheat sheet); use sentence case everywhere else.

https://archives.gentoo.org/gentoo-pms/message/cef75e03f1a3b692281a5b79065dc2b6
---
 appendices.tex            |  2 +-
 dependencies.tex          | 20 ++++++++++----------
 ebuild-env-commands.tex   |  4 ++--
 ebuild-env-invariancy.tex |  2 +-
 ebuild-env-state.tex      |  2 +-
 ebuild-env-vars.tex       |  6 +++---
 ebuild-functions.tex      |  4 ++--
 ebuild-vars.tex           |  4 ++--
 eclasses.tex              |  2 +-
 merge.tex                 |  6 +++---
 names.tex                 | 18 +++++++++---------
 pkg-mgr-commands.tex      | 10 +++++-----
 profile-variables.tex     |  4 ++--
 profiles.tex              |  4 ++--
 14 files changed, 44 insertions(+), 44 deletions(-)

diff --git a/appendices.tex b/appendices.tex
index 99429ec..1b70568 100644
--- a/appendices.tex
+++ b/appendices.tex
@@ -30,7 +30,7 @@ The items described in this chapter are included for information only. Unless ot
 they were deprecated or abandoned long before \t{EAPI} was introduced. Ebuilds must not use these
 features, and package managers should not be changed to support them.
 
-\section{If-else use blocks}
+\section{If-else USE Blocks}
 
 Historically, Portage supported if-else use conditionals, as shown by
 listing~\ref{lst:if-else-use-listing}. The block before the colon would be taken if the condition
diff --git a/dependencies.tex b/dependencies.tex
index 9917bc4..ee4339b 100644
--- a/dependencies.tex
+++ b/dependencies.tex
@@ -117,11 +117,11 @@ In particular, note that whitespace is not optional.
     \end{tabular}
 \end{centertable}
 
-\subsection{All-of Dependency Specifications}
+\subsection{All-of dependency specifications}
 
 In an all-of group, all of the child elements must be matched.
 
-\subsection{Use-conditional Dependency Specifications}
+\subsection{USE-conditional dependency specifications}
 
 In a use-conditional group, if the associated use flag is enabled (or disabled if it has an
 exclamation mark prefix), all of the child elements must be matched.
@@ -129,7 +129,7 @@ exclamation mark prefix), all of the child elements must be matched.
 It is an error for a flag to be used if it is not included in \t{IUSE\_EFFECTIVE} as described in
 section~\ref{sec:use-iuse-handling}.
 
-\subsection{Any-of Dependency Specifications}
+\subsection{Any-of dependency specifications}
 
 Any use-conditional group that is an immediate child of an any-of group, if not enabled (disabled
 for an exclamation mark prefixed use flag name), is not considered a member of the any-of group
@@ -140,7 +140,7 @@ considered to be matched if its associated package dependency specification is n
 
 An empty any-of group counts as being matched.
 
-\subsection{Exactly-one-of Dependency Specifications}
+\subsection{Exactly-one-of dependency specifications}
 
 Any use-conditional group that is an immediate child of an exactly-one-of group, if not enabled
 (disabled for an exclamation mark prefixed use flag name), is not considered a member of the
@@ -150,7 +150,7 @@ In an exactly-one-of group, exactly one immediate child element must be matched.
 
 An empty exactly-one-of group counts as being matched.
 
-\subsection{At-most-one-of Dependency Specifications}
+\subsection{At-most-one-of dependency specifications}
 
 Any use-conditional group that is an immediate child of an at-most-one-of group, if not enabled
 (disabled for an exclamation mark prefixed use flag name), is not considered a member of the
@@ -160,7 +160,7 @@ In an at-most-one-of group, at most one immediate child element must be matched.
 
 An empty at-most-one-of group counts as being matched.
 
-\subsection{Package Dependency Specifications}
+\subsection{Package dependency specifications}
 
 A package dependency can be in one of the following base formats. A package manager must warn or
 error on non-compliant input.
@@ -232,7 +232,7 @@ The following operators are available:
 \item[\t{>}] Strictly greater than the specified version.
 \end{description}
 
-\subsubsection{Block Operator}
+\subsubsection{Block operator}
 
 If the specification is prefixed with one or two exclamation marks, the named dependency is a block
 rather than a requirement---that is to say, the specified package must not be installed, with the
@@ -263,7 +263,7 @@ described in table~\ref{tab:bang-strength-table}.
     \end{tabular}
 \end{centertable}
 
-\subsubsection{Slot Dependencies}
+\subsubsection{Slot dependencies}
 \label{sec:slot-dep}
 
 \featurelabel{slot-deps} A named slot dependency consists of a colon followed by a slot name. A
@@ -300,7 +300,7 @@ Whenever the equals slot operator is used in an enabled dependency group, the de
 (\t{DEPEND}) must ensure that a matching package is installed at build time. It is invalid to use
 the equals slot operator inside \t{PDEPEND} or inside any-of dependency specifications.
 
-\subsubsection{2-Style and 4-Style Use Dependencies}
+\subsubsection{2-style and 4-style USE dependencies}
 \label{sec:use-dep}
 
 A 2-style or 4-style use dependency consists of one of the following:
@@ -338,7 +338,7 @@ would not have to be part of \t{IUSE}.
 It is an error for an ebuild to use a conditional use dependency when that ebuild does not have the
 flag in \t{IUSE\_EFFECTIVE}.
 
-\subsection{Use State Constraints}
+\subsection{USE state constraints}
 \label{sec:required-use}
 \t{REQUIRED\_USE} contains a list of assertions that must be met by the configuration of \t{USE}
 flags to be valid for this ebuild. In order to be matched, a \t{USE} flag in a terminal element
diff --git a/ebuild-env-commands.tex b/ebuild-env-commands.tex
index 5deb388..30c297c 100644
--- a/ebuild-env-commands.tex
+++ b/ebuild-env-commands.tex
@@ -1,4 +1,4 @@
-\section{Available commands}
+\section{Available Commands}
 
 This section documents the commands available to an ebuild. Unless otherwise specified, they may be
 aliases, shell functions, or executables in the ebuild's \t{PATH}.
@@ -60,7 +60,7 @@ In some cases a package's build process will require the availability of executa
 the core system, a common example being autotools. The availability of commands provided by the
 particular types of dependencies is explained in section~\ref{sec:dependency-classes}.
 
-\subsection{Ebuild-specific Commands}
+\subsection{Ebuild-specific commands}
 \input{pkg-mgr-commands.tex}
 
 % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :
diff --git a/ebuild-env-invariancy.tex b/ebuild-env-invariancy.tex
index d69c510..861e6b9 100644
--- a/ebuild-env-invariancy.tex
+++ b/ebuild-env-invariancy.tex
@@ -1,4 +1,4 @@
-\section{The state of the system between functions}
+\section{The State of the System Between Functions}
 
 For the sake of this section:
 
diff --git a/ebuild-env-state.tex b/ebuild-env-state.tex
index 3ddd1ab..70a0e46 100644
--- a/ebuild-env-state.tex
+++ b/ebuild-env-state.tex
@@ -1,4 +1,4 @@
-\section{The state of variables between functions}
+\section{The State of Variables Between Functions}
 \label{sec:ebuild-env-state}
 
 Exported and default scope variables are saved between functions. A non-local variable set in a
diff --git a/ebuild-env-vars.tex b/ebuild-env-vars.tex
index 019ce3f..ae47aea 100644
--- a/ebuild-env-vars.tex
+++ b/ebuild-env-vars.tex
@@ -312,7 +312,7 @@ table~\ref{tab:locale-settings}.
     \end{tabular}
 \end{centertable}
 
-\subsection{USE and IUSE Handling}
+\subsection{USE and IUSE handling}
 \label{sec:use-iuse-handling}
 
 This section discusses the handling of four variables:
@@ -377,7 +377,7 @@ For EAPIs listed in table~\ref{tab:profile-iuse-injection-table} as supporting p
 \t{IUSE} injection, the package manager must save the calculated value of \t{IUSE\_EFFECTIVE} when
 installing a package. Details are beyond the scope of this specification.
 
-\subsection{\t{REPLACING\_VERSIONS} and \t{REPLACED\_BY\_VERSION}}
+\subsection{REPLACING\_VERSIONS and REPLACED\_BY\_VERSION}
 \label{sec:replacing-versions}
 
 \featurelabel{replace-version-vars} In EAPIs listed in table~\ref{tab:added-env-vars-table} as
@@ -393,7 +393,7 @@ In EAPIs listed in table~\ref{tab:added-env-vars-table} as supporting it, the
 \t{REPLACED\_BY\_VERSION} variable shall be defined in \t{pkg\_prerm} and \t{pkg\_postrm}. It shall
 contain at most one value.
 
-\subsection{Offset-prefix variables \t{EPREFIX}, \t{EROOT} and \t{ED}}
+\subsection{Offset-prefix variables}
 \label{sec:offset-vars}
 
 \ChangeWhenAddingAnEAPI{6}
diff --git a/ebuild-functions.tex b/ebuild-functions.tex
index a744ae1..045b207 100644
--- a/ebuild-functions.tex
+++ b/ebuild-functions.tex
@@ -18,7 +18,7 @@ package, not the current configuration.
 
 Ebuilds must not call nor assume the existence of any phase functions.
 
-\subsection{Initial Working Directories}
+\subsection{Initial working directories}
 \label{sec:s-to-workdir-fallback}
 
 Some functions may assume that their initial working directory is set to a particular location;
@@ -447,7 +447,7 @@ source files from their respective locations, with notes concerning licensing if
 
 \t{pkg\_nofetch} must require no write access to any part of the filesystem.
 
-\subsection{\t{default\_} Phase Functions}
+\subsection{Default phase functions}
 \label{sec:default-phase-funcs}
 
 \featurelabel{default-phase-funcs} In EAPIs listed in
diff --git a/ebuild-vars.tex b/ebuild-vars.tex
index ecb50df..9a9502e 100644
--- a/ebuild-vars.tex
+++ b/ebuild-vars.tex
@@ -8,7 +8,7 @@ If any of these variables are set to invalid values, or if any of the mandatory
 undefined, the package manager's behaviour is undefined; ideally, an error in one ebuild should not
 prevent operations upon other ebuilds or packages.
 
-\section{Metadata invariance}
+\section{Metadata Invariance}
 \label{sec:metadata-invariance}
 
 All ebuild-defined variables discussed in this chapter must be defined independently of
@@ -163,7 +163,7 @@ unlisted architectures.
 
 An empty \t{KEYWORDS} variable indicates uncertain functionality on any architecture.
 
-\subsection{\t{RDEPEND} value}
+\subsection{RDEPEND value}
 \label{sec:rdepend-depend}
 
 \featurelabel{rdepend-depend} In EAPIs listed in table~\ref{tab:rdepend-depend-table} as having
diff --git a/eclasses.tex b/eclasses.tex
index 51c9a83..7569caf 100644
--- a/eclasses.tex
+++ b/eclasses.tex
@@ -11,7 +11,7 @@ Eclasses must be located in the \t{eclass} directory in the top level of the rep
 section~\ref{sec:eclass-dir}. Each eclass is a single file named \t{<name>.eclass}, where \t{<name>} is
 the name of this eclass, used by \t{inherit} and \t{EXPORT\_FUNCTIONS} among other places.
 
-\section{The inherit command}
+\section{The inherit Command}
 \label{sec:inherit}
 
 An ebuild wishing to make use of an eclass does so by using the \t{inherit} command in global scope.
diff --git a/merge.tex b/merge.tex
index 9da9631..0077837 100644
--- a/merge.tex
+++ b/merge.tex
@@ -33,7 +33,7 @@ except as follows:
 On SELinux systems, the SELinux context must also be preserved. Other directory attributes, including
 modification time, may be discarded.
 
-\subsection{Empty Directories}
+\subsection{Empty directories}
 
 Behaviour upon encountering an empty directory is undefined. Ebuilds must not attempt to install an
 empty directory.
@@ -100,7 +100,7 @@ is undefined.
     \end{tabular}
 \end{centertable}
 
-\subsection{Configuration File Protection}
+\subsection{Configuration file protection}
 \label{sec:config-protect}
 
 The package manager must provide a means to prevent user configuration files from being
@@ -141,7 +141,7 @@ Ebuilds must not attempt to merge a symlink on top of a directory.
 Any absolute symlink whose link starts with \t{D} must be rewritten with the leading \t{D} removed.
 The package manager should issue a notice when doing this.
 
-\section{Hard links}
+\section{Hard Links}
 
 A hard link may be merged either as a single file with links or as multiple independent files.
 
diff --git a/names.tex b/names.tex
index e4c3975..a348c0f 100644
--- a/names.tex
+++ b/names.tex
@@ -5,14 +5,14 @@
 No name may be empty. Package managers must not impose fixed upper boundaries upon the length of any
 name. A package manager should indicate or reject any name that is invalid according to these rules.
 
-\subsection{Category Names}
+\subsection{Category names}
 A category name may contain any of the characters [\t{A-Za-z0-9+\_.-}]. It must not begin with
 a hyphen, a dot or a plus sign.
 
 \note A hyphen is \e{not} required because of the \t{virtual} category. Usually, however, category
 names will contain a hyphen.
 
-\subsection{Package Names}
+\subsection{Package names}
 A package name may contain any of the characters [\t{A-Za-z0-9+\_-}]. It must not begin with a
 hyphen or a plus sign, and must not end in a hyphen followed by anything matching the version
 syntax described in section~\ref{sec:version-spec}.
@@ -20,35 +20,35 @@ syntax described in section~\ref{sec:version-spec}.
 \note A package name does not include the category. The term \i{qualified package name} is used
 where a \t{category/package} pair is meant.
 
-\subsection{Slot Names}
+\subsection{Slot names}
 \label{sec:slot-names}
 A slot name may contain any of the characters [\t{A-Za-z0-9+\_.-}]. It must not begin with a
 hyphen, a dot or a plus sign.
 
-\subsection{USE Flag Names}
+\subsection{USE flag names}
 A USE flag name may contain any of the characters [\t{A-Za-z0-9+\_@-}]. It must begin with an
 alphanumeric character. Underscores should be considered reserved for \t{USE\_EXPAND}, as
 described in section~\ref{sec:use-iuse-handling}.
 
 \note The at-sign is required for \t{LINGUAS}.
 
-\subsection{Repository Names}
+\subsection{Repository names}
 \label{sec:repository-names}
 A repository name may contain any of the characters [\t{A-Za-z0-9\_-}]. It must not begin with a
 hyphen. In addition, every repository name must also be a valid package name.
 
-\subsection{License Names}
+\subsection{License names}
 \label{sec:license-names}
 A license name may contain any of the characters [\t{A-Za-z0-9+\_.-}]. It must not begin with a
 hyphen, a dot or a plus sign.
 
-\subsection{Keyword Names}
+\subsection{Keyword names}
 \label{sec:keyword-names}
 A keyword name may contain any of the characters [\t{A-Za-z0-9\_-}]. It must not begin with a
 hyphen. In contexts where it makes sense to do so, a keyword name may be prefixed by
 a tilde or a hyphen. In \t{KEYWORDS}, \t{-*} is also acceptable as a keyword.
 
-\subsection{EAPI Names}
+\subsection{EAPI names}
 \label{sec:eapi-names}
 An EAPI name may contain any of the characters [\t{A-Za-z0-9+\_.-}]. It must not begin with a
 hyphen, a dot or a plus sign.
@@ -207,7 +207,7 @@ from which it was invoked.
 \end{algorithmic}
 \end{algorithm}
 
-\section{Uniqueness of versions}
+\section{Uniqueness of Versions}
 
 No two packages in a given repository may have the same qualified package name and equal versions.
 For example, a repository may not contain more than one of \t{foo-bar/baz-1.0.2},
diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index 389d8c0..7da9d4b 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -718,7 +718,7 @@ in table~\ref{tab:compression-table} as supporting \t{docompress}.
     \end{tabular}
 \end{centertable}
 
-\subsubsection{Use List Functions}
+\subsubsection{USE list functions}
 These functions provide behaviour based upon set or unset use flags. Ebuilds must not run any of
 these commands once the current phase function has returned. It is an error if an ebuild calls any
 of these functions in global scope.
@@ -800,7 +800,7 @@ table~\ref{tab:use-list-strictness}.
     \end{tabular}
 \end{centertable}
 
-\subsubsection{Text List Functions}
+\subsubsection{Text list functions}
 These functions check whitespace-separated lists for a particular value.
 
 \begin{description}
@@ -810,7 +810,7 @@ These functions check whitespace-separated lists for a particular value.
 \item[hasq] Deprecated synonym for \t{has}.
 \end{description}
 
-\subsubsection{Misc Commands}
+\subsubsection{Misc commands}
 The following commands are always available in the ebuild environment, but don't really fit in any
 of the above categories. Ebuilds must not run any of these commands once the current phase function
 has returned.
@@ -987,7 +987,7 @@ has returned.
     \end{tabular}
 \end{centertable}
 
-\subsubsection{Debug Commands}
+\subsubsection{Debug commands}
 The following commands are available for debugging. Normally all of these commands should be no ops;
 a package manager may provide a special debug mode where these commands instead do something.
 Ebuilds must not run any of these commands once the current phase function has returned.
@@ -1000,7 +1000,7 @@ Ebuilds must not run any of these commands once the current phase function has r
 \item[debug-print-section] Calls \t{debug-print} with \t{now in section \$*}.
 \end{description}
 
-\subsubsection{Reserved Commands and Variables}
+\subsubsection{Reserved commands and variables}
 
 Except where documented otherwise, all functions and variables that contain any of the following
 strings (ignoring case) are reserved for package manager use and may not be used or relied upon by
diff --git a/profile-variables.tex b/profile-variables.tex
index c47b748..5fd2d8b 100644
--- a/profile-variables.tex
+++ b/profile-variables.tex
@@ -1,10 +1,10 @@
-\section{Profile variables}
+\section{Profile Variables}
 \label{sec:profile-variables}
 
 This section documents variables that have special meaning, or special behaviour, when defined in a
 profile's \t{make.defaults} file.
 
-\subsection{Incremental Variables}
+\subsection{Incremental variables}
 \i{Incremental} variables must stack between parent and child profiles in the following manner:
 Beginning with the highest parent profile, tokenise the variable's value based on whitespace and
 concatenate the lists. Then, for any token $T$ beginning with a hyphen, remove it and any previous
diff --git a/profiles.tex b/profiles.tex
index ff791ac..2d0656d 100644
--- a/profiles.tex
+++ b/profiles.tex
@@ -1,7 +1,7 @@
 \chapter{Profiles}
 \label{sec:profiles}
 
-\section{General principles}
+\section{General Principles}
 Generally, a profile defines information specific to a certain `type' of system---it lies somewhere
 between repository-level defaults and user configuration in that the information it contains is not
 necessarily applicable to all machines, but is sufficiently general that it should not be left to
@@ -13,7 +13,7 @@ the files described in this chapter, and possibly inheriting another profile. Th
 follow a few basic conventions as regards inheritance and format; these are described in the next
 section. It may also contain any number of subdirectories containing other profiles.
 
-\section{Files that make up a profile}
+\section{Files That Make up a Profile}
 
 \subsection{The parent file}
 A profile may contain a \t{parent} file. Each line must contain a relative path to another profile
-- 
2.12.2