1 |
drobbins@g.o wrote: |
2 |
> |
3 |
> Hi All, |
4 |
> |
5 |
> In a few days, we're going to start an official documentation rampage, lasting |
6 |
> about a week. Hopefully, in that time, we can get a whole bunch of |
7 |
> documentation done and on the website. Fortunately, I'm writing an article for |
8 |
> IBM on the website redesign, so I can devote some time to documentation. |
9 |
> However, this does mean that our doc solution will be scrutinized by the world, |
10 |
> but I figured we're up to the task. |
11 |
> |
12 |
> For a refresher, this is what everybody seems to be in agreement upon: |
13 |
> |
14 |
> 1. The documentation should be composed in XML. |
15 |
> 2. We should use XSLT to translate the XML documentation into web-ready HTML. |
16 |
> |
17 |
> However, we still haven't decided which XML approach to use: |
18 |
> |
19 |
> a. Use our own custom "guide" format designed for our needs |
20 |
> b. Use the already complete docbook format for our XML |
21 |
> |
22 |
> In my eyes, the advantage of a custom guide format is that it is much easier to |
23 |
> change/upgrade if we need new features, and is definitely going to have a |
24 |
> simpler, more HTML-like syntax. |
25 |
> |
26 |
> The advantage of the docbook format is that it's a standard (for technical |
27 |
> documentation), and has a lot of features. The downside of this is that we are |
28 |
> less in control of the format and we will need to learn the "docbook way" of |
29 |
> doing things. Another concern about docbook -- since it has a lot more tags |
30 |
> than our lightweight guide format, writing docbook --> HTML XSL transforms could |
31 |
> be *very* cumbersome, since we will have to support all docbook tags :( This |
32 |
> appears to be the major drawback to docbook -- its DTD is *huge*. |
33 |
|
34 |
There is a lite version of docbook which is not that huge. |
35 |
I'm currently making packages for the docbook-xml-dtd's and |
36 |
docbook(-lite) xsl's. |
37 |
You should be able to test them in a few hours. |
38 |
|
39 |
It's true docbook transformation need much time with these xsl's. But |
40 |
since we do not use dynamic XML generation time should not be the |
41 |
problem. |
42 |
|
43 |
Another thing. I want to make two new categories: |
44 |
|
45 |
- app-spell: (for i/a/pspell, their backendsand the dictionaries. |
46 |
- app-ml: for all the xml/sgml/html whatever ml stuff. |
47 |
|
48 |
Or should ml be a new major categorie with ml-apps and ml-libs |
49 |
subcategories? |
50 |
Then we can put stuff like libwww, libxslt, libxml in ml-libs. And |
51 |
things like |
52 |
jade, sablotron, and all the sgml-tools to ml-apps. |
53 |
|
54 |
achim~ |
55 |
|
56 |
|
57 |
|
58 |
> |
59 |
> example docbook XML: |
60 |
> |
61 |
> /usr/portage/app-doc/gentoo-doc/files/install.docbook |
62 |
> |
63 |
> example guide (beta) XML: |
64 |
> |
65 |
> /usr/portage/app-doc/gentoo-web/files/xml/install.xml |
66 |
> |
67 |
> -- |
68 |
> Daniel Robbins <drobbins@g.o> |
69 |
> President/CEO http://www.gentoo.org |
70 |
> Gentoo Technologies, Inc. |
71 |
> |
72 |
> _______________________________________________ |
73 |
> gentoo-dev mailing list |
74 |
> gentoo-dev@g.o |
75 |
> http://www.gentoo.org/mailman/listinfo/gentoo-dev |