Re: [gentoo-pms] Patches for your reviewing pleasure: Various improvements, including cheat sheet

[Christian Faulhammer]

Hi,

Ciaran McCreesh <ciaran.mccreesh@××××××××××.com>:
[chapters subdir]
> Well, it's really an all or nothing thing. And all's going to be a
> pain until we're sure we aren't going to have to go back and edit the
> history.

 We can wait with it.


> > 0001: Desk reference, updated and all issues you raised handled.
>
> You're indenting with two spaces rather than four, and don't have our
> precious vim modelines. Lack of consistency makes me cry!

 Then go change the other files, and if Vim is too dumb to recognise a
LaTeX file, I can't help it.

> > +  from the same checkout as this overview.
>
> has trailing whitespace. Git moans about this.

 Fixed.
 
> > +  Please report mistakes or enhancements to this document via the
>
> should read "mistakes in or enhancements to"
>
> > +Currently there is no full specification what EAPI 0 includes.
> > +Portage, official ebuild documentation and existing ebuilds set the
> > +standard here, although obvious errors are still errors.
>
> I'm wondering whether we can tone this (and the similar wording in
> PMS) down a bit. The Council approved PMS as "correct, except where
> people file bugs" a while back.
>
> > +  disabled explicitely by user configuration) with a \code{+} sign
> > in
>
> Spelling of 'explicitly'.
>
> > +\item[Named slot dependencies] Dependencies can explicitely
> > request a
>
> Ditto.
>
> > +\item[\code{SRC\_URI} arrows] Allows redirection of upstream file
> > +  naming scheme by using an "arrow" (\code{->}) to a new file name
> > in
> > +  DISTDIR.  See \featureref{src-uri-arrows}.
>
> Not sure on this wording. How about something like:
>
>     SRC_URI="http://some/url -> foo" can be used to use foo as the
>     filename for downloads.
>
> > +\item[USE dependencies] Dependencies can be specified to be built
> > with
> > +  or without a specific USE flag, thus getting rid of countless
> > +  \code{built\_with\_use} checks.  A more sophisticated syntax is
> > +  available in EAPI 3.
>
>     Dependencies can specify use flag requirements on their target,
>     removing the need for built_with_use checks. A more powerful
> syntax that does not require the flag to be in IUSE is in EAPI 3.
>
> > +  Patching and other preparing tasks must no longer take place in
> > +  \code{src\_unpack} but in \code{src\_prepare}.
>
>     Patching and similar preparation must now be done in src_prepare,
>     not src_unpack.
>
> > +  be called via \code{default\_\emph{phasename}}, so small
> > additions
> > +  you need will not be accompanied by a complete reimplementation
> > of
> > +  the phase.  Additionally as a shorthand for the current phase's
> > +  default definition \code{default} can be invoked.
>
>     so duplicating the standard implementation is no longer necessary.
>     The default function calls the current phase's default_ function
>     automatically.
>
> > +  Duplicating checks from the \code{pkg\_setup} phase may be
> > +  necessary.
>
>     Most checks should usually be repeated in pkg_setup.
>
> > +  phase can be called even for non-installed packages.  Do not
> > depend
> > +  on any outside programs in that case!  See \featureref{pkg-info}.
>
>     Be warned that dependencies might not have been installed.
>
> > +\item[Slot operators] There are two ways to define a wanted slot
> > in a
> > +  dependency string:
>
>     Dependencies that are both DEPEND and RDEPEND and that can match
>     multiple slots should specify one of:
>
> > +\item[USE dependency defaults] Additionally to the features
> > offered in
>
>     In addition to the ...
>
> > +  after a USE flag (mind the braces).
>
> Braces are {}. You want brackets or parentheses.
>
> > The former leads to the
> > +  assumption that the USE flag is available when not found in the
> > +  dependency, the latter leads to the reverse behaviour.  This
> > mimicks
> > +  parts of the behaviour of \code{-{}-missing} in
>
>     The former specifies that flags not in IUSE should be treated as
>     enabled; the latter, disabled. Cannot be used with USE_EXPAND
> flags.
>
> > +  \code{/usr/share\{doc,info,man\}} are compressed on-disk after
>
> s/are/may be
>
> > +  With \code{docompress} all arguments are passed to the inclusion
> > +  list, while the behaviour can be inverted with the \code{-x}
> > +  switch.  See \featureref{controllable-compress}.
>
>     docompress path ... adds paths to the inclusion list for
>     compression. docompress -x path ... adds paths to the exclusion
>     list.
>
> > +  files respectively in the known manner.
>
> "in the known manner" sounds weird.
>
> > +  command given as argument will not abort the build process in
> > case
> > +  of a failure but preserve the exit status nonetheless.  See
>
> I'd mention that commands die on error before this. And then:
>
>     will return non-zero on failure rather than aborting the build.
>
> > +\item[USE flags in any-of] Inside of \code{||} constructs USE flag
> > +  conditionals are forbidden (with exceptions).
>
>     use? ( ) blocks are forbidden as direct children of || ( ) blocks.
>
> > +  anymore.
>
> 'anymore' as a single word is generally considered horrible.

 Adressed I hope.  Last iteration, what you don't find now, will go in
later.

And more patches:
0001: Corrected desk reference.
0002: Tell Emacs to use retarded indenting in all LaTeX files, so the
Vim weenies don't whine.
0003: Fix intendation to 4 spaces where needed.
0004: Comment class file
0005: Kick out appendix.sty and a little appendix tweak
0006: Some minor Makefile tweaking
0007: Make email addresses clickable

And for inital review:
0008: Add Gentoo logo to PMS and desk reference.

V-Li

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

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