You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@xml.apache.org by cm...@yahoo.com on 2001/07/16 21:36:45 UTC
+1 to Docbook ( was: Re: -1 to Anakia )
+1 for docbook
It seems we have "old" stylebook, "new" stylebook, "jakarta-site" style
( or however the DTD is called ). AFAIK none of those are clearly
documented or defined - and we have quite a few variations already.
Everyone outside apache is using either DocBook or plain HTML - for the
simple reason that those are the standards. We like to use XML because
it's "standard", but when it comes to the DTDs and tag sets - we invent
our own format(s).
The result of this is visible in the current mess of tag styles and site
generation.
The idea that each project can invent it's own set of tags for
documentations doesn't seem to work very well.
Costin
> > On 7/16/01 12:03 PM, "Davanum Srinivas" <di...@yahoo.com> wrote:
> >
> > > Jason,
> > >
> > > In the long run am ok to using anything to do the docs and site. In the short
> > > term, let us at
> > > least stick to the Stylebook DTD's since every other project in the xml family
> > > are already in this
> > > format. When we decide to move forward, let us push all the projects to move
> > > forward.
> >
> > I would rather wait until c2 is done, I would rather not use another
> > format. I am used to the tags of Anakia, but I fully agree with using
> > standard DocBook tags. I would rather use DocBook tags myself anyway. This
> > is what c2 will accept, yes? If so I would rather go that route. Stylebook
> > is in the past for me and I don't want to use it again.
> >
> > I think that using DocBook as the input is very wise, and I would like
> > to get Anakia using DocBook as there are so many tools for DocBook than
> > at least two apache projects would be using the same format. Geir has
> > wanted to do this for a while but no time. But if we all used DocBook
> > than it doesn't really matter what produces the final output. xml.apache.org
> > can eat its own dogfood, and jakarta.apache.org can do the same.
> >
> > I would be happy to try c2 using DocBook.
>
> Take a look at http://jakarta.apache.org/avalon/developing/index.xml
>
> The whole "Developing with Avalon" book is written in DocBook 4.1 format--
> and uses Cocoon to style the site. It is possible. The only shortcomming
> is autogenerating the Table of Contents (ToC). The approach I used is to
> embed XInclude statements that link to the different Chapters. Every linked
> page is an entry for the ToC. Getting the title from the other files was
> a bit more difficult. I will attempt to try a different approach soon.
>
> It is amazing what Apache products can do right now. I haven't created the
> PDF generation portion yet--but it is only a matter of time.
---------------------------------------------------------------------
In case of troubles, e-mail: webmaster@xml.apache.org
To unsubscribe, e-mail: general-unsubscribe@xml.apache.org
For additional commands, e-mail: general-help@xml.apache.org
Re: +1 to Docbook ( was: Re: -1 to Anakia )
Posted by Robert Koberg <ro...@koberg.com>.
When this discussion started I thought it was about producing documentation
content that people could resuse when they ship their apps. In other words,
if the content was in docbook (even if it wasn't I suppose but its an extra
step), people could package the documentation for xalan, xerces, cocoon with
their own look and feel.
I would like to have that option for what I am doing.
----- Original Message -----
From: <cm...@yahoo.com>
To: <ge...@xml.apache.org>
Sent: Monday, July 16, 2001 12:36 PM
Subject: +1 to Docbook ( was: Re: -1 to Anakia )
> +1 for docbook
>
> It seems we have "old" stylebook, "new" stylebook, "jakarta-site" style
> ( or however the DTD is called ). AFAIK none of those are clearly
> documented or defined - and we have quite a few variations already.
>
> Everyone outside apache is using either DocBook or plain HTML - for the
> simple reason that those are the standards. We like to use XML because
> it's "standard", but when it comes to the DTDs and tag sets - we invent
> our own format(s).
>
> The result of this is visible in the current mess of tag styles and site
> generation.
>
> The idea that each project can invent it's own set of tags for
> documentations doesn't seem to work very well.
>
> Costin
>
>
> > > On 7/16/01 12:03 PM, "Davanum Srinivas" <di...@yahoo.com> wrote:
> > >
> > > > Jason,
> > > >
> > > > In the long run am ok to using anything to do the docs and site. In
the short
> > > > term, let us at
> > > > least stick to the Stylebook DTD's since every other project in the
xml family
> > > > are already in this
> > > > format. When we decide to move forward, let us push all the projects
to move
> > > > forward.
> > >
> > > I would rather wait until c2 is done, I would rather not use another
> > > format. I am used to the tags of Anakia, but I fully agree with using
> > > standard DocBook tags. I would rather use DocBook tags myself anyway.
This
> > > is what c2 will accept, yes? If so I would rather go that route.
Stylebook
> > > is in the past for me and I don't want to use it again.
> > >
> > > I think that using DocBook as the input is very wise, and I would like
> > > to get Anakia using DocBook as there are so many tools for DocBook
than
> > > at least two apache projects would be using the same format. Geir has
> > > wanted to do this for a while but no time. But if we all used DocBook
> > > than it doesn't really matter what produces the final output.
xml.apache.org
> > > can eat its own dogfood, and jakarta.apache.org can do the same.
> > >
> > > I would be happy to try c2 using DocBook.
> >
> > Take a look at http://jakarta.apache.org/avalon/developing/index.xml
> >
> > The whole "Developing with Avalon" book is written in DocBook 4.1
format--
> > and uses Cocoon to style the site. It is possible. The only
shortcomming
> > is autogenerating the Table of Contents (ToC). The approach I used is
to
> > embed XInclude statements that link to the different Chapters. Every
linked
> > page is an entry for the ToC. Getting the title from the other files
was
> > a bit more difficult. I will attempt to try a different approach soon.
> >
> > It is amazing what Apache products can do right now. I haven't created
the
> > PDF generation portion yet--but it is only a matter of time.
>
>
> ---------------------------------------------------------------------
> In case of troubles, e-mail: webmaster@xml.apache.org
> To unsubscribe, e-mail: general-unsubscribe@xml.apache.org
> For additional commands, e-mail: general-help@xml.apache.org
>
---------------------------------------------------------------------
In case of troubles, e-mail: webmaster@xml.apache.org
To unsubscribe, e-mail: general-unsubscribe@xml.apache.org
For additional commands, e-mail: general-help@xml.apache.org
Re: +1 to Docbook ( was: Re: -1 to Anakia )
Posted by Berin Loritsch <bl...@apache.org>.
cmanolache@yahoo.com wrote:
>
> +1 for docbook
>
> It seems we have "old" stylebook, "new" stylebook, "jakarta-site" style
> ( or however the DTD is called ). AFAIK none of those are clearly
> documented or defined - and we have quite a few variations already.
>
> The result of this is visible in the current mess of tag styles and site
> generation.
By using DocBook, we will also be able to use WYSIWYG programs designed for
DocBook. And then there is the decreased learning curve by all new documentors.
I think there is another benefit, if we decide to use Cocoon 2. We can set
up one general sitemap for the whole site, and make sure that all documentation
is generated with the same markup. Cocoon allows the addition of sub-sitemaps,
but even if we have separate "contexts" for each project--it just becomes so much
simpler to manage.
If Jakarta or XML sites decided that the current _very_ table heavy site design
can be simplified--the one set of stylesheets will benefit all the associated
projects. You see how it all works together?
Re: +1 to Docbook ( was: Re: -1 to Anakia )
Posted by Norman Walsh <nd...@nwalsh.com>.
/ <cm...@yahoo.com> was heard to say:
| +1 for docbook
+1 (if non-committers can vote :-)
As the chair of the DocBook Technical Committee at OASIS, principal
author of DocBook: The Definitive Guide, and primary contributor to
the DocBook XSL Stylesheet distribution
(http://sourceforge.net/projects/docbook), I'd be happy to answer any
DocBook questions that might arise. (For fastest service, please use
one of the DocBook lists, docbook@lists.oasis-open.org for general
questions and docbook-apps@lists.oasis-open.org for stylesheet and
tool questions.
Let me also add, up front, that DocBook is still evolving (though
slowly, as we like to think it's reached maturity) and additional
requirements and requests for enhancement are welcome.
Be seeing you,
norm
--
Norman.Walsh@Sun.COM | Sites disappear; others are created. That
XML Standards Engineer | nasty little railway station, devoid of taste
Technology Dev. Group | and style, becomes an element of beauty in the
Sun Microsystems, Inc. | landscape which first made it ugly.--R\'emy De
| Gourmont
---------------------------------------------------------------------
In case of troubles, e-mail: webmaster@xml.apache.org
To unsubscribe, e-mail: general-unsubscribe@xml.apache.org
For additional commands, e-mail: general-help@xml.apache.org
Re: +1 to Docbook ( was: Re: -1 to Anakia )
Posted by Norman Walsh <nd...@nwalsh.com>.
/ Donald Ball <ba...@webslingerZ.com> was heard to say:
| the only problem with using docbook is that it's a huge language, and
| writing a stylesheet to transform arbitrary docbook documents into
| something else is a non-trivial undertaking. if we restrict ourselves to
| using a strict documented subset of docbook, i'd consider it, but i don't
| have the time to undertake that project.
See if Simplified DocBook is enough for what you need:
http://www.oasis-open.org/docbook/xml/simple/
Be seeing you,
norm
--
Norman.Walsh@Sun.COM | No matter how cynical I get, I find I just
XML Standards Engineer | can't keep up.--Lily Tomlin
Technology Dev. Group |
Sun Microsystems, Inc. |
---------------------------------------------------------------------
In case of troubles, e-mail: webmaster@xml.apache.org
To unsubscribe, e-mail: general-unsubscribe@xml.apache.org
For additional commands, e-mail: general-help@xml.apache.org
Re: +1 to Docbook ( was: Re: -1 to Anakia )
Posted by Berin Loritsch <bl...@apache.org>.
Donald Ball wrote:
>
> the only problem with using docbook is that it's a huge language, and
> writing a stylesheet to transform arbitrary docbook documents into
> something else is a non-trivial undertaking. if we restrict ourselves to
> using a strict documented subset of docbook, i'd consider it, but i don't
> have the time to undertake that project.
Well, I have a start that works for Jakarta.apache.org. It can be increased
as needed.
It should be used as the basis of writing new styles for DocBook.
I will be checking it into Avalon's CVS as soon as I get the build system
working.
Re: +1 to Docbook ( was: Re: -1 to Anakia )
Posted by Donald Ball <ba...@webslingerZ.com>.
On Mon, 16 Jul 2001 cmanolache@yahoo.com wrote:
> +1 for docbook
>
> It seems we have "old" stylebook, "new" stylebook, "jakarta-site" style
> ( or however the DTD is called ). AFAIK none of those are clearly
> documented or defined - and we have quite a few variations already.
er, the 'stylebook document' format is very specifically documented, at
least in the cocoon repository - check out the dtds. anyways, it's
basically x/html with a few extra structural elements added for good
measure.
> Everyone outside apache is using either DocBook or plain HTML - for the
> simple reason that those are the standards. We like to use XML because
> it's "standard", but when it comes to the DTDs and tag sets - we invent
> our own format(s).
>
> The result of this is visible in the current mess of tag styles and site
> generation.
>
> The idea that each project can invent it's own set of tags for
> documentations doesn't seem to work very well.
the only problem with using docbook is that it's a huge language, and
writing a stylesheet to transform arbitrary docbook documents into
something else is a non-trivial undertaking. if we restrict ourselves to
using a strict documented subset of docbook, i'd consider it, but i don't
have the time to undertake that project.
- donald
---------------------------------------------------------------------
In case of troubles, e-mail: webmaster@xml.apache.org
To unsubscribe, e-mail: general-unsubscribe@xml.apache.org
For additional commands, e-mail: general-help@xml.apache.org