thoughts on documentation tools, life and the universe

Anything and everything that's related to OGRE or the wider graphics field that doesn't fit into the other forums.
User avatar
xavier
OGRE Retired Moderator
OGRE Retired Moderator
Posts: 9481
Joined: Fri Feb 18, 2005 2:03 am
Location: Dublin, CA, US
x 22

thoughts on documentation tools, life and the universe

Post by xavier »

<moderator>
The following is in reply to this post: http://www.ogre3d.org/phpBB2/viewtopic. ... fic#163732
</moderator>

BRAINLESS wrote:so I think the only real option is TeX
DocBook is probably easier than TeX -- existing DSSSL templates can produce documents in just about any format you like: PDF, HTML, CHM, and so on (including generation LaTeX IIRC).
User avatar
BRAINLESS
Goblin
Posts: 282
Joined: Tue Jan 04, 2005 6:56 pm
Location: The Netherlands

Post by BRAINLESS »

xavier wrote:
BRAINLESS wrote:so I think the only real option is TeX
DocBook is probably easier than TeX -- existing DSSSL templates can produce documents in just about any format you like: PDF, HTML, CHM, and so on (including generation LaTeX IIRC).
Thanks! Are there any good editors for this? I suppose it could be written in notepad, but I'd be writing more tags then text from the looks of it... that's probably not the intention?
Proud member of the OpenFRAG Game Development community
User avatar
xavier
OGRE Retired Moderator
OGRE Retired Moderator
Posts: 9481
Joined: Fri Feb 18, 2005 2:03 am
Location: Dublin, CA, US
x 22

Post by xavier »

If you don't mind the learning curve, there is a good Emacs mode for DocBook authoring (it's kinda the default DocBook editor, I've found). Other XML editors available have DocBook support -- I had a list at one point when I was eval'ing editors but in the end I resigned myself to learning Emacs. ;)
OvermindDL1
Gnome
Posts: 333
Joined: Sun Sep 25, 2005 7:55 pm

Post by OvermindDL1 »

I use Doxygen, can export to any of the formats listed as well, simple syntax. For things like tutorials and such as well it can also excel at (most people don't know that it can create beautifully formatted things that are not code related).

Question for BRAINLESS though (not trying to hijack). I have not looked at openfrag, but perhaps if you went in a sort of UScript style hierarchy then it would be far easier to create any type of gameplay you could think of...
User avatar
BRAINLESS
Goblin
Posts: 282
Joined: Tue Jan 04, 2005 6:56 pm
Location: The Netherlands

Post by BRAINLESS »

OvermindDL1 wrote:I use Doxygen, can export to any of the formats listed as well, simple syntax. For things like tutorials and such as well it can also excel at (most people don't know that it can create beautifully formatted things that are not code related).
I've just looked around a bit and I suppose it could be used to write documentation, but isn't it also rather limited? My requirements are:
- it has to build a table of contents (automatically).
- it has to keep track of listings (so I dont have to renumber them when I add one in the middle).
- it has to be able to show code in a different font, with ease.

Does doxygen really do that? From what I've seen it is really good for code but it does not help much on the listings or table of contents fronts.
Question for BRAINLESS though (not trying to hijack). I have not looked at openfrag, but perhaps if you went in a sort of UScript style hierarchy then it would be far easier to create any type of gameplay you could think of...
UScript = Unreal Script?

Openfrag has 1 major goal/code of conduct, EVERYTHING has to be freely available, preferably open source + free to use (even commercialy). Unreal is not free, so that is not an option. Apart from that, I'm not really sure how it would help us. Unreal can do a lot for us so in that respect it's a huge leap in the right direction, but why would it be easier to create an engine that supports different types of games then writing the entire thing ourselves?
[edit]
I just read it again and you're not suggesting to use UScript, but its hierarchy. I'll have a look at it, maybe that helps... thanks :)
[/edit]
[and another one]
Hey that looks really good, thanks! It's pretty much what I had in mind, only these guys have thought of all the useful stuff so that I dont have to, good stuff! :D
[/second edit]
Last edited by BRAINLESS on Thu Jul 20, 2006 10:31 pm, edited 1 time in total.
Proud member of the OpenFRAG Game Development community
User avatar
jacmoe
OGRE Retired Moderator
OGRE Retired Moderator
Posts: 20570
Joined: Thu Jan 22, 2004 10:13 am
Location: Denmark
x 179
Contact:

Post by jacmoe »

You can do all that in Doxygen. :wink:
You can create dox files and include them in your Doxygen build.
It does more than parse source code.
It has full support for indexing, formatting, crossreferences, sections, pages, etc.
You can write a book in only Doxygen, if you wanted to. :P

And you can set the output to latex for further processing.
/* Less noise. More signal. */
Ogitor Scenebuilder - powered by Ogre, presented by Qt, fueled by Passion.
OgreAddons - the Ogre code suppository.
User avatar
xavier
OGRE Retired Moderator
OGRE Retired Moderator
Posts: 9481
Joined: Fri Feb 18, 2005 2:03 am
Location: Dublin, CA, US
x 22

Post by xavier »

jacmoe wrote:You can do all that in Doxygen. :wink:
You can create dox files and include them in your Doxygen build.
It does more than parse source code.
It has full support for indexing, formatting, crossreferences, sections, pages, etc.
You can write a book in only Doxygen, if you wanted to. :P
The point is, I don't. I would rather use the more standard and versatile DocBook (which is what O'Reilly uses) rather than force it with something else "just because you can".
User avatar
jacmoe
OGRE Retired Moderator
OGRE Retired Moderator
Posts: 20570
Joined: Thu Jan 22, 2004 10:13 am
Location: Denmark
x 179
Contact:

Post by jacmoe »

I know you don't. You are a practical man.
I answered because BRAINLESS wanted auto table of contents, track of listings and code in different fonts.
If this is to be coupled with code documentation, why not have it all in one place?
Using one, maybe two doxygen files: one for API and one for manual.
Just a thought, that's all.

I know DocBook is powerful, but unless openFrag is planning on writing a regular book, doxygen might do the job (in a more managable fashion).
/* Less noise. More signal. */
Ogitor Scenebuilder - powered by Ogre, presented by Qt, fueled by Passion.
OgreAddons - the Ogre code suppository.
User avatar
xavier
OGRE Retired Moderator
OGRE Retired Moderator
Posts: 9481
Joined: Fri Feb 18, 2005 2:03 am
Location: Dublin, CA, US
x 22

Post by xavier »

jacmoe wrote:I know you don't. You are a practical man.
I answered because BRAINLESS wanted auto table of contents, track of listings and code in different fonts.
If this is to be coupled with code documentation, why not have it all in one place?
Using one, maybe two doxygen files: one for API and one for manual.
Just a thought, that's all.

I know DocBook is powerful, but unless openFrag is planning on writing a regular book, doxygen might do the job (in a more managable fashion).
I gathered that the intent was not to write documentation from code (which I am sorry, no one is going to convince me is a good way to do it), but instead to write actual usable documentation instead. DocBook is not just for books; it is a technical documentation DTD that, given application of the dsired DSSSL template, can be used to create book layouts (as O'Reilly does) but is also used to generate the documentation for, say, php.net and mysql.com IIRC.
User avatar
BRAINLESS
Goblin
Posts: 282
Joined: Tue Jan 04, 2005 6:56 pm
Location: The Netherlands

Post by BRAINLESS »

jacmoe wrote:I know DocBook is powerful, but unless openFrag is planning on writing a regular book, doxygen might do the job (in a more managable fashion).
Actually, that's pretty much the point... I dont want to provide just an API, which only helps when you know what you are looking for. I want to provide a text that says 'if you want to use input, here are the options'. Pretty much like Ogres manual (http://www.ogre3d.org/docs/manual/), but hopefully downloadable as a PDF or something. Something like that is much easier to use (I imagine). Besides, it's easy to start on that now, because I probably can't write much more then 10 pages, even if I exagerate the whole thing. If I wait a few months it will probably be so big that I dont even want to start on it.

I might resolve to using the wiki in the end, as I can't really think of a reason why others should not be able to edit it (except consistency, if I write it all everything will look the same). I'll have a better look at doxygen after my vacation, it's no use to start before then anyway.
Proud member of the OpenFRAG Game Development community
Lodes
Google Summer of Code Student
Google Summer of Code Student
Posts: 228
Joined: Mon Mar 17, 2003 12:02 am
Location: San Jose, CA, USA

Post by Lodes »

I personally use Lyx. It basically is a word-processor with a LaTeX backend. It is very nice and I have used it to write documentation for some small projects.

It's really great to just being able to write and never have to worry about things like table of content, layout, headers, footers, references and such as it is automatically done for you as long as you use the program correctly which is really easy.

http://www.lyx.org/
User avatar
xavier
OGRE Retired Moderator
OGRE Retired Moderator
Posts: 9481
Joined: Fri Feb 18, 2005 2:03 am
Location: Dublin, CA, US
x 22

Post by xavier »

BRAINLESS wrote:I can't really think of a reason why others should not be able to edit it (except consistency, if I write it all everything will look the same)
Consistent style makes for more readable documentation. One of the reasons I find the Ogre Wiki so largely useless is that it's a mishmash of countless different styles and meanings and assumptions. You *want* a consistent style throughout; that is one of the reasons APress has a copyeditor going over the Ogre book with a fine-tooth comb right now, to ensure consistenty from page to page and chapter to chapter.

[edit: and for finding typos that Word did not catch, LOL]
User avatar
jacmoe
OGRE Retired Moderator
OGRE Retired Moderator
Posts: 20570
Joined: Thu Jan 22, 2004 10:13 am
Location: Denmark
x 179
Contact:

Post by jacmoe »

I chose to use doxygen for the OgreOpcode manual, because it's not going to be more than 10 pages anyway, and because with doxygen I am able to package it nicely in a compiled html help file, complete with manual, tutorial and API documentation.
All it takes is a couple extra dox files, which are text with doxygen markup tags.
I considered DocBook, but that means that I have to click a couple extra buttons when generating documentation ..

Well, each to his own I guess. :)
/* Less noise. More signal. */
Ogitor Scenebuilder - powered by Ogre, presented by Qt, fueled by Passion.
OgreAddons - the Ogre code suppository.
OvermindDL1
Gnome
Posts: 333
Joined: Sun Sep 25, 2005 7:55 pm

Post by OvermindDL1 »

And yea, they answered the Doxygen question. I've used some API's that write some very nice tutorials and such with doxygen.

And yes, Unreal Script code, not referring to UScript itself, but rather how it is designed. You can use UScript to make the game be just about anything you want it to be. UScript is very C++ like and could translate to C++ near perfectly. The design that I am talking about (is also what I am doing in my project), there is a root Actor class. There are controllers, from those PlayerControllers and AiControllers. Any controller can control any Pawn. Any controller's camera can be set individually to another object. I have an old test setup from when I first designed it that allows you to hop between hover vehicles, right click to posses, middle click to just switch camera (to what you are pointing), middle click while aiming at nothing to switch camera back to what you are currently possessing. When possessed then the controller receives all events that the pawn receives. Etc...

I've recently been converting it to Python and it converts even better. I've got UScript style states, I've got decorators that make such n' such functions are only called on the server or client. I have decorators that, for example, well, let me just copy what I posted elsewhere:
I just keep loving python more and more the more I work with it. Image

Example:

Code: Select all

class Player(_Player):
	# *snip*

	def Say(self, Msg):
		Msg = Msg[0:128]
		if self.AllowTextMessage(Msg):
			self.ServerSay(Msg)

	@replicateCallToServer
	def ServerSay(self, Msg):
		if self.isAdmin and Msg[0]=='#':
			Msg = Msg[1:]
			for C in ActiveLevel.ControllerList:
				if isinstance(C, PlayerController):
					C.ClearProgressMessages()
					C.SetProgressTime(6)
					C.SetProgressMessage(0, Msg, Color(255,255,255))
			return
		ActiveLevel.Game.Broadcast(self, Msg, 'Say')

	# *snip*
This minor example is nice in that if a player calls Say, like Say("Hey, what's up?"), then if the message is valid (checks that they aren't spectator or whatnot), it then calls ServerSay with the same params. You see the @replicateCallToServer though, that is something I just made and tested. It changes the following function to only be called when one of two conditions are fullfilled. The first condition, if this system is running on the server, it will be called immediatly. The second is that if the system is running on a Client, then all of the parameters will be packaged up and sent to the server where the same function on the same instance of the same object (everything that is replicated has a unique id for every instance) will be called with the same parameters. Doesn't matter how many, if any arguments the function takes, whether it has any optional arguments, doesn't matter. I just wrapped up an entire complicated member function remote call setup into a nice little definition. Image

EDIT: Oh, for note, it can also call any C/C++ methods of the class that are rpc or python exposed. :)
Also recently got latent functionality working in it without using greenlets or stackless. And since Pythons binds so perfectly to C++, especially with its extension modules, anything slow can be sped right up. I have it mimicking UScript very closely, and it is working wonderfully.
User avatar
Levia
Halfling
Posts: 45
Joined: Fri Feb 03, 2006 9:56 pm
Location: The Netherlands

Post by Levia »

Thats the good thing about oF. When suggested we consider it, and when usefull it will most probably be added.

..
I guess doxygen isnt made for big manuals/documentation ;) I would write it in wiki ofcourse.
User avatar
BRAINLESS
Goblin
Posts: 282
Joined: Tue Jan 04, 2005 6:56 pm
Location: The Netherlands

Post by BRAINLESS »

Lodes wrote:I personally use Lyx. It basically is a word-processor with a LaTeX backend. It is very nice and I have used it to write documentation for some small projects.

It's really great to just being able to write and never have to worry about things like table of content, layout, headers, footers, references and such as it is automatically done for you as long as you use the program correctly which is really easy.

http://www.lyx.org/
Thanks a lot! This looks like a winner! :)

OvermindDL1: that looks really good! Since I'm using yake I'm pretty sure we'll use LUA, but for now it's C++ only. LUA also binds with C++ really well, so it should not be very different from your situation. It will be a while until we get to that point though, we must first get a decent demo up and running before we can start thinking of these things. Thanks a lot for the pointer to, UScript could definitely be a line to hold on to when we need inspiration!

May I suggest that if anyone wants to continue this discussion they create a new thread and post a link here, so that Deamon can have his own thread back ;)
Proud member of the OpenFRAG Game Development community
User avatar
jacmoe
OGRE Retired Moderator
OGRE Retired Moderator
Posts: 20570
Joined: Thu Jan 22, 2004 10:13 am
Location: Denmark
x 179
Contact:

Post by jacmoe »

He just got his topic back!
Feel free to pursue the quest for the ultimate doc tool in this topic. :wink:
/* Less noise. More signal. */
Ogitor Scenebuilder - powered by Ogre, presented by Qt, fueled by Passion.
OgreAddons - the Ogre code suppository.
OvermindDL1
Gnome
Posts: 333
Joined: Sun Sep 25, 2005 7:55 pm

Post by OvermindDL1 »

If you are using LuaBind, that is based off of boost::python (what I use), so I know how easy it is. Image

I chose not to use it because it does not have an equivilent to function decorators in python, nor can I automark variables dirty when they are modified to a different value, including setting reliability information when replicated, nor latent functions.

I used to use LUA before I discovered binding with Python.

Don't forget that Yake supports multiple scripting systems so a python version could be made.
User avatar
BRAINLESS
Goblin
Posts: 282
Joined: Tue Jan 04, 2005 6:56 pm
Location: The Netherlands

Post by BRAINLESS »

OvermindDL1 wrote:Don't forget that Yake supports multiple scripting systems so a python version could be made.
Yes, it supports multiple scripting systems... but only one exists (LUA). I'd have to write a Python one myself ;)

Perhaps I'll do that though... it'll depend on how much time I've got and what we expect to need by then.

btw, thanks to whoever moderated this out of the other topic
Proud member of the OpenFRAG Game Development community
OvermindDL1
Gnome
Posts: 333
Joined: Sun Sep 25, 2005 7:55 pm

Post by OvermindDL1 »

I could probably help with it if you so wished.
User avatar
BRAINLESS
Goblin
Posts: 282
Joined: Tue Jan 04, 2005 6:56 pm
Location: The Netherlands

Post by BRAINLESS »

OvermindDL1 wrote:I could probably help with it if you so wished.
To be honest, I currently have no idea (at all) how scripting works or how to use it. So any help is appreciated! :) I've always wondered what the definite advantage of scripting was, as everything can be done in C++ as well. I suppose some things are easier, but if we would move some things entirely to a script it would require developers of openfrag plugins to learn that language as well. I'm not sure how bad that is though.
Proud member of the OpenFRAG Game Development community
User avatar
xavier
OGRE Retired Moderator
OGRE Retired Moderator
Posts: 9481
Joined: Fri Feb 18, 2005 2:03 am
Location: Dublin, CA, US
x 22

Post by xavier »

I participated in a debate on this exact topic here at work the other day -- the actual usefulness of scripting in a game engine. Many good arguments were made against using a Turing-complete scripting language as well as compiled C++ code. One point made was that you could just as easily give the designers Visual Studio and a set of macros and save yourself the bother of trying to bolt a scripting language onto the engine and then having to create an IDE for them to debug with as well. I had a hard time arguing with that one. In the end, we all agreed that it's probably best just to give the designers a non-Turing-complete imperative command-driven language (batch scripting, in other words) that they can use to script responses to events or conditions. At the end of the day, that's really all they need or want, you'll find out. If your engine or game is designed to be heavily modded, you might find that having some actual language support for things like UI scripting (events logic) could be useful. Lua serves both of these purposes -- the designers to not have to know they are using Lua -- just give them a list of commands your engine supports and they'll be fine (and happier for not having to learn an actual language). And you can use the same full-featured script language for mroe complicated things like UI scripting.

My $0.02. The debate certainly changed some of my views on the propriety of scripting at all in a game.
User avatar
BRAINLESS
Goblin
Posts: 282
Joined: Tue Jan 04, 2005 6:56 pm
Location: The Netherlands

Post by BRAINLESS »

First draft of our developers guide...

http://files.openfrag.org/Members/brain ... 0guide.pdf

This was at first written in LyX, thanks Lodes!, but I have since switched back to pure TeX. TeX supplies exactly the kind of formatting I am looking for, and LyX sometimes messed up. Luckily, LyX simply exports TeX files, so I didn't have to start all over again. I still have to figure out a few things (like how to exclude the sample listing from being numbered), but I know it's easy to do that. I'm not sure, but I think I could even export this thing straight to HTML if I wanted to. PDF is alright for now though. I love the way it does code-formatting all by itself now :)
Proud member of the OpenFRAG Game Development community
rogma
Halfling
Posts: 73
Joined: Fri May 07, 2004 5:03 pm
Location: Issy les Moulineaux, France
Contact:

Post by rogma »

Concerning docbook, two editors :

http://vex.sourceforge.net/ --> a wysiwyg xml and docbook plugin for eclipse
http://www.xmlmind.com/xmleditor/ xmlmind editor; a very good wysiwyg docbook (and more) editor

...
User avatar
sinbad
OGRE Retired Team Member
OGRE Retired Team Member
Posts: 19269
Joined: Sun Oct 06, 2002 11:19 pm
Location: Guernsey, Channel Islands
x 66
Contact:

Post by sinbad »

I wanted to use DocBook when I started the manual, but I couldn't find a decent editor at the time to make it more bearable to write, and the HTML conversion tools I tried seemed pretty cumbersome and hit-and-miss. There were some decent commercial tools for it but nothing that great in the open source department - hence why I plumped for Tex too, since it's quick to write, and the HTML tools actually worked.

Things might have changed now and DocBook might have better and more usable free tools, but often you have to just go with what works, rather than take a purist approach.

@xavier: we all know you don't like the wiki, but it isn't a book, and thus should not be judged on the same criteria. It's a distillation of community knowledge, and yes that means that quality and style are not consistent, but you have to take the good with the bad - and the good is that the wiki is constantly being updated with useful information, far more than if it were locked down to the extent required of a book.

Saying it isn't like a book really isn't the point, and reflects more of your personal preference / expectation than the base utility of it. Books gain in consistency, quality and readability. The wiki gains in being more actively updated (since a book is static) and covering a wider range of topics. They do different things, and both are valid learning tools - the fact that you don't like the style of one of them doesn't mean other people don't find it useful. I think the prevalence of wikis in open source projects of all kinds show that people do - we even use one at work for internal developer tips and guides that don't fit into official documentation; when you have a good tip it's essential to put it somewhere rather than nowhere, and a wiki is fast to use, and searchable, meaning it's far more likely to get used than traditional Word deliverable docs. I would far rather a hint / tip was placed in an unstructured (but searchable) wiki than sit invisibly in someone's TODO list for writing up 'properly'.

You will never square the circle of being 'very actively updated' and 'high quality reviewed material', (well, perhaps without dedicated staffers ;)). They are diammetrically opposed when your primary resources are a community. IMO you're better to have 2 different resources which each major in one particular direction, then you have both bases covered.
Last edited by sinbad on Sat Jul 22, 2006 12:20 pm, edited 1 time in total.
Post Reply