New manual format now online

After some sustained work by long-time Ardour contributor Tim Mayberry, the manual pages have been reformatted as DocBook XML and then rendered to a new online format. You can see the results in the usual place; I think they look great. Tim and others are still working on fine tuning the CSS file used for online formatting, so expect to see a few more changes. We will also be investigating options for keeping a Wiki-style system for editing. For the time being, the “source code” to the manual lives in subversion, under manual/ at the top level.

If you would like to help, documentation for DocBook is here.

I’d like to add that although the readability of the manual is important I would like to help focus on improving the content so if anyone has a suggestion regarding the manual style it would be helpful if they could be made via the bug tracker.

I intend to make some information available for people who are not familiar with DocBook and I filed a bug to do remind me to do that but I don’t consider it absolutely necessary to contribute documentation. A patch containing the modifications to the docbook source is preferred but if a documentation bug is filed with some accompanying documentation in an open format I am willing to do the conversion.

There is a fair amount of information available about DocBook but a friend of mine created a somewhat simplified diagram of a common toolchain used to process DocBook XML source into formats such as HTML and PDF which may help give some understanding.

toolchain workflow

One aspect of using DocBook for documentation is that it has good support for content localization, but in saying that it is a fairly complicated process and some time will be needed to implement support for it.

The link in Paul’s main post above is broken. “in the usual place” should point to http://ardour.org/files/manual/index.html not https://ardour.org/node/files/manual/index.html

– Alex