Docbook XML

DocBook is an XML dialect that is used by a wide range of projects to maintain their documentation. Examples for DocBook usage in OpenSource projects are the documentations of KDE and PHP. PEAR has opted for using DocBook because we believe that it provides a solid foundation for the technical documentation for PEAR packages.

The trade-off for using DocBook is that it is relatively hard to use. Testing documentation requires a special tool to be installed and one needs to learn a (not very complicated) XML dialect. Once one is familiar with how DocBook works they will enjoy writing documentation with it though.

The book DocBook: The Definitive Guide, written by Norman Walsh and Leonard Muellner and published by O'Reilly & Associates, Inc., is available online and it makes up a great resource for people interested in learning DocBook.

Definitely check out the book's DocBook Element Reference section. This portion provides detailed information about each element, including which elements can (and must) be used as parents and children.