DocBook

What is it?

DocBook is a markup language used to create and maintain documentation that can be as simple as an article or a chapter, or as big as a complete book or a set of books.

Links:

Wikipedia article about DocBook.
DocBook definition in http://wiki.docbook.org/topic/DocBook .
http://wiki.docbook.org/ (docbook wiki is based on MoinMoin).
- This is a wiki about Docbook, using MoinMoin. It is different from DocBookWiki (http://doc-book.sourceforge.net/homepage/), which is written in PHP and supports Docbook as its native format.
http://validate.sf.net - Online DocBook Validator and XML -> HTML/PDF Transformer
http://docbook.org/
http://www.oasis-open.org/committees/docbook/
Eric S. Raymond: DocBook Demystification HOWTO version 1.3 revised 2004-02-27

MoinMoin and DocBook

MoinMoin >=1.3.5 supports DocBook parsing and generation
- Requires installation of PyXML http://pypi.python.org/pypi/PyXML
- You can generate DocBook for any page with the "Render As DocBook" action (use the 'mimetype=text/docbook'). See HelpOnActions.
- You can include DocBook XML in any page using the XSLT processing option. See HelpOnXmlPages.

Related pages here:

FeatureRequests/XmlDocbookWiki
DocBookToOpenDocumentXslt
OpenOfficeConverter
See FeatureRequests/XmlDocbookWiki for a boon to Moin & Docbook!

DocBook output in 1.7

Several (but not all) new features from the 1.6 docbook branch have been merged with 1.7. If you are interested in using DocBook with MoinMoin, please help test the docbook formatter changes merged from the 1.6 docbook branch! The test wiki is at http://test17.moinmo.in/. If/when you find things that break, please report them at MoinMoinBugs and send an email toMikko Virkkilä.

The following is a list of features from the 1.6 docbook branch that have been merged into the 1.7 release:

Output valid DOCTYPE
Much improved table support
Support for unicode and HTML entities like →(=→) and ☃ (=☃)
Support for FootNote macro
Support for bulletless lists
Much better support for definitions and glossaries
Added support for program language and line numbering in code areas
Support for linebreaks in paragraphs and more robust support for them in preformatted sections
Images should now always get an absolute path
A bug where if the attachment had a title specified, the title would not be carried over as the alternative text is fixed
Support for the MoinMoin comment element was added. It is mapped to a "remark" element. Will produce valid docbook only with inline comments though, as remark is an inline element.
Admonitions: if the wikiparser is used in a code area and one of the docbook admonition names is specified as the css class the code area will be turned in to a native DocBook admonition. The admonitions are tip, note, important, caution, warning in rising severity order. Note that the relevant css rules have not been implemented yet in the default theme, so the html output will by default not look like much.
Revision history: the wiki page's edit history is exported inside the docbook as the docbook's revision history. Doesn't work with included pages, only the main page.

The following features from the 1.6 docbook branch have not been merged yet:

There is community interest in merging the ImportDocBook and BuildBook utilities into the main release. However, more testing and improvements need to be done before these are ready.

History of 1.6 docbook branch

The 1.6 docbook code was contributed by Mikko Virkkilä as a Google Summer of Code 2006 project. Much of the information below was copied from http://fedoraproject.org/wiki/MoinDocBookProject and related pages. The goal of this ambitious project was to improve and facilitate the use of DocBook inside MoinMoin.

TODO

Docs

Cleanup comments / docstrings, add some more
CHANGES.mvirkill:
- merge to the main CHANGES file (after merging to main branch)
User docs:
- getting it working: which dependencies? other things to do?
  - 4suite-xml (which versions work?)
- add some lines on the MoinFeatures page - see text prepared in CHANGES.mvirkkil
- Help pages:
  - the new stuff has some comments in the CODE about "what it does" - at least part of that stuff should be added to CHANGES or to some Help* page on moinmaster wiki so that people will know what's in there and what they can do with it. Add some use cases for docbook to the Help pages (for docbook dummies like me :).
  - an Admonition macro Help page should get created (see also admonition for rest markup)
  - all docbook related actions (RenderAsDocBook / BuildBook / ImportDocBook) also need help page(s)
  - Insert macro needs help page

Coding Style

Code should be PEP8 compliant (mostly whitespace issues, import order), see also CodingStyle
Minor code changes:
- avoid using too much str+str+str [but rather use %s]
- use os.path.join (not "x/y/z"), so it could work on win32, too
The text_docbook formatter has some "print"s in it, they maybe should get removed or commented out or replaced by logging.debug()
[TW] Is it just me or would maybe more people understand "admonition" better if it was renamed to "warning" or "hint" (or some other term that non-native speakers understand better)?
Admonition.py uses str+str too often, replace by output.append(...) and "".join(output)

Fixes / TODO

the pagename parameter to Admonition macro currently does nothing (TODO)

Tests

We need people using/testing this so we can make sure that merging it into main improves our docbook support (and doesn't break stuff that worked before).http://docbook.wikiwikiweb.de/
BuildBook works for SyntaxReference
more tests with DocBookImport - sometimes it doesn't generate any pages (e.g. with output of BuildBook for SyntaxReference page).
"Render as DocBook":
- compare docbook formatter output of 1.6 branch with 1.6-docbook branch.
- http://docbook.wikiwikiweb.de/docs/RPM%20Guide?mimetype=text/book chapters are empty?

Maintenance

It would be nice not just getting that code into main branch, but also having some maintainer for it who is able to fix bugs if people find some.

Other