[gentoo-pms] EAPI feature labelling

[gentoo-pms] EAPI feature labelling

[Ciaran McCreesh]

[-- Attachment #1.1: Type: text/plain, Size: 722 bytes --]

I'm going to go through and do paragraph-level labels for every EAPI
dependent feature on the eapi-3 branch.

I'm using this for development:

    \newcommand{\featureref}[1]{\b{feat:#1} on page~\pageref{feat:#1}}
    \newcommand{\compactfeatureref}[1]{\b{feat:#1}~p\pageref{feat:#1}}
    \newcommand{\featurelabel}[1]{\label{feat:#1} \visiblelabel{feat:#1} }
    \newcommand{\visiblelabel}[1]{\b{[#1]}}

I've attached a demonstration diff covering EAPI 1 things.

Is this going to work, or do I need to change how I'm doing anything?
Can you suggest a better \featurelabel that does the margin box thing
and that will work even if placed in an \item or \table or whatever?

Thanks,
-- 
Ciaran McCreesh

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: eapi-1-labels.patch --]
[-- Type: text/x-patch, Size: 5812 bytes --]

diff --git a/dependencies.tex b/dependencies.tex
index ed8ab61..53e9b13 100644
--- a/dependencies.tex
+++ b/dependencies.tex
@@ -205,6 +205,7 @@ error on non-compliant input.
     \t{category/package}, followed by a hyphen, followed by a version specification.
 \end{compactitem}
 
+\featurelabel{slot-deps}
 In EAPIs shown in table~\ref{tab:slot-deps-table} as supporting \t{SLOT} dependencies, either of the
 above formats may additionally be suffixed by a \t{:slot} restriction, as described in
 section~\ref{sec:slot-dep}. A package manager must warn or error if slot dependencies are used with an
diff --git a/eapi-differences.tex b/eapi-differences.tex
index 9d87624..c2e72ec 100644
--- a/eapi-differences.tex
+++ b/eapi-differences.tex
@@ -59,7 +59,7 @@
 Profile \t{USE} injection & table~\ref{tab:profile-iuse-injection-table} & No & No &
     \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} No & Yes \\
 
-\t{IUSE} defaults & table~\ref{tab:iuse-defaults-table} & No & Yes &
+\t{IUSE} defaults & \compactfeatureref{iuse-defaults} & No & Yes &
     \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Yes} &}{} Yes & Yes \\
 
 \IFANYKDEBUILDELSE{
@@ -128,7 +128,7 @@ Profile \t{USE} injection & table~\ref{tab:profile-iuse-injection-table} & No &
 }{}
 
 Slot dependencies &
-    table~\ref{tab:slot-deps-table} &
+    \compactfeatureref{slot-deps} &
     No &
     Named &
     \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Named and Operator} &}{}
@@ -159,7 +159,7 @@ Use dependencies & table~\ref{tab:use-deps-table} & No & No &
 \t{src\_configure} & table~\ref{tab:src-configure-table} & No & No &
 \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} Yes & Yes \\
 
-\t{src\_compile} style & table~\ref{tab:src-compile-table} & 0 & 1 &
+\t{src\_compile} style & \compactfeatureref{src-compile} & 0 & 1 &
     \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{1} &}{} 2 & 2 \\
 
 \t{src\_install} style & table~\ref{tab:src-install-table} & no-op & no-op &
@@ -278,9 +278,9 @@ EAPI 0 is the base EAPI.
 EAPI 1 is EAPI 0 with the following changes:
 
 \begin{compactitem}
-\item \t{IUSE} defaults, table~\ref{tab:iuse-defaults-table}.
-\item Slot dependencies, table~\ref{tab:slot-deps-table}.
-\item Different \t{src\_compile} implementation, table~\ref{tab:src-compile-table}.
+\item \t{IUSE} defaults, \featureref{iuse-defaults}.
+\item Slot dependencies, \featureref{slot-deps}.
+\item Different \t{src\_compile} implementation, \featureref{src-compile-1}.
 \end{compactitem}
 
 \IFKDEBUILDELSE
@@ -317,7 +317,7 @@ EAPI 2 is EAPI 1 with the following changes:
 \item \t{!} and \t{!!} blockers, table~\ref{tab:bang-strength-table}.
 \item \t{src\_prepare}, table~\ref{tab:src-prepare-table}.
 \item \t{src\_configure}, table~\ref{tab:src-configure-table}.
-\item Different \t{src\_compile} implementation, table~\ref{tab:src-compile-table}.
+\item Different \t{src\_compile} implementation, \featureref{src-compile-2}.
 \item \t{default\_} phase functions for phases \t{pkg\_nofetch}, \t{src\_unpack}, \t{src\_prepare},
     \t{src\_configure}, \t{src\_compile} and \t{src\_test}; table~\ref{tab:default-phase-function-table}.
 \item \t{doman} languages support, table~\ref{tab:doman-table}.
diff --git a/ebuild-functions.tex b/ebuild-functions.tex
index ba9f346..86095cf 100644
--- a/ebuild-functions.tex
+++ b/ebuild-functions.tex
@@ -285,12 +285,14 @@ src_configure() {
 \subsection{src\_compile}
 \label{sec:src-compile-function}
 
+\featurelabel{src-compile}
 The \t{src\_compile} function configures the package's build environment in EAPIs lacking
 \t{src\_configure}, and builds the package in all EAPIs.
 
 The initial working directory is \t{S}, with an error or fallback to \t{WORKDIR} as discussed in
 section~\ref{sec:s-to-workdir-fallback}.
 
+\featurelabel{src-compile-0}
 For EAPIs listed in table~\ref{tab:src-compile-table} as using format 0, the default implementation used
 when the ebuild lacks the \t{src\_compile} function shall behave as:
 
@@ -305,6 +307,7 @@ src_compile() {
 }
 \end{verbatim}
 
+\featurelabel{src-compile-1}
 For EAPIs listed in table~\ref{tab:src-compile-table} as using format 1, the default implementation used
 when the ebuild lacks the \t{src\_compile} function shall behave as:
 
@@ -319,6 +322,7 @@ src_compile() {
 }
 \end{verbatim}
 
+\featurelabel{src-compile-2}
 For EAPIs listed in table~\ref{tab:src-compile-table} as using format 2, the default implementation used
 when the ebuild lacks the \t{src\_compile} function shall behave as:
 
diff --git a/ebuild-vars.tex b/ebuild-vars.tex
index 3c86422..8966203 100644
--- a/ebuild-vars.tex
+++ b/ebuild-vars.tex
@@ -30,6 +30,7 @@ All ebuilds must define at least the following variables:
     responsible for merging these values. See section~\ref{sec:use-iuse-handling} for discussion on
     which values must be listed this variable.
 
+    \featurelabel{iuse-defaults}
     In EAPIs shown in table~\ref{tab:iuse-defaults-table} as supporting \t{IUSE} defaults, any use flag
     name in \t{IUSE} may be prefixed by at most one of a plus or a minus sign. If such a prefix is
     present, the package manager may use it as a suggestion as to the default value of the use flag
diff --git a/pms.tex b/pms.tex
index dc00271..f55da36 100644
--- a/pms.tex
+++ b/pms.tex
@@ -50,6 +50,11 @@
 \renewcommand{\b}[1]{\textbf{#1}}
 \newcommand{\note}[1]{\paragraph{Note:} #1}
 
+\newcommand{\featureref}[1]{\b{feat:#1} on page~\pageref{feat:#1}}
+\newcommand{\compactfeatureref}[1]{\b{feat:#1}~p\pageref{feat:#1}}
+\newcommand{\featurelabel}[1]{\label{feat:#1} \visiblelabel{feat:#1} }
+\newcommand{\visiblelabel}[1]{\b{[#1]}}
+
 \definecolor{deepblue}{rgb}{0.0, 0.2, 0.7}
 \definecolor{deeppurple}{rgb}{0.7, 0.0, 0.8}
 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-pms] EAPI feature labelling

[Christian Faulhammer]

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

Hi,

Ciaran McCreesh <ciaran.mccreesh@googlemail.com>:

> I'm using this for development:
> 
>     \newcommand{\featureref}[1]{\b{feat:#1} on page~\pageref{feat:#1}}
>     \newcommand{\compactfeatureref}[1]{\b{feat:#1}~p\pageref{feat:#1}}
>     \newcommand{\featurelabel}[1]{\label{feat:#1}
> \visiblelabel{feat:#1} } \newcommand{\visiblelabel}[1]{\b{[#1]}}

 What you use is not really important as long as you use the new
commands and they will be defined in such a way that they use the
\label and \ref commands.  <- Great sentence.  Do you really want to
bold the references?  You will visually overload the page.  For
proof-reading this may be ok, but the end version should use \emph.

> Is this going to work, or do I need to change how I'm doing anything?
> Can you suggest a better \featurelabel that does the margin box thing
> and that will work even if placed in an \item or \table or whatever?

 \newcommand{\featurelabel}[1]{\marginpar{\framebox{feat:#1}}\label{feat:#1}}
was my initial idea. and kill \visiblelabel.  Lists should be no
problem, table is...so I had a look around and my friend Markus Kohm
has a solution:

\usepackage{marginnote} % written by Markus Kohm and available in
			% TeXLive

\newcommand{\featurelabel}[1]{\marginnote{\framebox{feat:#1}}\label{feat:#1}}

V-Li

-- 
Christian Faulhammer, Gentoo Lisp project
<URL:http://www.gentoo.org/proj/en/lisp/>, #gentoo-lisp on FreeNode

<URL:http://gentoo.faulhammer.org/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-pms] EAPI feature labelling

[Ciaran McCreesh]

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

On Fri, 10 Apr 2009 19:05:12 +0200
Christian Faulhammer <fauli@gentoo.org> wrote:
> > I'm using this for development:
> > 
> >     \newcommand{\featureref}[1]{\b{feat:#1} on
> > page~\pageref{feat:#1}}
> > \newcommand{\compactfeatureref}[1]{\b{feat:#1}~p\pageref{feat:#1}}
> > \newcommand{\featurelabel}[1]{\label{feat:#1}
> > \visiblelabel{feat:#1} } \newcommand{\visiblelabel}[1]{\b{[#1]}}
> 
>  What you use is not really important as long as you use the new
> commands and they will be defined in such a way that they use the
> \label and \ref commands.

Goodgood.

> Do you really want to bold the references?  You will visually
> overload the page.  For proof-reading this may be ok, but the end
> version should use \emph.

I don't really mind what they look like. Those commands I wrote were
just things I could get working quickly. I'll leave the "making it look
pretty" to you or anyone else who feels like messing with it.

> > Is this going to work, or do I need to change how I'm doing
> > anything? Can you suggest a better \featurelabel that does the
> > margin box thing and that will work even if placed in an \item or
> > \table or whatever?
> 
>  \newcommand{\featurelabel}[1]{\marginpar{\framebox{feat:#1}}\label{feat:#1}}
> was my initial idea. and kill \visiblelabel.  Lists should be no
> problem, table is...so I had a look around and my friend Markus Kohm
> has a solution:
> 
> \usepackage{marginnote} % written by Markus Kohm and available in
> 			% TeXLive
> 
> \newcommand{\featurelabel}[1]{\marginnote{\framebox{feat:#1}}\label{feat:#1}}

Hokey, I'll start playing with those. Thanks.

-- 
Ciaran McCreesh

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]