[gentoo-dev] webapp.eclass documentation

[gentoo-dev] webapp.eclass documentation

[Renat Lumpau]

[-- Attachment #1: Type: text/plain, Size: 516 bytes --]

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/
-- 
Renat Lumpau
all things web-apps
GPG key id #C6A838DA on http://pgp.mit.edu
Key fingerprint = 04AF B5EE 17CB 1000 DDA5  D3FC 1338 ADC2 C6A8 38DA

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] webapp.eclass documentation

[Kalin KOZHUHAROV]

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

Re: [gentoo-dev] webapp.eclass documentation

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 1269 bytes --]

Kalin KOZHUHAROV wrote:
> 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?

Please use the gentoo-doc mailing list or #gentoo-doc at freenode or
file a bug against Docs-user component on our Bugzilla.

You might also want to check the new appearance on our redesign site
(not in sync with the fresh contents) [1].

> 2. Consider this paragraph:
[...]
Submit a bug, please.

> BTW, is there an easy way to get the source XML of this (and other) doc? So
> I can send patches directly.

Append "?passthru=1" to the end of the URL (or "&passthru=1" of the URL
string already contains the "?" sign). See [2].

[1] http://wwwredesign.gentoo.org/
[2] http://www.gentoo.org/proj/en/gdp/doc/doc-tipsntricks.xml#doc_chap1

Cheers,
-jkt

-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]