[gentoo-dev] Gentoo Linux documentation

[gentoo-dev] Gentoo Linux documentation

[drobbins]

Hi All,

In a few days, we're going to start an official documentation rampage, lasting
about a week.  Hopefully, in that time, we can get a whole bunch of
documentation done and on the website.  Fortunately, I'm writing an article for
IBM on the website redesign, so I can devote some time to documentation.
However, this does mean that our doc solution will be scrutinized by the world,
but I figured we're up to the task.

For a refresher, this is what everybody seems to be in agreement upon:

1. The documentation should be composed in XML.
2. We should use XSLT to translate the XML documentation into web-ready HTML.

However, we still haven't decided which XML approach to use:

a. Use our own custom "guide" format designed for our needs
b. Use the already complete docbook format for our XML

In my eyes, the advantage of a custom guide format is that it is much easier to
change/upgrade if we need new features, and is definitely going to have a
simpler, more HTML-like syntax.

The advantage of the docbook format is that it's a standard (for technical
documentation), and has a lot of features.  The downside of this is that we are
less in control of the format and we will need to learn the "docbook way" of
doing things.  Another concern about docbook -- since it has a lot more tags
than our lightweight guide format, writing docbook --> HTML XSL transforms could
be *very* cumbersome, since we will have to support all docbook tags :(  This
appears to be the major drawback to docbook -- its DTD is *huge*.

example docbook XML:

/usr/portage/app-doc/gentoo-doc/files/install.docbook

example guide (beta) XML:

/usr/portage/app-doc/gentoo-web/files/xml/install.xml

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

Re: [gentoo-dev] Gentoo Linux documentation

[S. Murthy Kambhampaty]

On 16 Mar 2001 14:48:31 -0700, drobbins@gentoo.org wrote:
> However, we still haven't decided which XML approach to use:
> 
> a. Use our own custom "guide" format designed for our needs
> b. Use the already complete docbook format for our XML
> 
Why not use your "guide" xml for now, and then transform it to DocBook when you think you're ready.  Writing the "guide" to "DocBook" transform may be your avenue to learning DocBook to boot, eh?

Murthy


_________________________________________________________
Do You Yahoo!?
Get your free @yahoo.com address at http://mail.yahoo.com

Re: [gentoo-dev] Gentoo Linux documentation

[drobbins]

On Fri, Mar 16, 2001 at 05:43:19PM -0500, S. Murthy Kambhampaty wrote:
> > However, we still haven't decided which XML approach to use:
> > 
> > a. Use our own custom "guide" format designed for our needs
> > b. Use the already complete docbook format for our XML
> > 

> Why not use your "guide" xml for now, and then transform it to DocBook when
> you think you're ready.  Writing the "guide" to "DocBook" transform may be
> your avenue to learning DocBook to boot, eh?

True.  I think that's a good way to look at it.

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

Re: [gentoo-dev] Gentoo Linux documentation

[Achim Gottinger]

drobbins@gentoo.org wrote:
> 
> Hi All,
> 
> In a few days, we're going to start an official documentation rampage, lasting
> about a week.  Hopefully, in that time, we can get a whole bunch of
> documentation done and on the website.  Fortunately, I'm writing an article for
> IBM on the website redesign, so I can devote some time to documentation.
> However, this does mean that our doc solution will be scrutinized by the world,
> but I figured we're up to the task.
> 
> For a refresher, this is what everybody seems to be in agreement upon:
> 
> 1. The documentation should be composed in XML.
> 2. We should use XSLT to translate the XML documentation into web-ready HTML.
> 
> However, we still haven't decided which XML approach to use:
> 
> a. Use our own custom "guide" format designed for our needs
> b. Use the already complete docbook format for our XML
> 
> In my eyes, the advantage of a custom guide format is that it is much easier to
> change/upgrade if we need new features, and is definitely going to have a
> simpler, more HTML-like syntax.
> 
> The advantage of the docbook format is that it's a standard (for technical
> documentation), and has a lot of features.  The downside of this is that we are
> less in control of the format and we will need to learn the "docbook way" of
> doing things.  Another concern about docbook -- since it has a lot more tags
> than our lightweight guide format, writing docbook --> HTML XSL transforms could
> be *very* cumbersome, since we will have to support all docbook tags :(  This
> appears to be the major drawback to docbook -- its DTD is *huge*.

There is a lite version of docbook which is not that huge.
I'm currently making packages for the docbook-xml-dtd's and
docbook(-lite) xsl's.
You should be able to test them in a few hours.

It's true docbook transformation need much time with these xsl's. But
since we do not use dynamic XML generation time should not be the
problem.

Another thing. I want to make two new categories:

- app-spell: (for i/a/pspell, their backendsand the dictionaries.
- app-ml: for all the xml/sgml/html whatever ml stuff.

Or should ml be a new major categorie with ml-apps and ml-libs
subcategories?
Then we can put stuff like libwww, libxslt, libxml in ml-libs. And
things like
jade, sablotron, and all the sgml-tools to ml-apps.

achim~



> 
> example docbook XML:
> 
> /usr/portage/app-doc/gentoo-doc/files/install.docbook
> 
> example guide (beta) XML:
> 
> /usr/portage/app-doc/gentoo-web/files/xml/install.xml
> 
> --
> 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 Linux documentation

[Achim Gottinger]

Achim Gottinger wrote:
> 
> drobbins@gentoo.org wrote:
> >
> > Hi All,
> >
> > In a few days, we're going to start an official documentation rampage, lasting
> > about a week.  Hopefully, in that time, we can get a whole bunch of
> > documentation done and on the website.  Fortunately, I'm writing an article for
> > IBM on the website redesign, so I can devote some time to documentation.
> > However, this does mean that our doc solution will be scrutinized by the world,
> > but I figured we're up to the task.
> >
> > For a refresher, this is what everybody seems to be in agreement upon:
> >
> > 1. The documentation should be composed in XML.
> > 2. We should use XSLT to translate the XML documentation into web-ready HTML.
> >
> > However, we still haven't decided which XML approach to use:
> >
> > a. Use our own custom "guide" format designed for our needs
> > b. Use the already complete docbook format for our XML
> >
> > In my eyes, the advantage of a custom guide format is that it is much easier to
> > change/upgrade if we need new features, and is definitely going to have a
> > simpler, more HTML-like syntax.
> >
> > The advantage of the docbook format is that it's a standard (for technical
> > documentation), and has a lot of features.  The downside of this is that we are
> > less in control of the format and we will need to learn the "docbook way" of
> > doing things.  Another concern about docbook -- since it has a lot more tags
> > than our lightweight guide format, writing docbook --> HTML XSL transforms could
> > be *very* cumbersome, since we will have to support all docbook tags :(  This
> > appears to be the major drawback to docbook -- its DTD is *huge*.
> 
> There is a lite version of docbook which is not that huge.
> I'm currently making packages for the docbook-xml-dtd's and
> docbook(-lite) xsl's.
> You should be able to test them in a few hours.

I have commited all the required packages. You will need

app-text/docbook-xml DTD's 
app-text/docbook-xml-simplified DTD's 
app-text/docbook-xsl XSL Stylesheets for XML->HTML and XML->FO
transformation

gnome-libs/libxml2 required for libxslt
gnome-libs/libxslt includes the required xsltproc.

Once you have installed all these, you can transform install.docbook to
html with the following command:

xsltproc /usr/share/sgml/docbook/xsl/1.29/html/docbook.xsl
install.docbook > install.html

If you want to disable dtd validation use the option --novalid

achim~

Re: [gentoo-dev] Gentoo Linux documentation

[Achim Gottinger]

Achim Gottinger wrote:
> 
> Achim Gottinger wrote:
> >
> > drobbins@gentoo.org wrote:
> > >
> > > Hi All,
> > >
> > > In a few days, we're going to start an official documentation rampage, lasting
> > > about a week.  Hopefully, in that time, we can get a whole bunch of
> > > documentation done and on the website.  Fortunately, I'm writing an article for
> > > IBM on the website redesign, so I can devote some time to documentation.
> > > However, this does mean that our doc solution will be scrutinized by the world,
> > > but I figured we're up to the task.
> > >
> > > For a refresher, this is what everybody seems to be in agreement upon:
> > >
> > > 1. The documentation should be composed in XML.
> > > 2. We should use XSLT to translate the XML documentation into web-ready HTML.
> > >
> > > However, we still haven't decided which XML approach to use:
> > >
> > > a. Use our own custom "guide" format designed for our needs
> > > b. Use the already complete docbook format for our XML
> > >
> > > In my eyes, the advantage of a custom guide format is that it is much easier to
> > > change/upgrade if we need new features, and is definitely going to have a
> > > simpler, more HTML-like syntax.
> > >
> > > The advantage of the docbook format is that it's a standard (for technical
> > > documentation), and has a lot of features.  The downside of this is that we are
> > > less in control of the format and we will need to learn the "docbook way" of
> > > doing things.  Another concern about docbook -- since it has a lot more tags
> > > than our lightweight guide format, writing docbook --> HTML XSL transforms could
> > > be *very* cumbersome, since we will have to support all docbook tags :(  This
> > > appears to be the major drawback to docbook -- its DTD is *huge*.
> >
> > There is a lite version of docbook which is not that huge.
> > I'm currently making packages for the docbook-xml-dtd's and
> > docbook(-lite) xsl's.
> > You should be able to test them in a few hours.
> 
> I have commited all the required packages. You will need
> 
> app-text/docbook-xml DTD's
> app-text/docbook-xml-simplified DTD's
> app-text/docbook-xsl XSL Stylesheets for XML->HTML and XML->FO
> transformation
> 
> gnome-libs/libxml2 required for libxslt
> gnome-libs/libxslt includes the required xsltproc.
> 
> Once you have installed all these, you can transform install.docbook to
> html with the following command:
> 
> xsltproc /usr/share/sgml/docbook/xsl/1.29/html/docbook.xsl
> install.docbook > install.html
> 
> If you want to disable dtd validation use the option --novalid

I added two new packages

app-text/xmltex 	an XML parser in tex
app-text/passivetex	TeX macros for processing FO formatted xml files.

Now you can convert docbook xml's to pdf's like this:

xsltproc /usr/share/sgml/docbook/xsl/1.29/html/docbook.xsl
install.docbook >install.fo
pdfxmltex install.fo

I get a few errors if I try to convert our install.docbook from
pdfxmltex. In this cases I just hitted enter.
There are a few problems in the resulting install.pdf. The <article>
setion is not supported and the table
does not get formated correct.
Maybe that problems occure because the passivetex macros where written
for another TeX package that tetex.
I will  try to make a package for that tex system (TeX Live). 

achim~

> 
> achim~
> 
> _______________________________________________
> gentoo-dev mailing list
> gentoo-dev@gentoo.org
> http://www.gentoo.org/mailman/listinfo/gentoo-dev

Re: [gentoo-dev] Gentoo Linux documentation

[drobbins]

On Sat, Mar 17, 2001 at 07:03:51PM +0100, Achim Gottinger wrote:

> It's true docbook transformation need much time with these xsl's. But
> since we do not use dynamic XML generation time should not be the
> problem.

I think that a docbook-lite format could work.  My concern with docbook
wasn't as much the additional processing power needed, but the additional
hours and hours that may be needed to write our own XSLT to conver docbook
to our desired HTML format.  When designing the XSLT, it would seem that
having only the XML tags we need (and no more) would be an advantage.

Best Regards,

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

Re: [gentoo-dev] Gentoo Linux documentation

[Achim Gottinger]

drobbins@gentoo.org wrote:
> 
> On Sat, Mar 17, 2001 at 07:03:51PM +0100, Achim Gottinger wrote:
> 
> > It's true docbook transformation need much time with these xsl's. But
> > since we do not use dynamic XML generation time should not be the
> > problem.
> 
> I think that a docbook-lite format could work.  My concern with docbook
> wasn't as much the additional processing power needed, but the additional
> hours and hours that may be needed to write our own XSLT to conver docbook
> to our desired HTML format.  When designing the XSLT, it would seem that
> having only the XML tags we need (and no more) would be an advantage.
> 
If you take a look at the html output, you will see that all tags have a
name or class element. 
So using a local stylesheet should be ok for the beginning.

BTW: There is a new package app-text/docbook2X which can be used to
convert docbook to man and info
pages. It uses alot of perl XML modules and internaly uses XML::DOM and
not XML::Sablotron or XML::LibXSLT

Maybe we can extend this package to amke use of the newer parsers and
add html and fo output (maybe pdf too)
to it.
Then we would have a nice frontend docs.

achim~

> Best Regards,
> 
> --
> 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 Linux documentation

[drobbins]

On Sat, Mar 17, 2001 at 07:03:51PM +0100, Achim Gottinger wrote:

> Another thing. I want to make two new categories:

> - app-spell: (for i/a/pspell, their backendsand the dictionaries.
> - app-ml: for all the xml/sgml/html whatever ml stuff.

> Or should ml be a new major categorie with ml-apps and ml-libs subcategories?
> Then we can put stuff like libwww, libxslt, libxml in ml-libs. And things
> like jade, sablotron, and all the sgml-tools to ml-apps.

Since "ml" reminds me of "machine language", how about these categories:

markup-apps
markup-libs

???

Maybe ml is better.

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

Re: [gentoo-dev] Gentoo Linux documentation

[Achim Gottinger]

drobbins@gentoo.org wrote:
> 
> On Sat, Mar 17, 2001 at 07:03:51PM +0100, Achim Gottinger wrote:
> 
> > Another thing. I want to make two new categories:
> 
> > - app-spell: (for i/a/pspell, their backendsand the dictionaries.
> > - app-ml: for all the xml/sgml/html whatever ml stuff.
> 
> > Or should ml be a new major categorie with ml-apps and ml-libs subcategories?
> > Then we can put stuff like libwww, libxslt, libxml in ml-libs. And things
> > like jade, sablotron, and all the sgml-tools to ml-apps.
> 
> Since "ml" reminds me of "machine language", how about these categories:
> 
> markup-apps
> markup-libs
> 
> ???
> 
> Maybe ml is better.
Hmm I'm still thinking about a category name that merges markup
languages with tes related stuff.

Yesterday I reworked the sgml related part of docbook. This produces now
quite better output results 
than the xsl way.
The following output's now work fine: html, dvi, pdf, ps, tex
I had to hack the plain-text backend so text should worke fine once I
commited my changes.
I have still problems producing man and texi output (They both depend on
the perl package SGMLSpm, maybe this is buggy).

Here is a list of packages required to handle sgml docbook stuff:

sgml-common:			Includes basic entitie definitions and a script to manage
catalogs.
docbook-sgml-dtd:		Includes docbook SGML DTD's 
docbook-dsssl-stylesheets:	Includes the conversion stylesheets 

openjade:	Does the conversion job
jadetex:	Is required to produce the dvi pdf ps output.


docbook-sgml-utils:		Includes conversion stylesheets and scripts for
conversion (docbook2html, ...)

Here is a list of packages required to handle sgml docbook stuff:

docbook-xml-dtd:	 The XML DTD's
docbook-xml-simple-dtd:	 The XML DTD's for simplified docbook (100
instead of 300 entities)
docbook-xsl-stylesheets: XSLT Stylesheets for html and fo output
(Coming soon: docbook-xml-2X:	Stylesheets and scripts to convert
xml-docbook to man and texi)
xmltex:		An xml parser for tex.
passivetex:	Macros required to convert fo to pdf and tex.

libxslt:	Includes the xslt parser.

The sgml-packages now add and remove their catalogs from a centralized
catalog.
This is a LSB conform handling of catalogs.

All cataolges get stored in /etc/sgml

There is one global catalog that keeps all the other centralized
catalogs. called "catlog".

The three packages sgml-common, docbook-dsssl-stylesheets and openjade
create the catalogs

sgml-ent, dsssl-docbook-stylesheets and openjade-1.3.

They add their centralized catalog to a catalog named
/etc/sgml/sgml-docbook.cat.

The docbook-sgml-dtd packages creates an centralized catalog called
/etc/sgml/sgml-docbook-{3,4}.[0,1}.cat
and add the global sgml-docbook.cat to that version specific catalog.

The docbook utils scan the sgml input for the doctype and use the
matching sgml-docbook catalog automatic.
These utils also detect if the input is and xml file. In this case it
wants to use /etc/sgml/xml-docbook-{PV}.cat. Not working, because the
XML way of handling docbook files does not use catalog
files.

All the sgml dtd's, stylesheets and internal scripts go to
/usr/share/sgml/.
All the names I used for the subdirs are LSB convorm.

I renamed a few packages to be more LSB convorm and to work with the
dependencies system.

Bye Achim



> --
> 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 Linux documentation

[Achim Gottinger]

Hi again,

I commited all the packages listed in my last mail to the cvs-tree.
Additionaly I made a modification to the kdelibs package to install
their docbook stylesheets to /usr/share/sgml/docbook/kde-customizations
and to create a centralized catalog /etc/sgml/kde-docbook which includes
the sgml-docbook catalog.


I finished rc4 reworking of all app-text packages today. Take a look at
current-packages.rc4 to see to progress. 

I'm currently working on packages for gcc-2.95.3 and xfree-4.0.3.

Bye achim~

Re: [gentoo-dev] Gentoo Linux documentation

[Achim Gottinger]

Hi again,

I added another package app-text/psgml which can be used to edit
sgml/xml files in emacs.
I made a dot_emacs file which gets installed in the docs subdir. Merge
it
to your local .emacs file and it should work.

I commited the latest gcc and xfree packages too. But I have not heavily 
tested them yet.
Atleast xfree still runs with antialiased fonts after I updated gcc and
then build xfree with that.

achim~

Re: [gentoo-dev] Gentoo Linux documentation

[Achim Gottinger]

Hi again,

I currently played around with the LinuxDoc dtd's and stylesheets and
think we should use them.
The tags are simplified and more html like than docbook's. Additionally
it can be converted to docbook format.

You will find a short intro to docbook at
http://www.linuxdoc.org/LDP/LDP-Author-Guide/
and for LinuxDoc
http://www.linuxdoc.org/HOWTO/mini/Howtos-with-LinuxDoc.html

Comments please. :-)

bye achim