* Re: [gentoo-dev] webapp.eclass documentation
2006-01-19 23:23 [gentoo-dev] webapp.eclass documentation Renat Lumpau
@ 2006-01-20 15:38 ` Kalin KOZHUHAROV
2006-01-23 16:30 ` Jan Kundrát
0 siblings, 1 reply; 3+ messages in thread
From: Kalin KOZHUHAROV @ 2006-01-20 15:38 UTC (permalink / raw
To: gentoo-dev
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
^ permalink raw reply [flat|nested] 3+ messages in thread