Macro to render documentation from source in wiki

[skyper]

In the last time we had some discussions about documentation.
One problem is that we often have documentation in source but not in the wiki. To keep documentation in two different places does not work that well as you have to the work twice as otherwise it gets out of sync.

Would be nice to have a macro which renders documentation from source nicely in the wiki.

[stoecker]

What documentation in source?

[skyper]

Replying to stoecker:

What documentation in source?

Eg Syntax of OpenLocation, defaultpreset etc.

[stoecker]

You can reference to source code and files, but we don't have any standardized format for additional information in source code, so I don't see how a further integration into the wiki should work.

Make a proposal how it should look like.

[skyper]

Replying to stoecker:

You can reference to source code and files, but we don't have any standardized format for additional information in source code, so I don't see how a further integration into the wiki should work.

Was just an idea.

Make a proposal how it should look like.

I will but have to think about it. We probably need some key in the comment section and a simple syntax. We will probably only have definitions, some free text (examples)

[stoecker]

P.S. For temporary macros you don't need to use SandBox or alike, which I will delete again, but simply use the Preview :-)

[skyper]

Replying to stoecker:

P.S. For temporary macros you don't need to use SandBox or alike, which I will delete again, but simply use the Preview :-)

Sorry, why is it saved anyway ?

[skyper]

For a simple documentation like defaultpresets.xml it is not that tricky, but I tried to document Open Location and I was not really able to find all the parts which produce the error warning and explain the usage. For this part we would need to proper interpret the code I guess.

For the beginning, a simple approach would be to render (parts of) a file (attachment and repository) with an optional line argument for the parts. This would be useful for non-binary, regular file.

[skyper]

I found the ​Include Macro which should do the job. Could it be installed ?

[stoecker]

What would that macro help? Including a whole part of a source code is not helpful. I still don't understand what your intention is.

[skyper]

Replying to stoecker:

What would that macro help? Including a whole part of a source code is not helpful. I still don't understand what your intention is.

My intention is to not have to document everything twice and e.g. display the first part of source:trunk/data/defaultpresets.xml.

As I read now it does not have an optional argument for lines (or parts of other wiki pages) and is not useful, you are right.

[stoecker]

While the idea is understandable I fear the effort to reach that goal is not so easy and use is limited. For example regarding defaultpresets: Improving the TaggingPresets wikipage and dropping the comments in the XML is the preferred way. No need to have that in the SVN at all.

[skyper]

Replying to stoecker:

While the idea is understandable I fear the effort to reach that goal is not so easy and use is limited. For example regarding defaultpresets: Improving the TaggingPresets wikipage and dropping the comments in the XML is the preferred way. No need to have that in the SVN at all.

For a long time, the comments in the XML were and still are the up-to-date documentation. Thought this was the preferred way and the wiki only a bonus. As the wiki is nicely updated at the moment considering MapCss Styles, the same could be achieved for TaggingPresets.

[stoecker]

Replying to skyper:

Thought this was the preferred way and the wiki only a bonus.

It is not preferred, only historic. The XML was much earlier.

[stoecker]

For presets: I now removed the text in XML and copied it to the wiki. Klumbumbus already started to integrate many parts of it. Feel free to help as well.