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 ...
Bye
Documentation Format? (SGML,HTML,TXT;-), ...)
Moderators: jesterKing, stiv
Documentation Format? (SGML,HTML,TXT;-), ...)
Heyho...
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 ...
Bye
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 ...
Bye
I'd like to give you a rough overview of the formats:
XML
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
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.
Plain text
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:
My proposal
Core source format: DocBook XML.
Editing formats: 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.
Output formats: 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.
XML
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
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.Plain text
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:
My proposal
Core source format: DocBook XML.
Editing formats: 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.Output formats: 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.
Felix
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.
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.
Stefano
?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.
Stefano
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.
-------------
L!13
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.
-------------
L!13
This is very interesting. I wasn't aware of POD as I've always used Python in the past for scripting.S68 wrote:***FLAME ME***
but I would rather suggest
POD
(for those who are too young POD is Plain Old Documentation, POD can be converted automatically to HTML, TeX etc.
etc.
As a second possibility I would sponsor good old
LaTeX
Stefano
I have several reservations with DocBook. First, Its no small task to get DocBook installed properly, learning how to use the DocBook tools and to become productive with it (ie learn it's syntax). Second, DocBook is very verbose (this is a strength too) and requires a lot of typing and with more typing comes more chance for errors against DocBook's complicated DTD. The roadblock of getting DocBook installed and running could be partially bypassed by the community creating tools to aid contributors getting started. Of course, as of right now there is no way to make this easy for potential contributors as we have no infrastructure or tools to aid contributors.
POD just has a few commands and would only take about 15 minutes for someone to learn the complete syntax (or at least get productive with it). POD can translate to HTML, TXT and LaTex. We could output our docs into any format from LaTex via POD. I've read one can also translate POD documents into DocBook DTDs. POD's also been used to write several high profile books. The only real drawback I can see to using POD is that it doesn't have support for tables. Perhaps this could be hacked on tho.
POD is at least worth investigating further. What does everyone else think?
Good suggestion Stefano!
-Pato
You should have voted for HTML then, I'm afraidIngieBee wrote: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.
- but ... if you at least have read what I wrote (it's ok if you don't understand every(or any-)thing, just ask then), you should know that you'll get it in a way you'll like (or else get someone to make it the way you like). But see my next post about the ignorance shown here. 
Felix
Very strange request indeed.S68 wrote:***FLAME ME***
S68 and pato wrote:POD
Sorry to be somewhat nasty, but I'm really pissed off with writing long, time-consuming (both for me and (I'm afraid) also for the reader) explanations that try to describe something somewhat bullet-(or, idiot-)proof, which then doesn't get read at all. So:xitnalta (that's me) wrote:My proposal
Core source format: DocBook XML.
Editing formats: 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
TO EVERYBODY WHO INTENDS TO CONTRIBUTE TO THIS THREAD:
-> Make sure you've read it completely first!
S68, you would actually not have deserved a flame for your post, but I had to do that because of seemingly general ignorance. Believe me, it is quite an effort to write these long replies. They're here to get read and then (maybe) critizised for their length, but not to be ignored.
Back to real business: I really like that idea of POD, even if I only heard about it when reading though perldoc. I think it is a good idea to make it an additional editing format people can contribute in. If you have a problem with DocBook XML being the core documentation format (that most people won't even have to learn in order to contribute documentation (for abovementioned reasons), but that I made a quite easy-to-install environment for Windows and Unix for anyway), then please just say so! But don't you dare to ignore the half content of a thread again - I don't think I'm the only one getting pissed off by such conduct.
Of course! But again, I don't recommend it to be the central documentation format.pato wrote:POD is at least worth investigating further.
What does everyone else think?
Now please come back and discuss this further. I don't intend to stop discussion with that post, but ignorance.
Last edited by xitnalta on Thu Oct 24, 2002 12:50 am, edited 2 times in total.
Felix
