Re: [gentoo-dev] Gentoo Documentation Considerations

drobbins@g.o wrote:
>
> On Sun, Mar 25, 2001 at 06:22:37PM +0200, Achim Gottinger wrote:
>
> > I have a few thoughts how we can handle the documentation for gentoo in a way
> > that we can use it for our webpage and independently for a printable book.
>
> > Now my plan.  We separate the articles from the build packages.  This means
> > we create gentoo-install, gentoo-portage, gentoo-ebuild, gentoo-man which
> > contain either gentoo-xsl or docbook style docs and those docs only get
> > installed to /usr/share/doc/gentoo/[guide|docbook].  Once daniel has finished
> > his gentoo->html xsl stylesheet, I create a gentoo->docbook xsl-sheet.
>
> Yes, I'd like to use "guide" as our official format and use XSLT to convert
> from there.  I can focus on the guide -> HTML XSLT, and if you can focus on
> the guide -> docbook XSLT, then that would be great.  Right now, web page HTML
> documentation is our number one priority, but it would also be nice to use
> "guide" XML as the master file for our man pages.

Can you please make sure that we have the latest xslt-stylesheet on cvs,
I want to write a DTD
for it: :-/

>
> > gentoo-web now can contain an global xml file which is generated dynamic from
> > the content of /usr/share/doc/gentoo/guide. It generates the website-content
> > from this global file.
>
> And I'm guessing that we should design it this way so that I need to remerge
> the actual documentation before it goes "live" on the website?  Because, if
> it pulled the docs directly from /usr/portage instead, then it could be using
> documentation that's currently in development and not yet production-ready?
>
> > gentoo-doc must convert the guide-style files to docbook. After that it
> > generates a global docbook book file and creates prinatble output.
>
> OK, so we have the following XML packages, each one containing a master
> document in "guide" XML format:
>
>                 gentoo-install
>                 gentoo-portage
>                 gentoo-ebuild
>                 gentoo-man
>

In my eyes a chapter of our book. Take a look how I tried to structure
it in gentoo-doc.

> Then, we have two "target" packages that generate content from these packages:
>
>                 gentoo-web
>                 gentoo-doc

These two packages should contain scripts to autogenerate the global xml
files.
Then the documentation packages can call these scripts on postinstall
and prerm.


This way your global xml file is allways actual. Additionaly you can add
automated html generation of changed parts.

This way you must remerge the documentation package to update the
webpage.

We can even extend ebuild to generate a package-guilde-xml file is
/usr/share/doc/gentoo/packages/[category]/[packagename].xml.

This files can contain the DESCRIPTION SRC_URI HOME_PAGE tags and maybe
some additional cvs info. 
Additionaly it can include links to /usr/share/doc/[package] stuff.

This info could be nice to generate online or local basic packge
descriptions in html or even printable.


>
> > This way we have our docs allways up to date on the web and as a book.
>
> Sounds good... I'll need to think about how this will work from the webmaster's
> (my) perspective.
>
> --
> Daniel Robbins                                  <drobbins@g.o>
> President/CEO                                   http://www.gentoo.org
> Gentoo Technologies, Inc.
>
> _______________________________________________
> gentoo-dev mailing list
> gentoo-dev@g.o
> http://www.gentoo.org/mailman/listinfo/gentoo-dev