I just wanted to start this Poll to get feedback on which Format the BlenderDoc should be edited!
Because I'm not very good at any of these Formats (except TXT perhaps
), I'll have to learn!
Maybe we can also get a decision!
We will see ...
I'm not sure what DocBook is like, but I voted for it because out of the choices, it sounds like it's something that can be downloaded.
So my responce is, it would be great if it were downloadable and viewable on my local computer. That's what I'd like.
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.
Docbook sounds good - ideally we should want something with potential for many different targets and potential future technologies. Something that can be translated to print sounds good, as well as something that can be translated to smaller hand-held devices (A mini-blender manual on your pocketPC/palm while you work on your main machine for example) and many other formats too. But also something that can be formatted well into a decent layout, with decent typography. The printed Blender documentation is well reknowned for it's great clear layout and excellent sense of style and I'd love to see that stay.
not everyone has docbook.
xml can be read in ie mozilla or netscape.
but I would rather suggest
(for those who are too young POD is Plain Old Documentation, POD can be converted automatically to HTML, TeX etc.
As a second possibility I would sponsor good old
And where is PDF? There is something to say about defacto standards out there. I have never heard of DOC Book before today. There are a number of PDF generators out there (yes even opensource if you have some leftest grudge against corperations) and it can on just about every platform that Blender is ported to...
All of the proposed format can be exported in PDF but are far easier to WRITE... have you ever tried to write PDF directly
Using eterogeneous word processors to produce PDF would be unefficient. We must agree on a open, all-platform -possibly text only- standard to write in, then you can publish it on the net on the format you like.
I agree that a format needs to be agreed on so that everyone can contribute to it. Maybe every week or so a sort of release of the latest documentation could be made in such formats as PDF and others that need quite time consuming/annoying conversions.
I have never heard of DocBook i no what XML is, is DocBook an opensource program that interprets and edits xml style documentation. Or is it only for editing.
We need to remember that newish blender users may never have heard of DocBook, and so all formats are really needed.
POD is ok but i would prefer LaTeX.
pdf output is then also included.
or: PDO -> LaTeX -> PDF....
GIT d+ s:- a- C++ UL+++ P--- L+ E--- W+ N+ o-- K- w++ O-- M V--
PS+ PE Y+ PGP++ t+++ 5 X+++ R- tv++ b++ DI- D- G e+ h-- r- y++