1 |
drobbins@g.o wrote: |
2 |
> |
3 |
> On Sun, Mar 25, 2001 at 06:22:37PM +0200, Achim Gottinger wrote: |
4 |
> |
5 |
> > I have a few thoughts how we can handle the documentation for gentoo in a way |
6 |
> > that we can use it for our webpage and independently for a printable book. |
7 |
> |
8 |
> > Now my plan. We separate the articles from the build packages. This means |
9 |
> > we create gentoo-install, gentoo-portage, gentoo-ebuild, gentoo-man which |
10 |
> > contain either gentoo-xsl or docbook style docs and those docs only get |
11 |
> > installed to /usr/share/doc/gentoo/[guide|docbook]. Once daniel has finished |
12 |
> > his gentoo->html xsl stylesheet, I create a gentoo->docbook xsl-sheet. |
13 |
> |
14 |
> Yes, I'd like to use "guide" as our official format and use XSLT to convert |
15 |
> from there. I can focus on the guide -> HTML XSLT, and if you can focus on |
16 |
> the guide -> docbook XSLT, then that would be great. Right now, web page HTML |
17 |
> documentation is our number one priority, but it would also be nice to use |
18 |
> "guide" XML as the master file for our man pages. |
19 |
|
20 |
Can you please make sure that we have the latest xslt-stylesheet on cvs, |
21 |
I want to write a DTD |
22 |
for it: :-/ |
23 |
|
24 |
> |
25 |
> > gentoo-web now can contain an global xml file which is generated dynamic from |
26 |
> > the content of /usr/share/doc/gentoo/guide. It generates the website-content |
27 |
> > from this global file. |
28 |
> |
29 |
> And I'm guessing that we should design it this way so that I need to remerge |
30 |
> the actual documentation before it goes "live" on the website? Because, if |
31 |
> it pulled the docs directly from /usr/portage instead, then it could be using |
32 |
> documentation that's currently in development and not yet production-ready? |
33 |
> |
34 |
> > gentoo-doc must convert the guide-style files to docbook. After that it |
35 |
> > generates a global docbook book file and creates prinatble output. |
36 |
> |
37 |
> OK, so we have the following XML packages, each one containing a master |
38 |
> document in "guide" XML format: |
39 |
> |
40 |
> gentoo-install |
41 |
> gentoo-portage |
42 |
> gentoo-ebuild |
43 |
> gentoo-man |
44 |
> |
45 |
|
46 |
In my eyes a chapter of our book. Take a look how I tried to structure |
47 |
it in gentoo-doc. |
48 |
|
49 |
> Then, we have two "target" packages that generate content from these packages: |
50 |
> |
51 |
> gentoo-web |
52 |
> gentoo-doc |
53 |
|
54 |
These two packages should contain scripts to autogenerate the global xml |
55 |
files. |
56 |
Then the documentation packages can call these scripts on postinstall |
57 |
and prerm. |
58 |
|
59 |
|
60 |
This way your global xml file is allways actual. Additionaly you can add |
61 |
automated html generation of changed parts. |
62 |
|
63 |
This way you must remerge the documentation package to update the |
64 |
webpage. |
65 |
|
66 |
We can even extend ebuild to generate a package-guilde-xml file is |
67 |
/usr/share/doc/gentoo/packages/[category]/[packagename].xml. |
68 |
|
69 |
This files can contain the DESCRIPTION SRC_URI HOME_PAGE tags and maybe |
70 |
some additional cvs info. |
71 |
Additionaly it can include links to /usr/share/doc/[package] stuff. |
72 |
|
73 |
This info could be nice to generate online or local basic packge |
74 |
descriptions in html or even printable. |
75 |
|
76 |
|
77 |
> |
78 |
> > This way we have our docs allways up to date on the web and as a book. |
79 |
> |
80 |
> Sounds good... I'll need to think about how this will work from the webmaster's |
81 |
> (my) perspective. |
82 |
> |
83 |
> -- |
84 |
> Daniel Robbins <drobbins@g.o> |
85 |
> President/CEO http://www.gentoo.org |
86 |
> Gentoo Technologies, Inc. |
87 |
> |
88 |
> _______________________________________________ |
89 |
> gentoo-dev mailing list |
90 |
> gentoo-dev@g.o |
91 |
> http://www.gentoo.org/mailman/listinfo/gentoo-dev |