2.1:
mildly cracktastic in first reading; almost reads as if "names" is an actual entity,
rather then talking about common properties.  Might want to reword it.


2.1.6:
stating "in some contexts" glosses over stating when it's valid, same for ~.  Since y'all are specifically
mentioning them, should provide the basic meaning of ~arch and -* (can argue it's implementation specific,
but that's a major stretch)


2.2:
completely skipped float comparison; wording there also explicitly ignores their existance.  Spanky has a bug
open already re: this.

Dropped -cvs also (if intentional, should note it somehow).


3.2:
"each category provided by the repository shall be contained in one directory, whose name is that category";
drop the filler, same thing is stated above in 3.1

Allowing empty categories seems a bit funky also.
Rephrase "Additional directories may not be present to avoid conflicts"; explicitly phrase it as 
"category directory may not contain non-package directories"


3.4
package.mask is appended to the leftmost inherit chain for profiles; meaning profiles *can* override
repository level defined masks.  overlay behaviour there isn't defined either.


3.7.1:
cache entry:
lack of mtime documentation, means staleness verification isn't fully possible for partial trees.

Simple example, paludis flat_list format has differing mtime rules.  under the specs definition, the 
paludis flat_list format is valid cache data, despite the fact portage staleness detection will flag
it and regenerate it.

Dropping mtime requirement for cache entries in the tree means that either
1) staleness verification must be dropped for the tree
2) certain trees become "paludis trees" and "portage/pkgcore trees" based on the cache mtime format.

Whats dumb about this is that the data ordering is the same- the mtime setting is all that differs, but
since the cache format definition is incomplete in the spec, you can't rely on the metadata/cache 
if you're doing staleness verification.


4.2.11:
doesn't document that the flags should be paired (ie, don't try pruning something that isn't there).
potentially that can just be argued as a style thing, although it hides errors allowing missed pairings
to slide through.  same goes for 4.2.9.


5:
rename it to "old style virtuals"
old style virtuals should not be involved in versioned deps; usage of it is a side affect of portage behaviour.
up for debate whether it should be considered 'standard' since all implement it, additionally since old style virtuals
(assuming say virtual/jre) *can* sanely be versioned, just something of a rarity.


5.1.*: dependency rules about provides should be moved here


7.2:
keywords aren't incremental between the eclass and the ebuild, nor have they ever been.
wording on implicit rdepend vs eclasses blows; rather vague.


7.3:
not explicit (however is implicit), the exported func name must be prefixed by the eclasses exact name (sans .eclass).
EXPORT_FUNCTIONS invoked once per eclass is semi-arbitrary

s/can be used to 'export'/can be used to alias/; oddly enough, you can mark functions as exported.


8.1:
wording suggestion:
All ebuild/eclass defined metadata variables must not be sensitive to the system generating it; the host
system should in no way influence the resultant metadata.  Put simply, the resultant metadata variables
must be constant for that ebuild/eclass regardless of the environment, including system defined USE.

"globally defined ebuild variables without a special meaning must similarly not rely upon variable data" isn't
quite true (per the norm, specifics).  Additionally, the issue of pre-existing env for reexecution of the env
can come up.


8.2:
drop the "may be defined by eclass"; irrevelant.
homepage is a uri, phrasing choosen is weird.

KEYWORDS=-* is deprecated offhand (bug open about it); definition there is fairly redundant due to
2.1.6, suggest "whitespace delimited list of keywords" instead with the appropriate link.


8.3:
defining S as being based off of WORKDIR, when WORKDIR thus far (as far as I can tell) hasn't been defined
isn't too useful/friendly; suggest linkage/reordering

RESTRICT definition is utterly crappy, lacks sandbox, doesn't provide any definition of what the listed
bools actually do.  

The problem with not documenting the misc restricts there is that ebuilds wind up having to grow tricks
localizing themselves to the manager to accomplish the same thing- 
src_test() {
  if hasq test $FEATURES; then
    make check || die bugger
  fi
}
for example.  Test wise, userpriv matters a fair bit (and a good number of ebuilds check for it in
$FEATURES), thus again, the restricts need better defining.

Finally, pkg_nofetch is only invoked when restrict=fetch is defined; thus that *has* to be clarified
if pkg_nofetch phase support is required.

Additionally, restrict *does* support use conditionals, which is totally unstated in the doc.


"ideally an error in one ebuild should not prevent operations" fairly counter to long standing behaviour,
regardless, it doesn't belong in the spec.

Possibly worth noting that the metadata keys are locked down post env/ebuild/eclass sourcing via a 
readonly also.

finally, provide rules aren't explicit; the provided target must be an unversioned virtual/foo.  interlinkage
with 5 advised.  Further, definition there allows ||() to be used, which obviously is insane.


8.4:
"may be magically defined" -> "must be defined by the manager inherit implementation"

the "inherit must be constant in invocation for an ebuild" doesn't belong there, belongs in metadata constant
rules.


9.1:
description there is a fair bit off; the reliance on the target discerns whether or not rdepend must be 
first or can come after.  In other words, if I'm building something that rdeps on diffball, if nothing in
the graph requires diffball to work during the interim (meaning it's rdeps fully satisfied), then the rdeps
don't need to be complete until something requires diffball to work.

That's a bit more accurate then "can be dropped to post dependencies to break cycles"; you can shift the 
rdepend satisfiers around only up until another package needs to 'use' that package (thus requiring its
rdepends to be satisfied).


9.x:
suggest breaking depset rules out into their own, labeling it "dependencies" and describing SRC_URI rules is daft.
Very least, Dependencies is a bad name for DepSet since it's used for much more then just dependencies.


9.2:
use group; state it must be followed by an any-all; no description of the rules for the grouping currently.

provide examples for 9.2.*


9.2.1:
use the historical name, 'atom' instead of switching terminolgy to package dependency

=sys-apps/portage-2.0.* isn't valid, only =sys-apps/portage-2.0* is valid. (be explicit)

~sys-apps/portage-2.1.2-r9 definition is semi misleading.  yes, version comparison is done (just that)-
however "except the revision part of the matching package may be greater than the revision part" confuses the issue.
haven't scanned, but would be inclined to state ~ with -r* is invalid; no ebuild in the tree has it now.

"blocks on a package provided by the ebuild"; be specific, old style virtuals is what you're addressing, but the wording
is inaccurate- blocks apply as long as the provider target is *not* from the ebuild.

"blocks on the ebuild itself do not count", yes they do (drop the 'ebuild' and go with CP instead for terminology
also)

It's retarded if they're doing an unversioned block, but due to slotting, it's required- simple example,
v0.9 wasn't yet slottable, version 1.0 is.  later slottings have to do !<1.0 to prevent the collision
against the older version.


9.2.4:
Wording sucks- an empty || () in the raw depset is forbid, but it can resolve down to ||()- in which case it is considered
'satisfied'.

|| () depsets resolving down to nothing, and being considered 'satisfied' is also something of an internal
side affect; poke jstubbs and a few others, expect it'll stay (for now) but don't think most folks are aware, let alone
that they'll all like it.

example-
|| ( ( !yourarch? ( app-arch/bzip2 ) !someflag? ( app-arch/tar ) ) dev-util/bsdiff )
won't pull in bsdiff, which without a scan I'd expect has at least a few cases in the tree where folks expect it to be.


10.1:
drop the "most functions" and be explicit; "unless otherwise stated, phase hooks shouldn't have access to anything other
then ${T},${WORKDIR}" 

Would suggest using a different name then "functions" for the phase hooks also; terminology wise, ought to make
it easier for the reader to identify where the manager hands control over.

have no documentation about the expected sandbox allowances, further skipping over the expected behaviour for userpriv,
usersandbox (userpriv'd sandbox), etc.  Yes, partially manager implemented, but the specifics of perms should be covered-
simple example, shift from pkg_setup to src_unpack- privs can change.

finally, the base env for the hooks isn't really linked in; USE for pkg_config comes from where?  user configuration, 
or vdb? (vdb obviously, but you get the idea).


10.1.5:
would suggest an alt word then no-op; it's minor, but wonder about it for non-native english readers.


10.1.6:
worth noting, pkg_preinst should not read in ${S}; breaks binpkgs.  wording above only covers write access,
doesn't cover read (which differs here).

ebuilds can write to ${T} in pkg_preinst also (several do for knowing what they're merging so they can do tweaks to ROOT
in postinst, regening icon cache for example)


10.1.8:
interactivity crap in reference to the other phases; glep52 (unattended, to address interactivity) was withdrawn, meaning
that until ACCEPT_LICENSE is across the board (not mandated in the spec afaik), interactivity is valid (albeit fucking annoying)
in license crap.

If you care to argue that one, take it up with games folk also since they're the main consumers at this point :)


10.1.9:
pkg_nofetch doesn't write anywhere- a) no point in doing so, b) scanned it.


11.1.1:
sort it.

would suggest dropping AA.  nothing uses it, nor can I recall ever actually *seeing* it used.
re: USE, suggest specifically stating space rather then 'whitespace'.  Haven't scanned, but would expect ebuilds to
occasionally output USE quoted, thus newlines/tabs slip through- minor, but said ebuilds/eclasses would be reliant on
the existing portage behaviour of space delimited instead of whitespace.

PATH: doesn't cover ebuild/eclass mangling of it in terms of manager preservation.

example shoved into 11.1.2 (global_variable) really ought to be inlined under the relevant section instead of floating.
potentially a pdf generation thing.


11.3.2:
RDEPEND for pkg_setup, never seen anything relying on it.  seems spurious, especially with the weasel words
"resolver can violate this as it sees fit if it thinks a cycle is involved"


11.3.3:
probably worth dropping the DIROPTIONS statement; few ebuilds use it directly, and they likely should be updated.

"List Functions", which really should have a number attached to it:
"These functions work on variables containing whitespace delimited lists" <-- whitespace bit seems redundant;
only use* actually internally pokes a variable, has* requires everything via args.

use_with rewording:
"Requires at least one arg, takes optionally two more..."

example might be useful there.


12:
collapse 2 into 1:
If the directory containing the file to merge is not listed or a subdir of a directory in CONFIG_PROTECT, or is 
exempted in CONFIG_PROTECT_MASK, merge it.