The ebuild howto is a quite usable primer, from which most people try to write their first ebuild. As did I. However, when I attached it on bugzilla, I was given a link to the "common ebuild mistakes" document at http://dev.gentoo.org/~liquidx/ebuildmistakes.html Which had some quite useful information (and yes, I violated quite a few of those rules, changing my ebuild was about 5 to 10 minutes of work). The document was new to me. It's not linked from the ebuild HOWTO, or mentioned as an official document. To improve the quality of (first-time) user-submitted ebuilds, it would in my eyes be very helpful to at least link to the common ebuild mistakes from the HOWTO document itself (and perhaps include it as an official document, or even merge the common mistakes with the ebuild HOWTO).
I've asked Alastair if we could migrate his document to GuideXML, place it under doc/en and link it from the guide.
Why not add a chapter in gentoo-howto.xml? It's not much more than cut'n'paste. I have to review the French translation (next on my list after HB translation which is almost done) very soon and I could very well integrate it before taking care of the French version.
If liquidx doesn't mind and it doesn't make it less readable, sure, why not?
Okay liquidx doesn't mind (he actually was planning on doing this but never found the time :)
i'd prefer a sep document, called common ebuild mistakes just like it is i think it would be cleaner that way, and when we refer people to it, it doesnt look like we're sending them to a HOWTO and telling them to RTFM howtos are diff from FAQs and this is kinda like a FAQ :)
What's to be done on this one? Personally, I'd rather have a single doc as this information should be read by anyone who reads the gentoo-howto and plans on submitting ebuilds. People who have made mistakes can be directed straight to the added chapter with a link like http://www.gentoo.org/doc/en/gentoo-howto.xml#doc_chap6
well i might point out that some browsers dont handle links like that (#name) too well ... but i still think it'd be better with a sep document for my previous reasons
I'd say "make it a separate document". It isn't a lot of work to join them (or separate them) and some people might want to print out one document but not the other. And if we at any point feel that it is better to join them, we'll join them :)
I'll convert the doc to GuideXML tomorrow during classes :p
Created attachment 25341 [details] ebuild-mistakes.xml document This is a GuideXML'ed version of Alastair Tse's document. I'll commit it to CVS later...
The guide is committed as http://www.gentoo.org/doc/en/ebuild-mistakes.xml.
I've linked to this document from the gentoo-howto, which makes this bug fixed :)
