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