Hi,
Answer to Andreas' and Simone's questions in one email:
Yes there are already a few "Docbook for dummies" from various projects
like LDP. We can easy adopt that one for our purposes. Intent is to have
only those xml articles in cvs and all generated stuff on the website as
well as enable user to build whatever version needed through ant build.
As far as I know there aren't any specialized IDE's for Docbook yet.
There are Emacs bindings, a good XML editor can guide you with help of
Docbook DTD, and there is always very usefull and handy reference at
http://www.docbook.org/tdg/html/docbook.html
At last you can always use xml parser to verify Docbook XML file
correctness.
Cheers,
Vladimir
On Thu, 11 Jan 2001, Bordet, Simone wrote:
> Hey Vladimir,
>
> just curious about DocBook, I started looking at it and I have a question:
> do you use a simple text editor to write documentation, or it exists a tool
> that allows you to easily "format" (ie embed in the appropriate XML DocBook
> tag) the document you're writing ?
> I have in mind some IDE that allows you to type as if you are in M$ Word (so
> you have paragraphs, bullets and facilities like hyperlinking selected
> objects, image inserting, etc) but in reality it generates HTML for you.
>
> Regards,
>
> Simon
>
> > -----Original Message-----
> > From: Vladimir A Blagojevic [mailto:[EMAIL PROTECTED]]
> > Sent: gioved� 11 gennaio 2001 22:37
> > To: [EMAIL PROTECTED]
> > Subject: [jBoss-Dev] Documentation overhaul - a case for docbook
> >
> >
> > Hi,
> >
> > Our fellow JBoss colleague Tobias French has initiated JBoss
> > documentation
> > discussions regarding different approaches to resolving our
> > documentation
> > problem.
> >
> > Some time ago upon "directive" from Marc I started working on
> > JBoss container
> > walk-through paper (finally done now) which also kicked off
> > my search for
> > documentation solution.
> >
> > After some considerate time spent looking around I came to a
> > conclusion that
> > Docbook XML initiative is the most reasonable way to go.
> > DocBook is a XML
> > and SGML DTD that lets authors in technical groups exchange and reuse
> > technical information. Docbook DTD defines some 300 elements that are
> > contextually related to a computer technical writing.
> > For example DTD contains elements such as : computeroutput,
> > programlisting,
> > chapter, para, article , faq etc
> >
> > To get a feel of docbook-ed JBoss CMP article point your XML
> > client here
> > http://www.ariel.cs.yorku.ca/~cs962267/docbook/cmp.xml
> >
> > Docbook "package" comes with XSL stylesheets that allow
> > technical groups
> > define different views of Docbook-ed XML content. Currently
> > defined are
> > XML-HTML and XML-PDF stylesheets that allow creating of HTML
> > and PDF documents.
> >
> > These stylesheets are very flexible, well maintained, allow easily
> > customized hooks for specialized home-brewed styles of HTML views.
> > One specialized HTML view that I goofed with can be found at:
> > www.ariel.cs.yorku.ca/~cs962267
> >
> > The point is : you have one xml content, chunked into logical pieces
> > (i.e articles) which are then easily arranged , put together, and in
> > the end XSL stylesheet is applied against it to create any kind of
> > HTML view or PDF or PS etc etc
> >
> > DSSSL stylesheets, used in era of SGML can also be used to create
> > specialized views formats. In fact ,while experimenting with this on
> > RedHat Linux I managed to create doc, ps, dvi and all other different
> > kinds of formats from single docbook article.
> >
> > Principal maintainer of Docbook is Norman Walsh , www.nwalsh.com ,
> > one of the best guys in this industry , a member of XSL working group,
> > Sun Microsystems employee.
> >
> > Not to mention that Redhat, GNOME , KDE and all other major players
> > are already "on" Docbook. See a good article printed more than a year
> > ago at http://www.xml.com/pub/a/1999/10/docbook/docbook-making.html
> >
> > I have already docbook-ed more than 50 % of our documentation.
> > To finish HTML part of documentation I estimate that we would need
> > some 2 man days to finish it, another 3 man days to nicely arrange
> > everything ( customized HTML view , content arranging) and
> > finally 1 man
> > day to create ant build script to generate doco. After that
> > maintaining
> > should be very efficient/cost-effective. Content authors
> > don't have to
> > worry about content views only content. Documentation maintainer only
> > arranges content and maintaints stylesheets. Piece of cake , work
> > divided, view is consistent , everybody is happy.
> >
> > In a summary I think that Docbook is the best choice to
> > easily maintain
> > current documentation, update it , and create and kind of desired view
> > of the content.
> >
> > I gladly await any other approaches, views , questions. If
> > needed maybe
> > after some discussion the board can make a vote so we can close this
> > chapter and move forward.
> >
> > Sincerely,
> >
> > Vladimir
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
> >
>
>
