Important Dates

Latest Posts

Topic: Forum for Documentation?

Magor
Joined: 2009-03-30, 07:38
Posts: 36
Ranking
Pry about Widelands
Location: Königswinter, Germany
Posted at: 2009-03-30, 08:35

Hi!

I'm new to the Widelands (downloaded that addictive game just two days ago) and I am hooked. My wife is less than impressed face-wink.png

OK. What the game is surely missing is documentation. But I'm not here to complain, I'm here to join in, as this is clearly a "scratch the itch"-issue here.

So I started a project called WDT (Widelands Documentation Tool). In the end, this should read all the conf files and generate a fully human readable crossreferenced documentation, either as html or wiki, maybe even in an internal format for integration in the game. But that is the far future...

At the moment it just reads buildings' confs, gobbles up some basic information and turns them into text:

(Example from the barbarians)

Fisher's Hut - is a small sized production building employing fisher. - is built using 4 trunk.

Fortress - is a big sized military building. - is built using 9 blackwood, 5 trunk, 4 raw_stone and 2 grout.

Gamekeeper's Hut - is a small sized production building employing gamekeeper. - is built using 4 trunk and 1 raw_stone.

Gold Mine - is a mine type production building employing miner. - is built using 4 trunk and 2 raw_stone. - turn ration into goldstone (0).

Granite Mine - is a mine type production building employing miner. - is built using 4 trunk and 2 raw_stone. - turn ration into raw_stone:2 (0).

Wood Hardener - is a medium sized production building employing lumberjack . - is built using 3 trunk and 1 raw_stone. - turn 2 trunk into blackwood (0).

(End of example)

My questions: a) How stable is the conf design? Are there plans for bigger changes like "go XML" in the future? b) There are forums for grafics, sound, etc, but none for documentation and development. Will those come? c) Is there the need for such a tool at all? d) Whom/Where can I ask about conf files? Farmers, Fishers, etc are still a bit confusing (as you can see from the lack of information on produce).

Yours, Magor AKA Christian Treczoks


Top Quote
sigra
Joined: 2009-03-05, 19:02
Posts: 130
Ranking
At home in WL-forums
Location: Orsa
Posted at: 2009-03-30, 08:58

Magor wrote: read all the conf files and generate a fully human readable crossreferenced documentation, either as html

This is already implemented in the current development version. Get revision 3746 (or newer). Execute "./widelands --editor --language=de_DE --write_HTML=yes".

It will write browsable crossreferenced xhtml-files for ware types, worker types and building types. There will be a file with a table of all worker types, one for all worker types and one for all building types. Then there will be a file called index_de_DE.xhtml for each individual type.

the --editor parameter is just there because the editor loads all tribes when it starts, so you will get the documentation for all tribes. If you just start the program and play a game, it may not load all tribes (and therefore not write documentation for them).

The --language=de_DE parameter is just used to get different filenames for the files in different languages (de_DE) is just an example of a language that Widelands is translated into.

The --write_HTML=yes parameter tells the program to write the files. This is necessary because the program could not write the files each time a tribe is loaded, since the game data may be installed in a system location that the user does not have write access to.


Top Quote
Magor
Joined: 2009-03-30, 07:38
Posts: 36
Ranking
Pry about Widelands
Location: Königswinter, Germany
Posted at: 2009-03-30, 09:23

sigra wrote: This is already implemented in the current development version.

Great! Saves me a lot of work.

In what directory can the generated html files be found?

Yours, Magor


Top Quote
sigra
Joined: 2009-03-05, 19:02
Posts: 130
Ranking
At home in WL-forums
Location: Orsa
Posted at: 2009-03-30, 09:34

The tables of all ware types, worker types and building types are in the tribe's directory. The pages for each type is in the type's directory.


Top Quote
Magor
Joined: 2009-03-30, 07:38
Posts: 36
Ranking
Pry about Widelands
Location: Königswinter, Germany
Posted at: 2009-03-30, 10:41

sigra wrote: The tables of all ware types, worker types and building types are in the tribe's directory. The pages for each type is in the type's directory.

OK, I'll have a look at this when I'm home.

Will this be fixed to the effect to put all these files into a "doc" directory instead?

How about adding files with additional documentation into the directories like barbarians/buildings/fisherhut/info containing:

[global]

encoding=ISO8859-15

name=Fishers Hut

[description] The fishers hut should be located near a sufficiently sized body of water. There, the fisher can catch fish to sustain the food economy with an alternative to meat.

Alternatively, there could be additional info files for additional languages at least to provide the documentation generator with the correct object name in the target language (and maybe additionally needed words like correct articles for the generated part of the documentation). Example: barbarians/buildings/fisherhut/info.de_DE containing:

[global]

encoding=html

name=Fischerhütte

[description]

Eine Fischerhütte sollte in der Nähe eines ausreichend großen Gewässers liegen. Der Fischer kann dort Fische fangen, die als Alternative zu Schinken in der Nahrungsmittelproduktion eingesetzt werden können.

Yours, Magor


Top Quote
sigra
Joined: 2009-03-05, 19:02
Posts: 130
Ranking
At home in WL-forums
Location: Orsa
Posted at: 2009-03-30, 11:11

Magor wrote: Will this be fixed to the effect to put all these files into a "doc" directory instead?

No, there is no need for that. The doc files should be in the same directory as the images which they embed (otherwise it would be a mess with paths). And it should be really easy to go from the index_de_DE.xmthl file to another file (for example the conf file). It should be as easy as replacing the last part of the path in the browser address bar.

How about adding files with additional documentation into the directories like barbarians/buildings/fisherhut/info containing: [global] encoding=ISO8859-15 name=Fishers Hut [description] The fishers hut should be located near a sufficiently sized body of water. There, the fisher can catch fish to sustain the food economy with an alternative to meat.

This should be in the conf file (help=...)

Alternatively, there could be additional info files for additional languages at least to provide the documentation generator with the correct object name in the target language (and maybe additionally needed words like correct articles for the generated part of the documentation). Example: barbarians/buildings/fisherhut/info.de_DE containing: [global] encoding=html name=Fischerhütte [description] Eine Fischerhütte sollte in der Nähe eines ausreichend großen Gewässers liegen. Der Fischer kann dort Fische fangen, die als Alternative zu Schinken in der Nahrungsmittelproduktion eingesetzt werden können.

The translations are in po/de_DE/tribes and already work.


Top Quote
Magor
Joined: 2009-03-30, 07:38
Posts: 36
Ranking
Pry about Widelands
Location: Königswinter, Germany
Posted at: 2009-03-30, 11:35

sigra wrote:

Magor wrote: Will this be fixed to the effect to put all these files into a "doc" directory instead?

No, there is no need for that. The doc files should be in the same directory as the images which they embed (otherwise it would be a mess with paths).

While I agree with either the paths being messy or having to do unnecessary copying of files, I thought about the latter to have an independent, external documentation. But this I can do by myself, if needed.

This should be in the conf file (help=...)

This is propably just for a short help of one line, or can one use several help entries in a conf?

The translations are in po/de_DE/tribes and already work.

Oh my. I never looked in that directory. Any reason to call it "po" instead of "translations" or "i18n"?

Yours, Magor


Top Quote
sigra
Joined: 2009-03-05, 19:02
Posts: 130
Ranking
At home in WL-forums
Location: Orsa
Posted at: 2009-03-30, 12:07

Magor wrote: This is propably just for a short help of one line, or can one use several help entries in a conf?

Values can be multiline (see for example the messages in the tutorials).

Oh my. I never looked in that directory. Any reason to call it "po" instead of "translations" or "i18n"?

It is a standard name used in very many projects.


Top Quote
Magor
Joined: 2009-03-30, 07:38
Posts: 36
Ranking
Pry about Widelands
Location: Königswinter, Germany
Posted at: 2009-03-30, 13:18

sigra wrote:

This is already implemented in the current development version. Get revision 3746 (or newer). Execute "./widelands --editor --language=de_DE --write_HTML=yes".

I went home for lunch and checked this. No do ;-), but all I have is build-13. OK, it is not "current developer version", so that's fixable.

Is build-13 outdated in other respects, too?

I started SVNing down the development version and will be building this evening.

Regarding the "po"-directory: I had a look at the files and they look horrible to maintain - is there a dedicated editor available, or is the editor in the game also an editor for those files, too?

Yours, Magor (who can't wait to build the current version...)


Top Quote
Magor
Joined: 2009-03-30, 07:38
Posts: 36
Ranking
Pry about Widelands
Location: Königswinter, Germany
Posted at: 2009-03-30, 14:29

I just found the documentation I was originally searching for in the Wiki (http://wl.widelands.org/help/barbarians/buildings/). I'm sure it was not there yesterday, but I heard something about recovering the wiki after a crash, so I propably just found the game at the wrong time.

Is that Wiki-page based on the automatic documentation system you referred to?

I noticed that the column "description" is generally empty. Is this where the "help=" option of the conf comes into play?

And where in the sourcecode is the function that actually writes the html code? I ran Doxygen over the source, but all I found was write_HTML.cc, which looks more like a dumper for a running game than a documentation generator...

I hope I don't annoy you with all my requests and questions. I'm eager and willing to help with the project where I can, but it is quite a big project, and it's in cc, which is not my favourite (I do embedded systems, so I usually deal with .c and .vhdl). But I don't mind doing documentation, both english and german.

Yours, Magor


Top Quote