DocBook Doclet
The DocBook Doclet creates DocBook XML from Java source documentation or HTML files. It is helpful if you want to create reference handbooks of your API. Normally it is used with the Javadoc tool but it can also be used as a standalone application to convert HTML to DocBook. Additionally it comes with a Swing application to manage documentation projects and to transform the resulting DocBook files to PDF, Postscript, HTML, or JavaHelp.
| Tags | Software Development Documentation Utilities Text Processing Markup XML |
|---|---|
| Licenses | Freeware |
| Implementation | Java |
Recent releases
- 24 Mar 2009 16:33
Changes: A FileAccessDeniedException when creating a new project was fixed. Colons in the value of the attribute xml:id were replaced with underscores.
- 16 Feb 2009 09:51
Changes: Generation of wrong class diagrams containing interfaces was fixed. The value of the xml:id attribute now preserves the case. The first (very experimental) version of a new WordML transformation was added. Many minor fixes and improvements were made.
- 10 Nov 2008 21:46
Changes: Improved support for generics. DocBook 5.0 schema violation fixes. A fix for the statistics chapter. Many minor fixes and improvements.
- 25 Aug 2008 21:45
Changes: Missing parameter names have been fixed.
- 24 Aug 2008 21:43
Changes: Support for DocBook 5.0. Integration of DocBook XSL 1.74.0. Integration of APache FOP 0.95. Line breaks are enabled inside of synopsis. Additional spaces before commata in simple lists are removed. ​ (space without width) has been replaced with ­ (soft hyphen) because of problems in the ToC of PDFs. Generations do not lock the application anymore. The console is part of the main window again.
- All comments
Recent commentsImportant tool with some current limitations
This is an important addition to the DocBook
toolchain -- at least as important for its ability to
do "standalone" HTML->DocBook conversion as it is for
its ability to produce DocBook from Java source
documentation. And as far as I know there are no other
open-source tools available for converting HTML to
DocBook.
As of the 0.29 release, however, I think you can't yet
expect it to always produce valid DocBook that doesn't
require some manual cleanup (though it does always generate
clean well-formed XML -- nicely indented even).
The validity limitations I've seen relate mostly to
the fact that HTML permit certain kinds of markup
instances that really aren't complete, though they are
valid against the HTML DTD. When these markup instances get
converted to DocBook, which does require more complete
structures, they may not be valid.
For, example, in HTML, it's valid for a definition
list (dl element) to contain only a term (dt) with no
corresponding description (dd). But the DocBook Doclet
will convert that to a Variablelist containing a Term
but no associated Listitem (the equivalent of dd). This
generates validity errors because the Variablelist
content model requires a Listitem.
But validity errors like that are fairly easy to
find and clean up manually, so it's not that big of a
limitation. For future releases, it would be very
useful to have some logic in DocBook Doclet to detect
and automatically correct certain instances like that,
so that they don't need to be corrected manually.