Renat Lumpau wrote: > I just committed our new documentation [1] for webapp.eclass. We hope that it > will help devs and users write and maintain ebuilds for web applications. > Comments and patches are welcome. > > We also have a brand new project page [2], courtesy of wrobel. > > [1] http://www.gentoo.org/proj/en/webapps/webapp-eclass.xml > [2] http://www.gentoo.org/proj/en/webapps/
A few comments: 1. I can see this in many places of the Gentoo docs, so it is not specific to this particular doc, but still: the CSS for span.code would better be changed to use another color than the links. I very often catch myself trying to click on it (e.g. I expected "man 5 webapp.eclass" to be a link to the on-line man page; BTW that would not be a bad idea at all if it can be kept in sync). So if this is not supposed to be changed locally, (I see it is coming from http://www.gentoo.org/css/main.css?d=20051010 ) whom shall I contact? 2. Consider this paragraph: webapp.eclass is located in the usual place in the Portage tree. By default, it will be found in /usr/portage/eclass/webapp.eclass. By definition, the source code is the ultimate documentation and should be consulted whenever something does not perform as expected or further clarification is required. "By default, it will be found in /usr/portage/eclass/webapp.eclass." is not acurate I think ( found in /usr/portage/eclass/ is better). Even better if you combine the first two sentences: webapp.eclass is located under /usr/portage/eclass in a Gentoo default installation. BTW, is there an easy way to get the source XML of this (and other) doc? So I can send patches directly. 3. The "Beginner, Intermediate, Advanced" section titles might be better if they are a bit longer, say: "A Beginner example ebuild: www-apps/gallery" Is the version required for the sect title? Yes, it is required inside the explanation though. 4. This warning: "Warning: If the package requires specific Perl modules, all dependencies must have ebuilds available. Relying on CPAN is not acceptable." Why is that? If I have a webapp that needs ">=dev-perl/foo-3.0.4" which does not have (yet) an ebuild in /usr/portage what to do? Isn't the normal way to fail the emerge because 'cannot find any ebuilds that satisfy ">=dev-perl/foo-3.0.4"! ' A helpful hint "Try using `g-cpan -i foo` and reemerge ${PKG}" will be very good solution. Act accordingly for PHP, Ruby and whatever we have. 5. Just below the above warning, the discussion about databases... > A common mistake with specifying dependencies for web applications is to > unconditionally RDEPEND on a database engine such as MySQL or PostgreSQL. > Many, if not all, web applications are able to connect to a remote > database server. Thus, a local database should not be a requirement; Perfect up to here. > the right syntax for dealing with this is: > > Code Listing 2.8: Database Dependencies > > mysql? ( >=dev-db/mysql-4 ) /me might be wrong, but isn't this asking for the availability of a MySQL server installed? Don't tell me webapp.eclass treats the RDEPEND differently! Isn't it more normal to depend on, say dev-perl/DBD-mysql for a Perl webapp? ( change accordingly for PHP, etc.) 6. The last word :-) - contact the web-apps herd or ask on <a>IRC</a>. + contact the web-apps herd or discuss it on <a>#gentoo-web</a> IRC channel. Imagine reading it printed :-| 7. Having gone over it, why not webappS.eclass ? $ ls /usr/portage/eclass/*s.eclass |wc -l 23 examples: euitls, games, nsplugins, xemacs-packages ... Kalin. -- |[ ~~~~~~~~~~~~~~~~~~~~~~ ]| +-> http://ThinRope.net/ <-+ |[ ______________________ ]| -- gentoo-dev@gentoo.org mailing list
