[gentoo-dev] Gentoo Documentation Considerations

[gentoo-dev] Gentoo Documentation Considerations

[Achim Gottinger]

Hi devs,

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.

At the moment we have two packages in app-doc

gentoo-web contains daniels gentoo-xsl style docs and stylesheets to
convert them to html
gentoo-doc contains docbook-sgml style docs which can be converted  with
dsssl stylesheets 
           to html,pdf,ps,man

Both packages contain the daniels install docs and petes Gentoo-HOWTO.

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.

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.

gentoo-doc must convert the guide-style files to docbook. After that it
generates a global docbook book
           file and creates prinatble output.

This way we have our docs allways up to date on the web and as a book.

achim~

Re: [gentoo-dev] Gentoo Documentation Considerations

[drobbins]

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.

> 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

Then, we have two "target" packages that generate content from these packages:

		gentoo-web
		gentoo-doc

> 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@gentoo.org>
President/CEO					http://www.gentoo.org 
Gentoo Technologies, Inc.			

Re: [gentoo-dev] Gentoo Documentation Considerations

[Achim Gottinger]

drobbins@gentoo.org 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@gentoo.org>
> President/CEO                                   http://www.gentoo.org
> Gentoo Technologies, Inc.
> 
> _______________________________________________
> gentoo-dev mailing list
> gentoo-dev@gentoo.org
> http://www.gentoo.org/mailman/listinfo/gentoo-dev

Re: [gentoo-dev] Gentoo Documentation Considerations

[drobbins]

On Sun, Mar 25, 2001 at 07:53:07PM +0200, Achim Gottinger wrote:

> > 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: :-/

I'm working on guide-new.xsl on cvs, and I have an accompanying install-new.xml
that uses it.  Should be done in a day or two, at which point I can document it
(using guide, of course) and then you can start writing a DTD for it... oh, by
the way... thank you thank you thank you!!! :)

-- 
Daniel Robbins					<drobbins@gentoo.org>
President/CEO					http://www.gentoo.org 
Gentoo Technologies, Inc.