One way for you to get a grip on DocBook would be to try out Eric Raymond's doclifter:
http://www.catb.org/~esr/doclifter/
"The doclifter program translates documents written in troff macros to DocBook."
If you insist on writing a markup shorthand rather than the somewhat verbose XML markup, there's a number of options. If you are really familiar with SGML, you can actually use a normalizing SGML parser to 'fix up' a shorthand. Here's an example:
http://www.xml.com/pub/a/2004/03/03/sgmlwiki.html
A few tools for up-translating structured text to DocBook markup:
http://docutils.sourceforge.net/
http://docutils.sourceforge.net/sandbox/oliverr/docbook/
The DocBook writer is not terribly complete yet.
http://www.xmlmind.com/aptconvert.html
See a list of more up-conversion tools:
http://wiki.docbook.org/topic/DocBookTools#top_Include_ConvertOtherFormatsToDocBook
I have mixed feelings wrt. shorthands vs. valid XML markup. Mostly, I'll write the body of the text with little or no markup, and then add markup later. A structured text format can be helpful (and really nice for documentation embedded in source code). But you won't really get the benefits of XML without using it.
There is a long list of tutorials on the DocBook wiki:
http://wiki.docbook.org/topic/DocBookTutorials
Many of these tutorials appear to be a bit dated wrt. tools and "best practices". Given that you don't have any legacy DocBook documents:
- you should not start any new SGML-based projects
- you should investigate using xinclude rather than entity references
- you should prepare to use namespaces
- you should investigate using Relax NG and Schematron-based validation
In addition to this list and the DocBook wiki, you'd like to sample David Pawson's DocBook FAQ:
http://www.dpawson.co.uk/docbook/index.html
kind regards
Peter Ring
