Latest Posts

Topic: Forum for Documentation?

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

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

No.

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,

That is the place.

Is build-13 outdated in other respects, too?

Yes see the ChangeLog.

Regarding the "po"-directory: I had a look at the files and they look horrible to maintain - is there a dedicated editor available

It is a standard format used by most software, with many editors availabe; KBabel, Lokalize, Emacs, ....


Top Quote
SirVer
Joined: 2009-02-19, 15:18
Posts: 1439
Ranking
One Elder of Players
Location: Germany - Munich
Posted at: 2009-03-30, 20:32

The "wiki" page you found is actually another attempt at an automatic documentation system. And it is not a wiki page though it should like like one.

Eventually, both systems for the documentation of widelands should culminate into only one system that just works on the page and in-game.

!SirVer


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

sigra wrote:

Magor wrote: 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,

That is the place.

Yuk. I saw the code and thought that this looks more like a html'ed crash dumper than the end user documentation system I was looking for.

Now that "current" builds, I'll start digging through the sources and try to grok the internals to create another html dumper (or data aggregator for a post processing tool) that writes something more like "human readable documentation".

I already learned from my trial runs that such a tool needs a certain "understanding" of the provided programs to find out what the building actually produces from its input, which is actually a core question for the end-user documentation. I'll concentrate on that for a start.

Don't get me wrong, as a cross-indexer for programmers the dump given by the current build is good, but it is not built to attract players face-wink.png

Yours, Magor

PS: Yes, the current build is way better than build-13.


Top Quote
SirVer
Joined: 2009-02-19, 15:18
Posts: 1439
Ranking
One Elder of Players
Location: Germany - Munich
Posted at: 2009-03-31, 09:36

Magor,

please consider joining forces with Soeb and work on the online help on the webpage. Getting this data into the game will be easier than hacking the generation code into widelands (where it doesn't belong IMHO).

Cheers, !SirVer


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

Magor wrote: that writes something more like "human readable documentation".

It is possible to submit feature requests for improvements. I know that the worker programs are not shown as good as the productionsite programs, but that is because worker programs are not cleaned up yet (for example they still use line numbers and obscure iparam1, iparam2, sparam and such variables internally).

The links to map object types are represented with icons, not names (although the names are shown in the tooltips).

it is not built to attract players

Someone might want to pimp it with stylesheets.

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

sigra wrote:

Magor wrote: it is not built to attract players

Someone might want to pimp it with stylesheets.

I was not talking stylesheets. That is not my turf. I was talking content, like finding out that "a barbarian coal mine takes 1 ration turns them into 2 coal in 65 seconds" from reading its conf, which involves parsing and "understanding" the instructions. I am well aware that some things will not be possible (like finding out how long a farmer takes to produce one wheat), but where information can be gained, it should be turned into output.

Yours, Magor


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

SirVer wrote: please consider joining forces with Soeb and work on the online help on the webpage.

This I will propably do.

Getting this data into the game will be easier than hacking the generation code into widelands (where it doesn't belong IMHO).

I partially agree. The documentation tool should of course be external to the game, but there are a lot of sharing potential like parsing the confs and turning them into readily available internal structures.

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-31, 14:15

Magor wrote:

SirVer wrote: please consider joining forces with Soeb and work on the online help on the webpage.

This I will propably do.

Getting this data into the game will be easier than hacking the generation code into widelands (where it doesn't belong IMHO).

I partially agree. The documentation tool should of course be external to the game, but there are a lot of sharing potential like parsing the confs and turning them into readily available internal structures.

If the parser is split out from the main executable, most of the code will be shared. The documentation generator of course needs the code to parse the tribes, worlds and everything in them (building types, ware types, worker types). This parsing needs to load messages from the tribe's (and world's) textdomains. Then it needs to load some other text messages (for example titles like "Building types" or things like "Needs experience from working between %u and %u times to become". These messages are now in the widelands textdomain, but of course they could be moved into their own text domain just for the documentation generator.

It all depends on whether someone takes care of the build system and creates the infrastructure for building different executables that share some code. Then I could probably do the rest.


Top Quote
SirVer
Joined: 2009-02-19, 15:18
Posts: 1439
Ranking
One Elder of Players
Location: Germany - Munich
Posted at: 2009-03-31, 17:51

I would really love to see some of the more general stuff in widelands evolve in a kind of "widelands-lib". The documentation tool and widelands could then link to it. That would be great!


Top Quote