Documentation Format? (SGML,HTML,TXT;-), ...)

Blender documentation projects, tutorials, translation, learning & teaching Blender

Moderators: jesterKing, stiv


TXT (I know that has no chance! ;-D)
Total votes: 55

Posts: 10
Joined: Sat Oct 19, 2002 1:36 pm

Post by H_xNaN »

Interesting and *long* thread this is !
FWIW here's my list of things that accumulated to the internal NaN documentation structure. Always in a hurry as we were to become profitable there was not much time left for proper documentation, but even we ( ;-) ) had a need for it and we wanted to have to put as little time in it as possibe. It had to be multi-platform, and thus an open standard, for we worked at almost all blender supported platforms. It became plain hand-written HTML, under CVS control, which ruled out (most) html code generation tools because they make a gibberish out of it (try to read html code generated by MS-Word). I set up our intranet such that cvs commits in the intranet/ folder were instantly checked out on our intranet web server. This worked great and was easy to maintain by all involved in technical documentation (that's the part i'm talking about, not the books stuff). Lateron we added a latex to html convertor, and nice tools like doxygen.
I'm very curious to see where this thread leads to.

Posts: 6
Joined: Wed Oct 23, 2002 12:28 pm

Post by rontarrant »

ton wrote:What I have to say? I was hoping you guys would easily agree. :wink:

I guess there's a difference in requirements for the 'technical docs' and 'end-user docs'. Especially when you want to make a book, or documentation having a lot of chapters and a more complex internal structure, docbook provides excellent support.
Ton, could you direct me to a site with a beginnner's guide to DocBook, please?
ton wrote:
These docs typically are short, and not intended to be published otherwise than made available in CVS and at the internet.
Speaking of short docs, why not set up a small DocBook project we can use to 'get our feet.' Then we can all see what the learning curve is like, etc. It could be something like:

- a guide to keyboard shortcuts
- or an overview of Blender

If this small project was split up into separate pages for each area of Blender (object creation, lighting, animation, video transfer, sound, etc), it would give a number of people a chance to do one page each. If there are more people involved than could be accomodated in one team, have several teams doing a redundant effort. It would get us going and give us all a feeling of getting somewhere.

What do you think?
ton wrote: So, why not adopt both approaches? Allow, especially for technical docs, people to contribute HTML. This can easily be (re-)organized using directory structures. We can provide a template for it, to keep some uniformity in the documentation.
I think you're right to separate tech docs from user docs and use a different approach for each. It's likely that programmers will do most of the tech stuff anyway and user docs can be handled by those of us who aren't up to dealing with programming but do have expertise in doc creation.
ton wrote: If needed, people can even volunteer to convert the html into DocBook.

So, what about that?
I suppose there's even a programmer out there somewhere who could be convinced to write a conversion utility if it's needed. :-)

-Ron T.

Posts: 3
Joined: Fri Oct 18, 2002 12:55 pm

Post by chromit »

there is a lot of different documentation:

API (doxygen, javadoc (only for java :( ) )
code (comments )
architecture (UML tool, ...)

books (docBook, tex)

each of them has other needs.

i propose in general XML (easy, lots of tools, common) as long as there isn't something else who fits the needs well (DocBook for books).

with XSLT (flexible XML conversion tool) it's easy to convert an user defined XML file to HTML (for online viewing). this can be easy done online/ on file-request.
with XSL-FO it can be converted to printable formats like PDF, PS and stuff. (don't know exactly, never tried, only read about it).

possible XML example for tutorials:

Code: Select all

  <title>how to create little green aliens</title>
  <author>a little red alien</author>
    <keyword>green alien</keyword>
    <keyword>little alien</keyword>
    <description>create a .... add a ...</description>
    <description>create a .... add a ...</description>
this is easy to learn for everyone and can be viewed almost directly trough XSLT/ browser.

only an example to enlarge your horizont :wink:

ohh, yep, all the tools exist in java so it's almost platformindependent.

Posts: 4
Joined: Tue Oct 29, 2002 3:16 am

Post by ScottishPig »


Posts: 122
Joined: Mon Oct 14, 2002 2:49 am

Post by dittohead »

ScottishPorker!!! welcome to the forums.(as a registered user)

Posts: 5
Joined: Thu Jan 23, 2003 8:17 pm

Seperation of content from presentation

Post by meekrob »

I think what a lot of people who have contributed this thread don't really understand what xml or docbook really is.

Writing your docs in HTML or PDF or similar file formats is a bad idea because it locks you into a single format.

If you write your docs in XML or Docbook, that is not what you read in the end! You use a program to process the XML to multiple formats ... PDF, HTML, LATEX or WHATEVER. So nobody needs a special plugin to read XML docs.

The most important point however, is that XML or Docbook seperates content from presentation. For example a XML document would look like this:

<author>Ton Roosendal</author>
<title>The Blender Bible</title>
<chapter>In the beginning there was...</chapter>

No matter what format we want to present this in it will always be a piece of cake to process. Why? Because we have specified what each piece of data is. Finding out who the author is of an html file is tricky business. But with XML it is a piece of cake.

Say we do go with HTML. When we decide it is time to take all these various docs, written by different authors, with different styles of html and integrate them into one document, the advantages of XML will become crystal clear. Even with guidelines for the authors to follow, it will be near impossible to enforce those guidlines.

Honestly the discussion here should be XML or Docbook XML. Docbook sounds like a great idea, except I cannot find any good documentation for newbies. If anyone knows of any I'd be glad to read em.

So in my experience it is easiest to simply roll your own XML application. Call it blenderdoc. Keep it simple with under 20 tags.


Posts: 0
Joined: Mon Feb 17, 2003 12:42 am

Post by kabads »

Ultimately, we should be aiming for documentation which is portable and well structured.

However, to stick to this early on might be limiting peoples' contibutions, ie. those without the technical know-how of these kind of platforms (ie. Docbook and SGML).

In my opinion the best way to run this would be to have an official documentation thread, which sticks to XML, Docbook etc. and another less formal one, based on Wiki, obviously, being HTML based.

The Wiki can feed the authors of the official release, and yet still be flexible for people to contribute. It might also generate a lot of content quicker than the traditional Docbook route.

Just my two penneth.

Posts: 0
Joined: Sat Feb 22, 2003 4:02 am

Post by compjinx »

XML; seems that everything else has been build on either it, or its parent(SGML) and since XML is a nicer lighter version of SGML meant for the web.

HTML comes from SGML, DocBook comes from XML (DTD kinda thing?) and/or SGML. So I figure that XML should be used, just for it's easy portability to other formats (and the fact that it is human readable).

Anyways... first post... be kind...

Post Reply