[gentoo-pms] RFC: Promote 11.3.3 "Ebuild-specific commands" to a section

[gentoo-pms] RFC: Promote 11.3.3 "Ebuild-specific commands" to a section

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 859 bytes --]

Currently chapter 11 "The Ebuild Environment" is the largest chapter
by far with 23 pages (second is chapter 9 "Ebuild-defined functions"
with only 8 pages). Subsection 11.3.3 "Ebuild-specific commands" alone
has 14 pages, and with EAPI 7 it will grow further.

So I wonder if we could promote "Ebuild-specific commands" to a
section. I see two possibilities:

- Most straight forward would be to promote section 11.3 "Available
  Commands" to a chapter. OTOH, that would also move 11.3.2 to section
  level, which feels wrong because it has only three lines.

- Alternatively, we could leave the chapter structure alone, rename
  section 11.3 to "External Commands", and promote 11.3.3 to a new
  section 11.4. Chapter 11 would keep its somewhat excessive length,
  though.

I would slightly prefer the second plan, unless anybody has a better
idea.

Ulrich

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

[gentoo-pms] [PATCH 1/2] Move shell options to "Ebuild file format" chapter.

[Ulrich Müller]

[-- Attachment #1: Type: text/plain, Size: 5009 bytes --]

Since this paragraph is about Bash options like failglob, it fits
better with the Bash version than with "System commands".
---
 eapi-differences.tex    |  8 ++++----
 ebuild-env-commands.tex | 16 ++++------------
 ebuild-format.tex       | 15 ++++++++++-----
 3 files changed, 18 insertions(+), 21 deletions(-)

diff --git a/eapi-differences.tex b/eapi-differences.tex
index 8f8bf72..2b74e05 100644
--- a/eapi-differences.tex
+++ b/eapi-differences.tex
@@ -46,6 +46,9 @@ Stable use masking/forcing & \compactfeatureref{stablemask} &
 Bash version & \compactfeatureref{bash-version} &
     3.2 & 3.2 & 3.2 & 3.2 & 4.2 \\
 
+\t{failglob} in global scope & \compactfeatureref{failglob} &
+    No & No & No & No & Yes \\
+
 \t{IUSE} defaults & \compactfeatureref{iuse-defaults} &
     * & Yes & Yes & Yes & Yes \\
 
@@ -147,9 +150,6 @@ Profile \t{IUSE} injection & \compactfeatureref{profile-iuse-inject} &
 \t{EPREFIX}, \t{ED}, \t{EROOT} & \compactfeatureref{offset-prefix-vars} &
     No & Yes & Yes & Yes & Yes \\
 
-\t{failglob} in global scope & \compactfeatureref{failglob} &
-    No & No & No & No & Yes \\
-
 \t{find} is GNU? & \compactfeatureref{gnu-find} &
     Undefined & Undefined & Undefined & Yes & Yes \\
 
@@ -346,10 +346,10 @@ EAPI 6 is EAPI 5 with the following changes:
 
 \begin{compactitem}
 \item Bash version is 4.2, \featureref{bash-version}.
+\item \t{failglob} is enabled in global scope, \featureref{failglob}.
 \item Default \t{src_prepare} no longer a no-op, \featureref{src-prepare-6}.
 \item Different \t{src_install} implementation, \featureref{src-install-6}.
 \item \t{LC_CTYPE} and \t{LC_COLLATE} compatible with POSIX locale, \featureref{locale-settings}.
-\item \t{failglob} is enabled in global scope, \featureref{failglob}.
 \item \t{einstall} banned, \featureref{banned-commands}.
 \item \t{die} and \t{assert} called with \t{-n} respect \t{nonfatal}, \featureref{nonfatal-die}.
 \item \t{eapply} support, \featureref{eapply}.
diff --git a/ebuild-env-commands.tex b/ebuild-env-commands.tex
index d1773f5..650d200 100644
--- a/ebuild-env-commands.tex
+++ b/ebuild-env-commands.tex
@@ -32,24 +32,16 @@ The following commands must always be available in the ebuild environment:
     table~\ref{tab:system-commands-table} as requiring GNU find.
 \end{compactitem}
 
-\subsubsection{Shell options}
-
-\featurelabel{failglob} For EAPIs listed such in table~\ref{tab:system-commands-table}, the
-\t{failglob} option of bash is set in the global scope of ebuilds. If set, failed pattern matches
-during filename expansion result in an error when the ebuild is being sourced.
-
 \ChangeWhenAddingAnEAPI{6}
 \begin{centertable}{System commands for EAPIs}
     \label{tab:system-commands-table}
-    \begin{tabular}{lll}
+    \begin{tabular}{ll}
       \toprule
       \multicolumn{1}{c}{\textbf{EAPI}} &
-      \multicolumn{1}{c}{\textbf{GNU \t{find}?}} &
-      \multicolumn{1}{c}{\textbf{\t{failglob} in global scope?}} \\
+      \multicolumn{1}{c}{\textbf{GNU \t{find}?}} \\
       \midrule
-      0, 1, 2, 3, 4     & Undefined & No  \\
-      5                 & Yes       & No  \\
-      6                 & Yes       & Yes \\
+      0, 1, 2, 3, 4     & Undefined \\
+      5, 6              & Yes       \\
       \bottomrule
     \end{tabular}
 \end{centertable}
diff --git a/ebuild-format.tex b/ebuild-format.tex
index 638f773..fac5c81 100644
--- a/ebuild-format.tex
+++ b/ebuild-format.tex
@@ -7,21 +7,26 @@ table~\ref{tab:bash-version}, or any later version. If possible, the package man
 the shell's compatibility level to the exact version specified. It must ensure that any such
 compatibility settings (e.\,g.\ the \t{BASH_COMPAT} variable) are not exported to external programs.
 
+\featurelabel{failglob} For EAPIs listed such in table~\ref{tab:bash-version}, the \t{failglob}
+option of bash is set in the global scope of ebuilds. If set, failed pattern matches during
+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}
 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.
 
 \ChangeWhenAddingAnEAPI{6}
-\begin{centertable}{Bash version}
+\begin{centertable}{Bash version and options}
     \label{tab:bash-version}
-    \begin{tabular}{ll}
+    \begin{tabular}{lll}
       \toprule
       \multicolumn{1}{c}{\textbf{EAPI}} &
-      \multicolumn{1}{c}{\textbf{Bash version}} \\
+      \multicolumn{1}{c}{\textbf{Bash version}} &
+      \multicolumn{1}{c}{\textbf{\t{failglob} in global scope?}} \\
       \midrule
-      0, 1, 2, 3, 4, 5  & 3.2 \\
-      6                 & 4.2 \\
+      0, 1, 2, 3, 4, 5  & 3.2 & No  \\
+      6                 & 4.2 & Yes \\
       \bottomrule
     \end{tabular}
 \end{centertable}
-- 
2.14.2

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

[gentoo-pms] [PATCH 2/2] Promote "Available commands" from section to chapter.

[Ulrich Müller]

[-- Attachment #1: Type: text/plain, Size: 10207 bytes --]

"The ebuild environment" is the largest chapter by far with 23 pages,
mainly due to section "Available commands" which alone has 15 pages.
Therefore, promote this section to a chapter of its own (which will
still be the largest chapter of the document).
---
 ebuild-env-commands.tex => commands.tex | 10 +++++-----
 ebuild-environment.tex                  |  2 --
 pkg-mgr-commands.tex                    | 34 ++++++++++++++++-----------------
 pms.tex                                 |  2 ++
 4 files changed, 24 insertions(+), 24 deletions(-)
 rename ebuild-env-commands.tex => commands.tex (92%)

diff --git a/ebuild-env-commands.tex b/commands.tex
similarity index 92%
rename from ebuild-env-commands.tex
rename to commands.tex
index 650d200..5f6fe7a 100644
--- a/ebuild-env-commands.tex
+++ b/commands.tex
@@ -1,13 +1,13 @@
-\section{Available Commands}
+\chapter{Available Commands}
 
-This section documents the commands available to an ebuild. Unless otherwise specified, they may be
+This chapter documents the commands available to an ebuild. Unless otherwise specified, they may be
 aliases, shell functions, or executables in the ebuild's \t{PATH}.
 
 When an ebuild is being sourced for metadata querying rather than for a build (that is to say,
 when none of the \t{src_} or \t{pkg_} functions are to be called), no external command may
 be executed. The package manager may take steps to enforce this.
 
-\subsection{System commands}
+\section{System Commands}
 
 Any ebuild not listed in the system set for the active profile(s) may assume the presence of every
 command that is always provided by the system set for that profile. However, it must target the
@@ -17,7 +17,7 @@ equivalent, which is inherited by all available profiles. If an ebuild requires
 provided by the system profile, or that are provided conditionally based on USE flags, appropriate
 dependencies must be used to ensure their presence.
 
-\subsubsection{Guaranteed system commands}
+\subsection{Guaranteed system commands}
 \label{sec:guaranteed-system-commands}
 
 The following commands must always be available in the ebuild environment:
@@ -46,7 +46,7 @@ The following commands must always be available in the ebuild environment:
     \end{tabular}
 \end{centertable}
 
-\subsection{Commands provided by package dependencies}
+\section{Commands Provided by Package Dependencies}
 
 In some cases a package's build process will require the availability of executables not provided by
 the core system, a common example being autotools. The availability of commands provided by the
diff --git a/ebuild-environment.tex b/ebuild-environment.tex
index 99e7967..82c036c 100644
--- a/ebuild-environment.tex
+++ b/ebuild-environment.tex
@@ -4,8 +4,6 @@
 
 \input{ebuild-env-state.tex}
 
-\input{ebuild-env-commands.tex}
-
 \input{ebuild-env-invariancy.tex}
 
 % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :
diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index 6fd35ae..ab9c586 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -1,4 +1,4 @@
-\subsection{Ebuild-specific commands}
+\section{Ebuild-specific Commands}
 \label{sec:pkg-mgr-commands}
 
 The following commands will always be available in the ebuild environment, provided by the package
@@ -8,7 +8,7 @@ behaviour.
 
 Unless otherwise noted, any output of these commands ends with a newline.
 
-\subsubsection{Failure behaviour and related commands}
+\subsection{Failure behaviour and related commands}
 \label{sec:failure-behaviour}
 
 \featurelabel{die-on-failure} Where a command is listed as having EAPI dependent failure behaviour,
@@ -41,7 +41,7 @@ The following commands affect this behaviour:
     \end{tabular}
 \end{centertable}
 
-\subsubsection{Banned commands}
+\subsection{Banned commands}
 \label{sec:banned-commands}
 
 \featurelabel{banned-commands} Some commands are banned in some EAPIs. If a banned command is
@@ -66,7 +66,7 @@ called, the package manager must abort the build process indicating an error.
     \end{tabular}
 \end{centertable}
 
-\subsubsection{Sandbox commands}
+\subsection{Sandbox commands}
 These commands affect the behaviour of the sandbox. Each command takes a single directory as
 argument. Ebuilds must not run any of these commands once the current phase function has returned.
 \begin{description}
@@ -77,7 +77,7 @@ argument. Ebuilds must not run any of these commands once the current phase func
 \item[adddeny] Add a directory to the deny list.
 \end{description}
 
-\subsubsection{Package manager query commands}
+\subsection{Package manager query commands}
 These commands are used to extract information about the system. Ebuilds must not run any of
 these commands in parallel with any other package manager command. Ebuilds must not run any of
 these commands once the current phase function has returned.
@@ -107,7 +107,7 @@ to the host root instead of \t{ROOT}.
     \end{tabular}
 \end{centertable}
 
-\subsubsection{Output commands}
+\subsection{Output commands}
 These commands display messages to the user. Unless otherwise stated, the entire argument list is
 used as a message, with backslash-escaped characters interpreted as for the \t{echo -e} command of
 bash, notably \t{\textbackslash t} for a horizontal tab, \t{\textbackslash n} for a new line, and
@@ -130,7 +130,7 @@ stderr or some other appropriate facility.
     message followed by a failure indicator. Returns its first argument as exit status.
 \end{description}
 
-\subsubsection{Error commands}
+\subsection{Error commands}
 These commands are used when an error is detected that will prevent the build process from
 completing. Ebuilds must not run any of these commands once the current phase function has returned.
 \begin{description}
@@ -158,7 +158,7 @@ completing. Ebuilds must not run any of these commands once the current phase fu
     \end{tabular}
 \end{centertable}
 
-\subsubsection{Patch commands}
+\subsection{Patch commands}
 These commands are used during the \t{src_prepare} phase to apply patches to the package's sources.
 Ebuilds must not run any of these commands once the current phase function has returned.
 
@@ -232,7 +232,7 @@ Ebuilds must not run any of these commands once the current phase function has r
     \end{tabular}
 \end{centertable}
 
-\subsubsection{Build commands}
+\subsection{Build commands}
 These commands are used during the \t{src_configure}, \t{src_compile}, and \t{src_install}
 phases to run the package's build commands. Ebuilds must not run any of these commands once the
 current phase function has returned.
@@ -356,7 +356,7 @@ emake \
 
 \end{description}
 
-\subsubsection{Installation commands}
+\subsection{Installation commands}
 These commands are used to install files into the staging area, in cases where the package's \t{make
 install} target cannot be used or does not install all needed files. Except where otherwise stated,
 all filenames created or modified are relative to the staging directory including the offset-prefix
@@ -624,7 +624,7 @@ can be extended or reduced (see below). The options that can be passed to \t{doh
     \end{tabular}
 \end{centertable}
 
-\subsubsection{Commands affecting install destinations}
+\subsection{Commands affecting install destinations}
 The following commands are used to set the various destination trees, all relative to \t{\$\{ED\}} in
 offset-prefix aware EAPIs and relative to \t{\$\{D\}} in offset-prefix agnostic EAPIs, used by the
 above installation commands. They must be shell functions or aliases, due to the need to set variables
@@ -659,7 +659,7 @@ has returned.
 
 \end{description}
 
-\subsubsection{Commands affecting install compression}
+\subsection{Commands affecting install compression}
 
 \featurelabel{docompress} In EAPIs listed in table~\ref{tab:compression-table} as supporting
 controllable compression, the package manager may optionally compress a subset of the files under
@@ -721,7 +721,7 @@ in table~\ref{tab:compression-table} as supporting \t{docompress}.
     \end{tabular}
 \end{centertable}
 
-\subsubsection{USE list functions}
+\subsection{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.
@@ -803,7 +803,7 @@ table~\ref{tab:use-list-strictness}.
     \end{tabular}
 \end{centertable}
 
-\subsubsection{Text list functions}
+\subsection{Text list functions}
 These functions check whitespace-separated lists for a particular value.
 
 \begin{description}
@@ -813,7 +813,7 @@ These functions check whitespace-separated lists for a particular value.
 \item[hasq] Deprecated synonym for \t{has}.
 \end{description}
 
-\subsubsection{Misc commands}
+\subsection{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.
@@ -992,7 +992,7 @@ has returned.
     \end{tabular}
 \end{centertable}
 
-\subsubsection{Debug commands}
+\subsection{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.
@@ -1005,7 +1005,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}
+\subsection{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/pms.tex b/pms.tex
index 3f338fb..4d2cd99 100644
--- a/pms.tex
+++ b/pms.tex
@@ -68,6 +68,8 @@
 
 \include{ebuild-environment}
 
+\include{commands}
+
 \include{merge}
 
 \include{metadata-cache}
-- 
2.14.2

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

[gentoo-pms] Re: RFC: Promote 11.3.3 "Ebuild-specific commands" to a section

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 1048 bytes --]

>>>>> On Thu, 28 Sep 2017, Ulrich Mueller wrote:

> Currently chapter 11 "The Ebuild Environment" is the largest chapter
> by far with 23 pages (second is chapter 9 "Ebuild-defined functions"
> with only 8 pages). Subsection 11.3.3 "Ebuild-specific commands" alone
> has 14 pages, and with EAPI 7 it will grow further.

> So I wonder if we could promote "Ebuild-specific commands" to a
> section. I see two possibilities:

> - Most straight forward would be to promote section 11.3 "Available
>   Commands" to a chapter. OTOH, that would also move 11.3.2 to section
>   level, which feels wrong because it has only three lines.

> - Alternatively, we could leave the chapter structure alone, rename
>   section 11.3 to "External Commands", and promote 11.3.3 to a new
>   section 11.4. Chapter 11 would keep its somewhat excessive length,
>   though.

> I would slightly prefer the second plan, unless anybody has a better
> idea.

Actually the first plan requires fewer changes of text. A series of
two patches will follow, please review.

Ulrich

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

[gentoo-pms] Re: RFC: Promote 11.3.3 "Ebuild-specific commands" to a section

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 785 bytes --]

>>>>> On Fri, 29 Sep 2017, Ulrich Mueller wrote:

>> Currently chapter 11 "The Ebuild Environment" is the largest
>> chapter by far with 23 pages (second is chapter 9 "Ebuild-defined
>> functions" with only 8 pages). Subsection 11.3.3 "Ebuild-specific
>> commands" alone has 14 pages, and with EAPI 7 it will grow further.

>> So I wonder if we could promote "Ebuild-specific commands" to a
>> section. I see two possibilities:

>> - Most straight forward would be to promote section 11.3 "Available
>> Commands" to a chapter. OTOH, that would also move 11.3.2 to
>> section level, which feels wrong because it has only three lines.

>> - [...]

> Actually the first plan requires fewer changes of text. A series of
> two patches will follow, please review.

Pushed to master.

Ulrich

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]