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

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

Moderators: jesterKing, stiv

SGML

XML
12
22%
HTML
18
33%
TXT (I know that has no chance! ;-D)
1
2%
DocBook
24
44%
 
Total votes: 55

xitnalta
Posts: 68
Joined: Tue Oct 15, 2002 11:52 pm
Location: Romanshorn (TG), Switzerland

Postby xitnalta » Thu Oct 24, 2002 12:57 am

Btw.: DocBook is a file format, not a program. I could have made that point clearer.
Felix

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

Postby rontarrant » Thu Oct 24, 2002 2:10 am

Forgive the cross-posting, but since I started off in the wrong thread, I thought it best to repeat this here as well as in the original thread:

xitnalta wrote:
That was actually exactly the way people should promote themselves into any moderatoring boards here - by saying what they can do and then, to prove that they know what they're talking of, giving an opinion about it. Well done!

But that doesn't mean I automatically also agree with you. ;)


:-) Well said, sir.

xitnalta wrote:I'm totally against it. Not because I would have more experience than you (I only live since '85 and started programming with 8 years, so I'm now only about 9 years "married" to computers ;) ), but because I know (not only) HTML fairly well to know that it is not the best (and, I would argue, also not even a good) solution to this.



I've been waiting years to say this: I've been programming since you were in short pants! (Sorry, I couldn't resist) :-)

But I see your point about HTML. Do you (or anyone else) know what format the current fancy manual is done in, the one produced and printed by NaN? If nothing else, knowing that would be good fodder for discussion.

xitnalta wrote:But please just join us by contributing to this thread about documentation formats (that I had to flame a bit, sorry, but you'll find out why).


I read that thread, but I wasn't sure why you got so upset. Not that you need to explain any further or anything; I don't want to start a rumble.

xitnalta wrote:You don't actually need to install and/or write DocBook XML locally at your machine to help authoring documentation if DocBook XML is used as the central format.


I'm not sure I understand. How would the original author know if s/he's delivering a usable document if they can't check it locally? Personally, I like to have some way to test-display a doc before delivery.

xitnalta wrote: The processing (converting author documents to DocBook XML, and generation of other formats) can be done centrally somewhere on blender.org (or by The Documentation Staff


A central 'clearing' staff makes a lot of sense to me.

xitnalta wrote:I envision that for writing Blender documentation, people should be able to contribute in the format that suits them best (and/or is easiest to check for errors in their work environment).


It could get a bit confusing for the Doc Staff if they're receiving stuff in a number of different formats, however. I suppose it might help to come up with (for instance) two or three 'accepted' formats for writers that would then be converted to whatever base format is agreed on. At least that way things wouldn't get out of hand. To go along with that, though, it would be best (IMHO) to define Author's Delivery Formats as being something that's easily-available and easy to install/setup/whatever.

xitnalta wrote:Stay tuned and feel welcome!
:D :D

[/quote]

Thanks!

-Ron T.

S68
Posts: 94
Joined: Mon Oct 14, 2002 12:58 pm

Postby S68 » Thu Oct 24, 2002 10:13 am

xitnalta wrote:[
TO EVERYBODY WHO INTENDS TO CONTRIBUTE TO THIS THREAD:
-> Make sure you've read it completely first!


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.


/me is downloading

I've no problem with DocBook, except ignorance (never used it :P )

So, since I'm seriously intended to contribute, I'll learn it.

Blend on!

Stefano

droddl
Posts: 18
Joined: Sun Oct 13, 2002 7:42 pm

Postby droddl » Thu Oct 24, 2002 11:11 am

Heyho...

As the creator of this thread, I would like to say something!
@ Xinalta: You are getting mor sympathetix to me! :-)
And post a big big link to your page including that docbook distribution!

@everyone else: Many many things speak for DocBook!
I for myself can't deal with it yet! YET! I will have to learn it, but I think it's worth it! And everyone who dooes not want to learn it can make the documentation in any other format! Pass it to the admin, who then converts it into docbook! I know this is lot of work, but better than an endless Discussion of this topic!!!

To come to an end:
I think it's dicided that we are going to use DocBook! In fact that the poll gives an absolute majority! ;-)

If everyone thinks it's ok, then let's make some conventions for documenting blender! And the next step: EDIT and REORGANIZE that NAN Stuff!!!

I also checked out an XML-Editor:http://www.xmlmind.com/xmleditor/ Never used it, but I will! :-)

leinad13
Posts: 216
Joined: Wed Oct 16, 2002 5:35 pm

Postby leinad13 » Thu Oct 24, 2002 1:34 pm

Before i go and download some docbook related programs are we all agreed that docbook is the format of choice. No one is gonna come back in a day or so and say
"Oops, my bad docbook is crap, we will use ......... instead"

k now ive got that off my chest im gonna go download
-------------
Over to you boffins

L!13

leinad13
Posts: 216
Joined: Wed Oct 16, 2002 5:35 pm

Postby leinad13 » Thu Oct 24, 2002 2:19 pm

This probably makes me sound really stupid to most of you but im gonna ask anyway.

I have a program to edit XML, i believe that the documentation is going to be written in Docbook XML, what does Docbook have to do with XML and how to use its functionality in windows, BTW i have Cooktop (An XML editor for windows, its seems pretty complete) It pretty nice conversions from XML to HTML using XSLT. (I dont know what XSLT, i think it is a type of stylesheet?)

Could someone please advise me as to what to do next to help with the documentation.
-------------

Over to you boffins



L!13

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

Postby rontarrant » Thu Oct 24, 2002 3:56 pm

droddl wrote:Heyho...

To come to an end:
I think it's dicided that we are going to use DocBook! In fact that the poll gives an absolute majority! ;-)



As long as DocBook XML allows for the following, I'm all in favour of it:

1) precision placement of design elements (like you get with the HTML DIV tag)

2) layering of elements

Without that kind of flexibility, the graphic design is going to be severely limited. I'm assuming that since we're talking about delivery formats that include HTML and PDF, XML can handle these things.

-Ron T.

pato
Posts: 18
Joined: Wed Oct 16, 2002 5:50 pm

Postby pato » Thu Oct 24, 2002 9:47 pm

I believe that all the choices which we're currently considering are all very workable. All of these solutions have been used in the past for creating high quality books so certainly they're all at least workable.

As far as using Latex goes... To me it has the same weakness as DocBook does. Its a complicated beast to wrap your arms around and get productive with. A somewhat steep learning curve would tend to limit the pool of contributors I think. Any solution we decide IMO should provide a means for which people could easily and quickly start writing documentation. AFAIK LaTex doesn't provide for this and I'm not sure its even possible. My knowledge of LaTex isn't that great however, so if someone has a solution to LaTex's complexity I'm all ears.

xinalta:
Sit back and relax. :-) You've provided one very good course we might take (DocBook along with several secondary editing formats). You do have to remember though that this is the idea phase of the project. It should be expected and encouraged for people to say "I like X" or "I like Y" or "What about Z?" regardless of what anyone writes (no matter how well put). This is a community project and in the end we'll probably end up using whatever format the majority of the ppl around here like or want to learn/use. You've made your points for DocBook quite well. If you wished to strengthen your point you could set up a small wiki environment (or something similar) where people could *see* how easy it can be to churn out DocBook documentation. Of course there are no guarantees that DocBook will be the project's choice so keep that in mind while working if you setup such an environment. :-) I'm sure everyone's thoughts will be equally weighed when the time comes for the documentation czars to make a decision. Let's all sit back and enjoy the ride! Its sure to be a fun one!

-Pato

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

Postby dittohead » Thu Oct 24, 2002 10:16 pm

NO ONE HAS DOCBOOK!!!

Not very many people want to download YET ANOTHER app just to view the documentation.

Almost anyone can read HTML/XML, so docdookie isn't a very good idea, it would prolly shut people off to blender if they have to try and navigate another site to download some obscure app, just to view the documentation.

excuse me for my nastyness but docdookie is a BAD idea. :twisted:
Last edited by dittohead on Thu Oct 24, 2002 10:19 pm, edited 1 time in total.
dittohead

pato
Posts: 18
Joined: Wed Oct 16, 2002 5:50 pm

Postby pato » Thu Oct 24, 2002 10:17 pm

leinad13 wrote:Before i go and download some docbook related programs are we all agreed that docbook is the format of choice. No one is gonna come back in a day or so and say
"Oops, my bad docbook is crap, we will use ......... instead"

k now ive got that off my chest im gonna go download


Nothing is _really_ decided until:
A) Documentation Moderators are assigned by Ton
B) Those moderators make a final announcement based on developer feedback

Now that being said, there's probably a good chance of DocBook becoming the format of choice once we figure out the implementation details. :-)

-Pato

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

Postby dittohead » Thu Oct 24, 2002 10:22 pm

please not docdookie!!!

most people have no idea what it is!!!

most people dont want to have to try and shuffle around a 3rd party website just to download an app to view the documentation!!

THIS TURNS PEOPLE OFF TO BLENDER!!!
dittohead

pato
Posts: 18
Joined: Wed Oct 16, 2002 5:50 pm

Postby pato » Thu Oct 24, 2002 10:26 pm

dittohead wrote:i don't think these docbook freaks realize this but:

NO ONE HAS DOCBOOK!!!

Not very many people want to download YET ANOTHER app just to view the documentation.

Almost anyone can read HTML/XML, so docdookie isn't a very good idea, it would prolly shut people off to blender if they have to try and navigate another site to download some obscure app, just to view the documentation.

excuse me for my nastyness but docdookie is a BAD idea. :twisted:


DocBook is not an application but a source format for the documentation as xinalta mentioned earlier. From DocBook you can output HTML, PDFs, Formatted Text and many more. As noted earlier, DocBook *is* XML/SGML.

-Pato

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

Postby dittohead » Thu Oct 24, 2002 10:34 pm

like i said people are ignorant to what it is!!!! :P :P
dittohead

xitnalta
Posts: 68
Joined: Tue Oct 15, 2002 11:52 pm
Location: Romanshorn (TG), Switzerland

Postby xitnalta » Fri Oct 25, 2002 12:01 am

leinad13 wrote:"Oops, my bad docbook is crap, we will use ......... instead"

Look, the best point I can make is that I saw most of the things I proposed implemented elsewhere, and figured the rest won't be too difficult (or just might have slipped my attention). You can make HTML from it, you can make PDF files from it ... you can even make manpages if you want to be cruel to the format. So, even if it should be hard, at least everything is possible. If it should be later decided that it really was crap enough to move on (btw., it is an extensible format), everybody will concentrate on that latest conversion to the other format, which can then be done automatically on the whole doc.tree and we have it all in the new format.

It is just the easiest way I can imagine that most people will be satisfied.
Felix

xitnalta
Posts: 68
Joined: Tue Oct 15, 2002 11:52 pm
Location: Romanshorn (TG), Switzerland

Postby xitnalta » Fri Oct 25, 2002 12:23 am

leinad13 wrote:I have a program to edit XML, i believe that the documentation is going to be written in Docbook XML, what does Docbook have to do with XML and how to use its functionality in windows, BTW i have Cooktop (An XML editor for windows, its seems pretty complete) It pretty nice conversions from XML to HTML using XSLT. (I dont know what XSLT, i think it is a type of stylesheet?)

Could someone please advise me as to what to do next to help with the documentation.

Ok, so what do you know about XML? If you knew it, you would know that in itself, you can't do anything with it.

For example, you have the following easy specification, which shall represent XML here for a while:

----- specification start of "LittleXML"

; This is a comment
Keyword = Value

----- specification end of "LittleXML"


That's roughly XML (but a lot more complicated while still comprehensible). Now, what can you do with that? Exactly nothing, because you don't know which keywords are allowed! So DocBook XML is a specification that roughly looks like:

----- specification start of "LittleDocBook"

LittleXML keywords for LittleDocBook:

Title: The value for this keyword specifies the title of the book.
Author: The value for this keyword specifies the person who wrote the book.
ISBN: And this keyword wants the ISBN of the book as its specifier.

There can be many such sections in a LittleDocBook file, each one starting with a line containing Title as its keyword.

----- specification end of "LittleDocBook"


This specification would be for a catalog of books (a famous example for markup languages).

----- start of example
Title = Operating Systems - Design and Implementation
Author = Andrew S. Tanenbaum
Author = Albert S. Woodhull
ISBN = 0-13-630195-9

Title = Python Standard Library
Author = Fredrik Lundh
ISBN = 0-596-00096-0
----- end of example

The specification of the (Little)DocBook format is also called an "application" of (Little)XML. (I'll remove that (Little) again from now.) Without DocBook, but only XML, you would be in a situation like you (probably) were when you learned HTML - you learned how tags looked like (and XML is quite similar), but you didn't yet learn the tag names. DocBook is the tag names.

The other thing you need for DocBook XML (that's the name of the DocBook specification basing on XML - there's also (still) DocBook SGML, that bases on SGML) is software to process it. For markup languages, you tend to use stylesheets for that, since they're an efficient mixture of programming and markup language (well, look at XSLT ;) ) that lets you (relatively) easily express what you want to have as a result from the original document (such as, with CSS, a certain formatting style).

An XML editor is an editor specially suited for editing XML (obviously). But that's the end of the definition of "XML editor". They have very diverse features, and since I don't use Windows (anymore), I can't really tell you what you could do with your editor. (I know XSLT, btw.)

To your help offer:
If you don't know yet what to do in this documentation effort (I think, this thread will come to an end a while after the new server is up and running for blender.org), the best thing is to hang around in the forums, discuss, and wait a (hopefully not too long a) while. Ton is currently assembling a documentation committee that will dig through the existing documentation and set up some guidelines as a base for further discussion. (Guidelines are here to get changed, so don't worry too much about my stubbornness to be visible a too long time in them ;).)

PS: no question is stupid, keeping it for yourself is.
Felix


Return to “Documentation & Education”

Who is online

Users browsing this forum: Bing [Bot] and 0 guests