1 |
Achim Gottinger wrote: |
2 |
> |
3 |
> Achim Gottinger wrote: |
4 |
> > |
5 |
> > drobbins@g.o wrote: |
6 |
> > > |
7 |
> > > Hi All, |
8 |
> > > |
9 |
> > > In a few days, we're going to start an official documentation rampage, lasting |
10 |
> > > about a week. Hopefully, in that time, we can get a whole bunch of |
11 |
> > > documentation done and on the website. Fortunately, I'm writing an article for |
12 |
> > > IBM on the website redesign, so I can devote some time to documentation. |
13 |
> > > However, this does mean that our doc solution will be scrutinized by the world, |
14 |
> > > but I figured we're up to the task. |
15 |
> > > |
16 |
> > > For a refresher, this is what everybody seems to be in agreement upon: |
17 |
> > > |
18 |
> > > 1. The documentation should be composed in XML. |
19 |
> > > 2. We should use XSLT to translate the XML documentation into web-ready HTML. |
20 |
> > > |
21 |
> > > However, we still haven't decided which XML approach to use: |
22 |
> > > |
23 |
> > > a. Use our own custom "guide" format designed for our needs |
24 |
> > > b. Use the already complete docbook format for our XML |
25 |
> > > |
26 |
> > > In my eyes, the advantage of a custom guide format is that it is much easier to |
27 |
> > > change/upgrade if we need new features, and is definitely going to have a |
28 |
> > > simpler, more HTML-like syntax. |
29 |
> > > |
30 |
> > > The advantage of the docbook format is that it's a standard (for technical |
31 |
> > > documentation), and has a lot of features. The downside of this is that we are |
32 |
> > > less in control of the format and we will need to learn the "docbook way" of |
33 |
> > > doing things. Another concern about docbook -- since it has a lot more tags |
34 |
> > > than our lightweight guide format, writing docbook --> HTML XSL transforms could |
35 |
> > > be *very* cumbersome, since we will have to support all docbook tags :( This |
36 |
> > > appears to be the major drawback to docbook -- its DTD is *huge*. |
37 |
> > |
38 |
> > There is a lite version of docbook which is not that huge. |
39 |
> > I'm currently making packages for the docbook-xml-dtd's and |
40 |
> > docbook(-lite) xsl's. |
41 |
> > You should be able to test them in a few hours. |
42 |
> |
43 |
> I have commited all the required packages. You will need |
44 |
> |
45 |
> app-text/docbook-xml DTD's |
46 |
> app-text/docbook-xml-simplified DTD's |
47 |
> app-text/docbook-xsl XSL Stylesheets for XML->HTML and XML->FO |
48 |
> transformation |
49 |
> |
50 |
> gnome-libs/libxml2 required for libxslt |
51 |
> gnome-libs/libxslt includes the required xsltproc. |
52 |
> |
53 |
> Once you have installed all these, you can transform install.docbook to |
54 |
> html with the following command: |
55 |
> |
56 |
> xsltproc /usr/share/sgml/docbook/xsl/1.29/html/docbook.xsl |
57 |
> install.docbook > install.html |
58 |
> |
59 |
> If you want to disable dtd validation use the option --novalid |
60 |
|
61 |
I added two new packages |
62 |
|
63 |
app-text/xmltex an XML parser in tex |
64 |
app-text/passivetex TeX macros for processing FO formatted xml files. |
65 |
|
66 |
Now you can convert docbook xml's to pdf's like this: |
67 |
|
68 |
xsltproc /usr/share/sgml/docbook/xsl/1.29/html/docbook.xsl |
69 |
install.docbook >install.fo |
70 |
pdfxmltex install.fo |
71 |
|
72 |
I get a few errors if I try to convert our install.docbook from |
73 |
pdfxmltex. In this cases I just hitted enter. |
74 |
There are a few problems in the resulting install.pdf. The <article> |
75 |
setion is not supported and the table |
76 |
does not get formated correct. |
77 |
Maybe that problems occure because the passivetex macros where written |
78 |
for another TeX package that tetex. |
79 |
I will try to make a package for that tex system (TeX Live). |
80 |
|
81 |
achim~ |
82 |
|
83 |
> |
84 |
> achim~ |
85 |
> |
86 |
> _______________________________________________ |
87 |
> gentoo-dev mailing list |
88 |
> gentoo-dev@g.o |
89 |
> http://www.gentoo.org/mailman/listinfo/gentoo-dev |