I'd like to give you a rough overview of the formats:
XML is a formatting concept that works at the same level as a text file - it needs an application to be interpreted and you're absolutely free to put into it what you want. XML is roughly like HTML, only that you have to define all the tags yourself. It is used for textual documents (XHTML, DocBook XML), image formats (the vector-based SVG), native file formats, configuration files, remote procedure calls (XML-RPC and SOAP), ... . All these things are called applications
of XML You can do almost everything with XML that involves storing or exchanging data. (Sorry, I'm a bit lazy to look up all the respective links of that stuff. You find the XML standards and many applications of it on http://www.w3.org/ .)
If we were really choosing XML, we would have to come up with a suitable application for documentation - which already exists, so we can save a lot of work by using that (see below).
HTML (for me
) is an old standard, whose development is heavily dominated by companies who seeked competitive advantages (remember the Netscape vs. Internet Explorer flamewars?) and therefore was rampanting to cover all possible webdesign feature inventions of these companies. It really shouldn't
be used for technical documentation (although the German SELFHTML
compendium shows that it can
be done). But I don't say that I completely want to lock out people used to HTML (such as myself
) - see below.
Of course that one loses
. It is simple to say that paragraphs are separated by blank lines. But then, how do you make sure a program knows what a heading is? Or the title of the whole text file? And how do you want to embed pictures and emphasized text? That quickly shows that it is not suitable for large-scale documentation as well. (It is very efficient for README's and fast-written, small documentation drafts, though.) But we can still try to provide this format as a possible output format (and if this means doing 'lynx -dump some-html-output.html > some-text-output.txt' - so be it
DocBook what - DocBook SGML? DocBook XML?
Currently, DocBook is (still) available in two flavours - DocBook SGML and DocBook XML. I already described XML. SGML is similar to XML - it is like a much less restrictive, older, and much more complicated (for computer programs to interpret) format than XML. Like XHTML is an application of XML, HTML is an application of SGML.
DocBook XML is an XML application (you can repeat the same for SGML) very well suited for writing technical documentation - articles, books, etc. Thus:
Core source format:
DocBook XML (and SGML, if possible, through conversion), a subset of HTML, a subset of LaTeX, a Wiki-like language, and maybe a few others (Texinfo subset? OpenOffice.org? (very hot idea
)). I want to enable people to easily contribute. It doesn't mean that non-DocBook authors can then edit all of the other documentation not already (originally) written in their format (some of them can be cross-transformed), but that's a small loss of flexibility that you have to accept.
EVERYTHING! HTML (with or without frames etc.), PostScript and PDF, DocBook SGML, PalmDoc, Plain Text, Word documents (urgh), RTF, other XML formats, SVG, XSL:FO (oh, I'd really
love to have a working DocBook XML -> XSL:FO -> PDF toolchain with only free software
), man pages, TexInfo, ... . Really, everything. But it will take a lot of time to have sophisticated conversion mechanisms for all those formats, of course. Easiest are HTML (and plain text - with lynx
) and ... well, that's all I have produced from DocBook XML so far, but RTF, PostScript (and PDF - they're almost interchangeable formats), DocBook SGML (just rename *.xml to *.sgm?), and XSL:FO ((almost) like PDF, but XML-based) should be feasible as well.
Puh, sounds like a lot of work. Let's start by making some guidelines on writing DocBook XML for Blender documentation.