From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from lists.gentoo.org ([140.105.134.102] helo=robin.gentoo.org) by nuthatch.gentoo.org with esmtp (Exim 4.54) id 1EzyRI-0007yA-4g for garchives@archives.gentoo.org; Fri, 20 Jan 2006 15:44:36 +0000 Received: from robin.gentoo.org (localhost [127.0.0.1]) by robin.gentoo.org (8.13.5/8.13.5) with SMTP id k0KFghdi019042; Fri, 20 Jan 2006 15:42:43 GMT Received: from mail.tar.bz (s175249.ppp.asahi-net.or.jp [220.157.175.249]) by robin.gentoo.org (8.13.5/8.13.5) with ESMTP id k0KFcYGa003523 for ; Fri, 20 Jan 2006 15:38:35 GMT Received: (qmail 20898 invoked by uid 210); 20 Jan 2006 15:38:32 -0000 Received: from 192.168.1.122 by dorf (envelope-from , uid 89) with qmail-scanner-1.25st (clamdscan: 0.87/1096. perlscan: 1.25st. Clear:RC:1(192.168.1.122):. Processed in 0.029648 secs); 20 Jan 2006 15:38:32 -0000 Received: from kpc.tar.bz (HELO ?192.168.1.122?) (kalin.smtp%tar.bz@192.168.1.122) by dorf.tar.bz with ESMTPA; 20 Jan 2006 15:38:32 -0000 Message-ID: <43D103EC.4040609@thinrope.net> Date: Sat, 21 Jan 2006 00:38:20 +0900 From: Kalin KOZHUHAROV User-Agent: Mail/News 1.5 (X11/20060115) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@gentoo.org Reply-to: gentoo-dev@lists.gentoo.org MIME-Version: 1.0 To: gentoo-dev@lists.gentoo.org Subject: Re: [gentoo-dev] webapp.eclass documentation References: <20060119232319.GA28923@toucan.gentoo.org> In-Reply-To: <20060119232319.GA28923@toucan.gentoo.org> X-Enigmail-Version: 0.94.0.0 OpenPGP: id=26BE7385 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-Archives-Salt: cc8171d0-3a69-41f1-a9ae-a51a41bda210 X-Archives-Hash: e2fba28d56ce414a43f48e76f57c46bc 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 IRC. + contact the web-apps herd or discuss it on #gentoo-web 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