| 1 |
Achim Gottinger wrote: |
| 2 |
> |
| 3 |
> drobbins@g.o wrote: |
| 4 |
> > |
| 5 |
> > Hi All, |
| 6 |
> > |
| 7 |
> > In a few days, we're going to start an official documentation rampage, lasting |
| 8 |
> > about a week. Hopefully, in that time, we can get a whole bunch of |
| 9 |
> > documentation done and on the website. Fortunately, I'm writing an article for |
| 10 |
> > IBM on the website redesign, so I can devote some time to documentation. |
| 11 |
> > However, this does mean that our doc solution will be scrutinized by the world, |
| 12 |
> > but I figured we're up to the task. |
| 13 |
> > |
| 14 |
> > For a refresher, this is what everybody seems to be in agreement upon: |
| 15 |
> > |
| 16 |
> > 1. The documentation should be composed in XML. |
| 17 |
> > 2. We should use XSLT to translate the XML documentation into web-ready HTML. |
| 18 |
> > |
| 19 |
> > However, we still haven't decided which XML approach to use: |
| 20 |
> > |
| 21 |
> > a. Use our own custom "guide" format designed for our needs |
| 22 |
> > b. Use the already complete docbook format for our XML |
| 23 |
> > |
| 24 |
> > In my eyes, the advantage of a custom guide format is that it is much easier to |
| 25 |
> > change/upgrade if we need new features, and is definitely going to have a |
| 26 |
> > simpler, more HTML-like syntax. |
| 27 |
> > |
| 28 |
> > The advantage of the docbook format is that it's a standard (for technical |
| 29 |
> > documentation), and has a lot of features. The downside of this is that we are |
| 30 |
> > less in control of the format and we will need to learn the "docbook way" of |
| 31 |
> > doing things. Another concern about docbook -- since it has a lot more tags |
| 32 |
> > than our lightweight guide format, writing docbook --> HTML XSL transforms could |
| 33 |
> > be *very* cumbersome, since we will have to support all docbook tags :( This |
| 34 |
> > appears to be the major drawback to docbook -- its DTD is *huge*. |
| 35 |
> |
| 36 |
> There is a lite version of docbook which is not that huge. |
| 37 |
> I'm currently making packages for the docbook-xml-dtd's and |
| 38 |
> docbook(-lite) xsl's. |
| 39 |
> You should be able to test them in a few hours. |
| 40 |
|
| 41 |
I have commited all the required packages. You will need |
| 42 |
|
| 43 |
app-text/docbook-xml DTD's |
| 44 |
app-text/docbook-xml-simplified DTD's |
| 45 |
app-text/docbook-xsl XSL Stylesheets for XML->HTML and XML->FO |
| 46 |
transformation |
| 47 |
|
| 48 |
gnome-libs/libxml2 required for libxslt |
| 49 |
gnome-libs/libxslt includes the required xsltproc. |
| 50 |
|
| 51 |
Once you have installed all these, you can transform install.docbook to |
| 52 |
html with the following command: |
| 53 |
|
| 54 |
xsltproc /usr/share/sgml/docbook/xsl/1.29/html/docbook.xsl |
| 55 |
install.docbook > install.html |
| 56 |
|
| 57 |
If you want to disable dtd validation use the option --novalid |
| 58 |
|
| 59 |
achim~ |
Archives