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

 * [[http://en.wikipedia.org/wiki/DocBook|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: [[http://en.tldp.org/HOWTO/DocBook-Demystification-HOWTO/|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.  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!

<<Anchor(GSoC2006MoinDocBook)>>

== 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 to[[http://fedoraproject.org/wiki/MikkoVirkkilä|Mikko 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 {{{&rarr;}}}(=→) and {{{&#9731;}}} (=☃)
 * 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:

 * ImportDocBook
 * BuildBook

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 [[http://fedoraproject.org/wiki/MikkoVirkkilä|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.

 * /RoadMap
 * [[/Bugs]]
 * /ProgressReports
 * /SupportedElements

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

 * We need to discuss about the "Insert" vs. "Include" macro.
