You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tuscany.apache.org by Jim Marino <jm...@myromatours.com> on 2006/07/13 03:04:26 UTC
Chianti extension manual
I've started a manual for extending Chianti. It's obviously very
rough and missing many pieces but comments and contributions are
welcome. If you plan on editing it, please let me know so we don't
collide.
Also, this is a good point to raise the question of how we want to
construct user manuals. I seem to recall Hibernate having a good
process which results in the output of multiple formats, including
pdf, single page html, and multi-page html. Any suggestions? For the
time being, I've left it in Word but plan to switch to a more "open"
format.
Jim
---------------------------------------------------------------------
To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: tuscany-dev-help@ws.apache.org
Re: Chianti extension manual
Posted by Jim Marino <jm...@myromatours.com>.
Yea I've seen other projects use this. What would be nice is if we
could write using a word processor instead of an xml editor and have
it converted to DocBook. I'll have to check into this but if someone
has experience doing this sort of thing, it would be good to know.
Jim
On Jul 20, 2006, at 2:07 AM, Eric Le Goff wrote:
> Let's try and summarize docbook features :
>
> DocBook is an XML vocabulary designed for computer
> documentation.DocBook has historically been SGML, but DocBook 4 is
> supported in XML and SGML DTDs.
>
> It is the work product of an OASIS Technical Committee [1]
>
> I started learning it from [2], just like writing a simple book :
>
> <book id="simple_book">
> <title>Very simple book</title>
> <chapter id="simplechapter">
> <title>Chapter 1</title>
> <para>Hello world!</para>
> </chapter>
> </book>
>
> then learned more advanced syntax fro a reference card [3].
>
> You can write technical documents with Open Office, and save them in
> html or pdf.
> But the interest of DocBook is in separating data and presenting, the
> possibility to create automatically documents, and the ability to
> generate documents from databases. Can convert them to html or pdf
> also.
> You can also process the data in several ways (extracting, multiple
> views, etc...)
>
> DocBook is now used for the documentation of Linux and FreeBSD.
>
> I think people wrote a maven plugin for docbook generation [4]
>
> A text may be edited directly, or with a graphical editor (see [5],
> [6]). I personnaly use Emacs with psgml mode as described here [8],
> but I also know some people using OpenOffice as an editor [8]
>
> For a manual conversion process, some tools are required:
> * The DocBook DTD
> * The XSL DocBook style sheet.
> * The XSLT processor.
>
> Some style sheet allows to produce HTML or XSL-FO from a DocBook
> document.
>
> With the FOP program and the XSL-FO [9] , a pdf file is created with
> this command (in one line):
> java org.apache.fop.apps.Fop
> -xml myfile.xml
> -xsl DocBook-xsl/fo/DocBook.xsl
> -pdf myfile.pdf
>
> Aaron Mulder from the Apache Geronimo team wrote a book available in
> several formats [10] and I suppose he had used Docbook. He might
> confirm how useful it is to use this format to generate docs...or give
> us hid feedback, pros and cons of such a tool in the context of an
> incubating Apache project...
>
> Regards
>
>
>
> [1] http://www.oasis-open.org/docbook/
> [2] http://camille.begnis.org/publications/DocBook/DocBook-Starter-
> Kit.tar.bz2
> [3] http://www.dpawson.co.uk/docbook/docbookref.pdf
> [4] http://mojo.codehaus.org/docbook-maven-plugin/
> [5] http://www.xmlmind.com/
> [6] http://www.lyx.org/
> [7] http://fedora.redhat.com/docs/documentation-guide/
> [8] http://xml.openoffice.org/xmerge/docbook/UserGuide.html
> [9] http://xmlgraphics.apache.org/fop/
> [10] http://chariotsolutions.com/geronimo/
>
> --
> Eric LE GOFF
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
> For additional commands, e-mail: tuscany-dev-help@ws.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: tuscany-dev-help@ws.apache.org
Re: Chianti extension manual
Posted by Eric Le Goff <el...@gmail.com>.
Let's try and summarize docbook features :
DocBook is an XML vocabulary designed for computer
documentation.DocBook has historically been SGML, but DocBook 4 is
supported in XML and SGML DTDs.
It is the work product of an OASIS Technical Committee [1]
I started learning it from [2], just like writing a simple book :
<book id="simple_book">
<title>Very simple book</title>
<chapter id="simplechapter">
<title>Chapter 1</title>
<para>Hello world!</para>
</chapter>
</book>
then learned more advanced syntax fro a reference card [3].
You can write technical documents with Open Office, and save them in
html or pdf.
But the interest of DocBook is in separating data and presenting, the
possibility to create automatically documents, and the ability to
generate documents from databases. Can convert them to html or pdf
also.
You can also process the data in several ways (extracting, multiple
views, etc...)
DocBook is now used for the documentation of Linux and FreeBSD.
I think people wrote a maven plugin for docbook generation [4]
A text may be edited directly, or with a graphical editor (see [5],
[6]). I personnaly use Emacs with psgml mode as described here [8],
but I also know some people using OpenOffice as an editor [8]
For a manual conversion process, some tools are required:
* The DocBook DTD
* The XSL DocBook style sheet.
* The XSLT processor.
Some style sheet allows to produce HTML or XSL-FO from a DocBook document.
With the FOP program and the XSL-FO [9] , a pdf file is created with
this command (in one line):
java org.apache.fop.apps.Fop
-xml myfile.xml
-xsl DocBook-xsl/fo/DocBook.xsl
-pdf myfile.pdf
Aaron Mulder from the Apache Geronimo team wrote a book available in
several formats [10] and I suppose he had used Docbook. He might
confirm how useful it is to use this format to generate docs...or give
us hid feedback, pros and cons of such a tool in the context of an
incubating Apache project...
Regards
[1] http://www.oasis-open.org/docbook/
[2] http://camille.begnis.org/publications/DocBook/DocBook-Starter-Kit.tar.bz2
[3] http://www.dpawson.co.uk/docbook/docbookref.pdf
[4] http://mojo.codehaus.org/docbook-maven-plugin/
[5] http://www.xmlmind.com/
[6] http://www.lyx.org/
[7] http://fedora.redhat.com/docs/documentation-guide/
[8] http://xml.openoffice.org/xmerge/docbook/UserGuide.html
[9] http://xmlgraphics.apache.org/fop/
[10] http://chariotsolutions.com/geronimo/
--
Eric LE GOFF
---------------------------------------------------------------------
To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: tuscany-dev-help@ws.apache.org
Re: Chianti extension manual
Posted by kelvin goodson <ke...@thegoodsons.org.uk>.
Eric, I had a quick look at the DocBook site, but it lacks an overview,
and the links to the online html versions of the books seem to be
unavailable. I could see the schemata that clearly describe documentation
layout, but I couldn't get an idea of what tooling was available to edit
and produce the documentation. Can you summarise its features?
Cheers, Kelvin.
On 7/17/06, Eric Le Goff <el...@gmail.com> wrote:
>
> I guess docbook (http://www.docbook.org/) is often used for this kind of
> docs
> My 2 cents.
>
> On 7/13/06, Jim Marino <jm...@myromatours.com> wrote:
> > I've started a manual for extending Chianti. It's obviously very
> > rough and missing many pieces but comments and contributions are
> > welcome. If you plan on editing it, please let me know so we don't
> > collide.
> >
> > Also, this is a good point to raise the question of how we want to
> > construct user manuals. I seem to recall Hibernate having a good
> > process which results in the output of multiple formats, including
> > pdf, single page html, and multi-page html. Any suggestions? For the
> > time being, I've left it in Word but plan to switch to a more "open"
> > format.
> >
> > Jim
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
> > For additional commands, e-mail: tuscany-dev-help@ws.apache.org
> >
> >
>
>
> --
> Eric LE GOFF
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
> For additional commands, e-mail: tuscany-dev-help@ws.apache.org
>
>
--
Best Regards
Kelvin Goodson
Re: Chianti extension manual
Posted by Eric Le Goff <el...@gmail.com>.
I guess docbook (http://www.docbook.org/) is often used for this kind of docs
My 2 cents.
On 7/13/06, Jim Marino <jm...@myromatours.com> wrote:
> I've started a manual for extending Chianti. It's obviously very
> rough and missing many pieces but comments and contributions are
> welcome. If you plan on editing it, please let me know so we don't
> collide.
>
> Also, this is a good point to raise the question of how we want to
> construct user manuals. I seem to recall Hibernate having a good
> process which results in the output of multiple formats, including
> pdf, single page html, and multi-page html. Any suggestions? For the
> time being, I've left it in Word but plan to switch to a more "open"
> format.
>
> Jim
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
> For additional commands, e-mail: tuscany-dev-help@ws.apache.org
>
>
--
Eric LE GOFF
---------------------------------------------------------------------
To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: tuscany-dev-help@ws.apache.org
Re: Chianti extension manual
Posted by Raymond Feng <en...@gmail.com>.
Hi, Jim.
Forgot to mention that I had an early version on this topic. I uploaded it
to http://wiki.apache.org/ws/Tuscany/TuscanyJava/Extending/Manual. Maybe you
can take a look to see if it helps.
Thanks,
Raymond
----- Original Message -----
From: "Jim Marino" <jm...@myromatours.com>
To: <tu...@ws.apache.org>
Sent: Wednesday, July 12, 2006 6:04 PM
Subject: Chianti extension manual
> I've started a manual for extending Chianti. It's obviously very rough
> and missing many pieces but comments and contributions are welcome. If
> you plan on editing it, please let me know so we don't collide.
>
> Also, this is a good point to raise the question of how we want to
> construct user manuals. I seem to recall Hibernate having a good process
> which results in the output of multiple formats, including pdf, single
> page html, and multi-page html. Any suggestions? For the time being,
> I've left it in Word but plan to switch to a more "open" format.
>
> Jim
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
> For additional commands, e-mail: tuscany-dev-help@ws.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: tuscany-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: tuscany-dev-help@ws.apache.org