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 » Fri Oct 25, 2002 12:26 am

pato wrote: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.

I never said it was easy to set up, but only (but maybe I've forgot that) that it would be easy to use once set up. It isn't about the setup, but the comfort of all the people that make me flame here for virtually nothing. It just loses any sense for me that there are still people that don't even try to understand. :(
Felix

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

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

rontarrant wrote: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.

DocBook is not at all about formatting - it is about structure. (Well, why do I only now mention this? I should have done this already in my first post in this thread.) You have tags like <chapter>, <title>, <section>, <book>, <para>(graph), <emphasis> (that's exactly the tag why I'd like to have HTML (where that normally becomes an <i>) be an alternative editing format ;) ), <copyright>, <articleinfo>, etc. (I just picked out a random collection here.) There's not a single line of CSS you will write, or a single text size number you will enter. But I think that's better described at http://docbook.org/tdg/en/html/ch01.html .
Felix

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

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

dittohead wrote: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.

That's a perfectly stupid statement that could probably be from that guy I called an asshole in the chat because of flaming and insulting people there. Let me analyze:

"docbookie"
The main reason I call the statement stupid. I'm sure it's not a typo.

"No one has DocBook"
Wrong, have a look at http://tldp.org/ , the provider of all the "Linux" HOWTOs. Of course at least the single poor guy faking it has to have DocBook. (The "single poor guy" thing was a joke I don't think you got.)

"Not a lot of [spelling] people want to download yet another app just to view the docs"
That's correct, but you can't even download a DocBook viewer. I repeat it: A DOCBOOK VIEWER DOES NOT EXIST! That's why I (and others) said that it can be converted into just about anything - including HTML, which you (persumably) can just double-click on your desktop to get your Fine Internet Explorer running. And if THAT application can't read HTML, then it's surely not our fault. :twisted:

"Almost nobody [I think you meant that] can read HTML/XML."
Wrong. HTML is a synonym for Web page - and if you can't open that format on your computer, you should probably buy a new one or download a 16-bit version of lynx. But since you're here, I really assume that you have "HTML-support" on your computer, since HTML's exactly what you're reading.

As I said before, go reading the comments at the other end (the top one) of this thread to get an idea of what we're talking about.
Felix

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

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

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

Then they shouldn't participate in the discussion on the core documentation format at all.
Felix

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

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

xitnalta wrote:DocBook is not at all about formatting - it is about structure.

Formatting can be done in any possible way by transforming into HTML, of course.
Felix

_florian_
Posts: 36
Joined: Wed Oct 16, 2002 10:17 am

Postby _florian_ » Fri Oct 25, 2002 12:37 am

i think in 3d it could happen to write some math specs.
i know about MathML but these are for most *older* people not that
known like LaTeX where you can write math specs really easy.

i don't like every XML format because you always have to type so mutch
tags.
for those how don't like to write plain LaTeX there exists wysiwyg editors.
i don't know if docbook is really a typesetter like LaTeX but i guess it isn't.
it's easier to convert a text to an online format than to a professional
typesetting thing.

(i guess someone will correct me. and i know who will....)

florian
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++

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

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

I now do what I already did before: I won't contribute to this thread anymore. It is locked for me, by me. I will contribute to other threads and to the documentation effort, but here I'm absolutely lost. It looks like a black hole between the blender.org site and some readers somewhere else on the globe sucks a lot of what I say. (Problem with the temporary server?) I really hate to repeat stuff ten times, so ...

cu later anywhere else

PS: Of course I know there's no technical problem or "black hole" responsible for this. It was my waste of time and my postings that were too long. I'm puzzled why nobody complained about that, but instead just ignored everything.
Felix

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

Postby dittohead » Fri Oct 25, 2002 2:28 am

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

Then they shouldn't participate in the discussion on the core documentation format at all.


chill dude it was a joke.
_______________________________________________________________

about docbook(sorry for the !@#$%&* comments earlier, i feel like *insert another word for donkey here*)

after some research into docbook it sounds like the ideal way to get (the) documentation out there.

will the end-user documentation use tutorials or will it be like a manual?

if so: what if someone wants to contribute a tutorial (or something else small for the documentation), how could this be done if you don't know ANYTHING about docbook? I've written several mini tutorials and have started a small website that delivers a new mini-tutorial once a week, these could be placed in part of the documentation.
dittohead

AshleyHarris
Posts: 5
Joined: Wed Oct 16, 2002 12:25 pm

Postby AshleyHarris » Fri Oct 25, 2002 2:51 am

hey

my $0.02

I think the docs should be in XML. Why? Everybody out there can edit it with a text editor, it's viewable in a web browser, it can be converted extreamly easily to other formats ie PDF, HTML, RTF. I've never actually heard of docbook, but I've heard some critisisms here, maybe we should look into it. If XML is out of the question, it should be HTML, basically, we need something like:

<doc name=charanimation>
<heading>How to animate characters</heading>
<para imgonright="bonepic1.jpg">get the character, add bones, and move it. get the character, add bones, and move it. get the character, add bones, and move it. get the character, add <emp>bones</emp>, and move it. get the character, add bones, and move it. get the character, add bones, and move it. get the character, add bones, and move it. get the character, add bones, and move it.</para>
<nb>you'll need to go into pose mode to move the individual bones</nb>
<para>yadda yadda yadda</para>
<para>yadda yadda here is the finished animation</para>
<img src="jump.gif"/>
</doc>

That's got XML written all over it, it'll be very easy for someone to write, and can be parsed extreamly easily with anything, and then converted into anything with a simple parser. ie blenddoc XML -> HTML -> PDF, or XML-> rtf -> msword, or XML -> HTML -> TXT or whatever. If doc book is something along those lines, then we should use it. (is doc book multiOS?). It would also be very easy for a perl script or the like to automaticly make contents and navigation pages etc.
------
Ashley Harris, The number one slackarse, donothinger, and freeloader on the blender project :-)

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

Postby dittohead » Fri Oct 25, 2002 3:00 am

AshleyHarris wrote:(is doc book multiOS?)


From what i gather:

Consider the docbook version of the documentation, the source code of an app. when you get a hold of it you can edit it if you want, then you complie it for multiple systems, same with doc book, it's like xml, accept when you 'compile it' you can make it xml, html, pdf, and many other file formats.

if the people running the documentation project wish to(like a dev team) can compile it to what ever system(or in docbooks case to what ever format) they want.

correct me if im wrong but from what i gather that's what docbook is in it's simpilist form.
dittohead

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

Postby droddl » Fri Oct 25, 2002 10:09 am

Heyho...

once again! :)
In fact, that many people are voting for HTML (I think I shouldn't have put that on the list :lol: ):

-What do you want to do with that format? It's not very structured and you can only watch it in a browser!!! No convertion, no printing!

-I think, that Ton should say something about that too! See, the new documents for blender, that are online are in XML!!! DocBook!!! Let's use it! Let's learn it! I don't think, that it is very hard to catch it! Let's use an editor!!! If anybody out there knows an easy to use one!

:mrgreen:

Okay!

Let's see what Ton has got to say!!!

Bye

ton
Site Admin
Posts: 525
Joined: Wed Oct 16, 2002 12:13 am
Contact:

Postby ton » Fri Oct 25, 2002 1:53 pm

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.

The NaN technical docs are all written in HTML, that was to make it as easy as possible for everyone to contribute. After all, try motivating an engineer to write docs, er!
These docs typically are short, and not intended to be published otherwise than made available in CVS and at the internet.

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.
The 'Documentation Board' then can define a few projects that will be done in DocBook. These are typically potential 'books', documentation that requires a more sophisticated internal structure.

If needed, people can even volunteer to convert the html into DocBook.

So, what about that?

xype
Posts: 140
Joined: Tue Oct 15, 2002 10:36 pm

Postby xype » Fri Oct 25, 2002 2:03 pm

xitnalta wrote:
xitnalta wrote:DocBook is not at all about formatting - it is about structure.

Formatting can be done in any possible way by transforming into HTML, of course.


Replying to your own posts? I tought there was an edit button someplace..

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

Postby pato » Fri Oct 25, 2002 3:45 pm

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


Oh come now, we have to fight a little! Its the Blender community after all. ;-)

ton wrote: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.

The NaN technical docs are all written in HTML, that was to make it as easy as possible for everyone to contribute. After all, try motivating an engineer to write docs, er!
These docs typically are short, and not intended to be published otherwise than made available in CVS and at the internet.

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.
The 'Documentation Board' then can define a few projects that will be done in DocBook. These are typically potential 'books', documentation that requires a more sophisticated internal structure.

If needed, people can even volunteer to convert the html into DocBook.

So, what about that?


Certainly most coders _hate_ writing documentation. Writing documentation for them needs to be effortless so we can wring the maximum amount of documentation from them. ;-) Formatted plain text would probably even be ok for now as there are lots of text2html converters running around.

The most preferable method would be to get _all_ of the docs into our documentation submission system (whatever it will be). Of course, we can only hope for this to occur if the submissions system is something simple to use like Wiki.

-Pato

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

Postby pato » Fri Oct 25, 2002 4:09 pm

xitnalta wrote:It isn't about the setup, but the comfort of all the people that make me flame here for virtually nothing. It just loses any sense for me that there are still people that don't even try to understand. :(


The trick is to know who to ignore and who to pay attention to when they speak up. That and be sure to wear your asbestos underwear! :-)


Return to “Documentation & Education”

Who is online

Users browsing this forum: No registered users and 2 guests