In here, I would like to gather all the big and small tasks that need to be done on the docs, both so I (and everyone else) gets a good overview what has to be done and also because I hope that others of the dev team and of the community will join into this little project and tick off the one or the other task.
I'll start the list with a few tasks that I stumbled over:
Difficulty: Medium (involves coding in xml, probably python)
The navigation bar is not displayed correctly (always in German) and is by the way only a replica of what is in the contents index anyway. What would make much more sense from the usage point of view is to have a breadcrumb which reflects the same structure as seen in the contents index. The search link in the navigation bar is obsolete since we have the search field in the header. However, an additional search link could be integrated into the contents index.
The language switcher always shows the british flag, regardless of which language is currently selected. With additional translations of the documentation in the future in mind, the language switcher should appear in the upper right corner as a series of flags, the currently selected one highlighted.
The documentation of the game content (object definitions, scenarios,...) is currently and was always not very comprehensible. An overhaul of these pages should:
+ include examples of the basic definition of an object/scenario. For example show a directory listing of an example scenario with a Music.ocg, System.ocg, local object definitions etc.
+ separate between the normal/basic/required files in an object/scenario and advanced stuff that may be included (Info.txt, Material.ocg, Sound.ocg...); give a guideline how a scenario/object pack etc. should be structured (in examples). F.e. stuff sound effects in their object definition or into Sound.ocg if they are scenario global sounds etc.
+ especially for object definitions with their graphics.pngs, meshes and skeletons, a grouping of the contents and their relations to each other is necessary, with examples
Reset the version numbers of all functions to OC 1.0. Reason: Clonk Rage has it's own documentation, we don't need to document for CR and earlier. Also, the signature of all functions have been changed anyway (namingly, the for_object parameter has been removed).
> Reset the version numbers
Having the old version numbers float around doesn't any harm as far as I can tell, so I think effort is better spent elsewhere :-)
Difficulty: Easy (requires knowledge of German)
For some reason, the comments and also the function names in code examples are not localized - meaning they are all in German. The function names should always be in English, the comments should be localized.
Fix code examples
Difficulty: Medium (requires knowledge of C4Script)
Many code examples don't work anymore. Let it be that the ID "ROCK" doesn't exist anymore or that something like GetX(GetCursor()) is used. All examples should be looked at and corrected.
Certain "functions" in the documentation are not written with brackets. For example OCF, VIS and other constants but also stuff like this, return, etc. There should be a possibility to define in the xml that those are written without the brackets by the xsl in the documentation.
The examples in many functions are not very helpful, not very creative. Many are something among these lines:
Makes a Clonk bigger by 100."
Overhauled examples should show a proper use case - they can be inspired or taken from an actual use in Objects.ocd or scenarios (Example), (additionally) edge cases can be shown in examples. And don't forget, we can actually include images(!) in the documentation. Since clonk is a game (engine), it might make sense to not only describe the effect a function has, but also show it.
http://docs.openclonk.org/en/sdk/definition/procedures.html still talks about physicals (should talk about ActMap properties instead)
bool Activate(object controller)on DigDouble or by context menu is probably obsolete. But isn't
void Activate(int player)still called from the rules/goals menu?
>it's the property Visibility now.
What is the property Visibility now? Do you mean instead of Set/GetVisibility() or instead of VIS_Local?
Other constants are: VIS_OverlayOnly, VIS_Owner, VIS_Allies, VIS_Enemies, VIS_God and VIS_LayerToggle (last is checked for the object's layer).
Visibility = VIS_God | VIS_Owner
Visibility = [VIS_Select, 1, 0, 0, 1] //Visible for player 0 and 3
Visibility = [VIS_Enemies] //more compatible if you don't want to write functions checking every time if you have an array or an integer.
>Visibility = [VIS_Enemies] //more compatible if you don't want to write functions checking every time if you have an array or an integer.
Since properties are public by design, my suggestion is to have two properties: Visibility and VisibilityByPlayer or similar. If Visibility=VIS_Select, the VisibilityByPlayer property is looked at by functions. Opinions?
> If Visibility=VIS_Select, the VisibilityByPlayer property is looked at by functions.
I really don't see what this gains us over having both merged into a single property. If anything, the property could use proper getter/setter functions, as you already mentioned. Pretend it'd always have to be an array if you want to keep it easy for documentation purposes.
The way how the visibility of an object is set has changed. The documentation needs to be updated to account for that. This includes removal of Set/GetVisibility, VIS_Local, add other VIS_* constants and the explanation of the behaviour of the property. Perhaps a refactor of the interface (see in above discussion). I suggest to document the property "Visibility" and include a list of all VIS constants and their explanations there.
In http://docs.openclonk.org/en/sdk/definition/script.html , everything below the heading "Control Functions" is obsolete and should be rewritten, taking into account http://forum.openclonk.org/topic_show.pl?tid=337
Which gamecalls there are exactly has not been documented. I am sure there is more than Initialize, InitializePlayer, RemovePlayer and GameOver, isn't there? Here http://docs.openclonk.org/en/sdk/scenario/script.html
More like a "standard library" for Clonk-C4Script.
What I don't like about it is that every scenario would have to include the library folder too. So unless an object package can specify other included packages itself I am not really for that idea. We can still document everything. And if we want to, we can move it later
The effects need to be migrated to use effect.variables (with proper names), the "reserved" parameter needs to be removed from an effect function. Also, perhaps the time parameter should be removed as it is available always through effect.Time.
It is now obsolete, isn't it? (Because of someobj.Bla and someobj["bla"])
Edit: Ah, one thing is missing! The title page! http://docs.openclonk.org/en/sdk/ ... well, this I will do still, but probably later
It needs more than one person to keep the documentation reasonably updated that one can rely on the information in the documentation. But seeing that the morale of the other engine devs to document their new features has been relatively good in the past, I am expecting that we can maintain it in an updated status now that the documentation is about ~up to date again.
Especially from Günther I hope to see that he becomes more anxious to finish documenting all those big changes he made (f.e.).
Powered by mwForum 2.29.7 © 1999-2015 Markus Wichitill