By the Developers HOWTO I mean gentoo-howto.xml, linked from the docs list page as the Ebuild HOWTO and titled the Developers HOWOTO - slightly confusing names, btw. 1. About ebuild naming, the Policy forbids underscores, while the HOWTO allows them. I take this to mean portage-the-app supports underscores but portage-the-standard doesn't. IMHO this should be noted in the HOWTO, because noone should be using 'nonstandard' portage extensions. Or is there a distinction between portage/ebuilds-the-standard and portage/ebuilds-the-policy? 2. Portage considers 1.0a > 1.0.1, which isn't mentioned in either document, and should be, for completeness. 3. Comparisons like 3.0 vs. 3.0.0 confuse portage. Fex. I see 3.0.0 > 3.0, but also 3.0.0 > 3.0.0.0. And 3 > 3.<any number of zeros>. (This is apprently not reproducible using the portage api directly, only using emerge.) I'll file a separate bug about portage's incosistent behaviour, but you might consider noting in the docs that people should try not to have two such versions in the same package. 4. The Policy says, correctly, that 1.0_p1 > 1.0: "the suffixes are ordered as follows (lower means older): _alpha < _beta < _pre < _rc < (no suffix) < _p". The HOWTO doesn't mention this, grouping _p together with -beta, _rc... which could confuse people to think that 1.0_p1 < 1.0. In view of all this, I also suggest that the versioning sections of the two docs could be merged into a single definitive one, with perhaps a few notes on policy vs. the strict standard in the Policy.
1. added _ to the policy 2. portage needs to figure out what behavior it's going to have ... theyve been talking about this (a.k.a. this will be done LATER) 3. a portage issue, not a documentation issue persay ... see #2 above 4. added 'no suffix' mention in between _rc and _p