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