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

[Ciaran McCreesh]

On Tue, 14 Apr 2009 15:55:43 +0200
Christian Faulhammer <fauli@g.o> wrote:
> > I agree with you on the principle, but not on the numbers. It's not
> > worth using subdirectories until 'ls' output won't fit on one
> > screen.
>
>  Having actually done the change, does make the thing look really
> good. After a make run all the .log, .aux and whatever files are also
> around.

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.

> 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!

> +  from the same checkout as this overview.

has trailing whitespace. Git moans about this.

> +  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.

> 0002: Some Makefile tweaking (really minor).

OK, but won't apply easily without 0001, and I'm lazy.

> 0003: Use plainurl.bst from the system.

Applied, thanks.

> 0004: Some proper using of the description environment.

Applied, thanks.

-- 
Ciaran McCreesh