[PATCH] Add documentation from wiki to Presets XSD

[hiddewie]

The Presets XSD is the reference document for developing internal and external presets. There is good documentation in the wiki (https://josm.openstreetmap.de/wiki/TaggingPresets) but this sometimes has missing keys and may be outdated.

This patch adds the documentation from the wiki to the XSD. This would make the XSD leading. Wiki content may be generated from the document. In addition to this, using the XSD can show the relevant documentation straight in the IDE, without having to reference the wiki (screenshot).

In addition, having the documentation of XML tags and attributes in a different document than an XSD seems a maintanance burden because information lives in two places.

Some items were fixed that were mentioned in the wiki but not in the XSD:

• name_context was missing as attributes
• text_context was missing next to 1 text attribute
• list_entry has no documentation for some attributes

[simon04]

Replying to hiddewie:

This patch adds the documentation from the wiki to the XSD. This would make the XSD leading. Wiki content may be generated from the document.

@stoecker, can we use the XSD file to generate the Trac wiki documentation?

[stoecker]

Replying to simon04:

@stoecker, can we use the XSD file to generate the Trac wiki documentation?

Well. That depends. I don't plan to write a XSD to wiki parser script. So

• if there is an adaptable existing solution: Yes
• if there is nothing: No

[hiddewie]

I looked into some tooling and FlexDoc XSDDoc [1] seems the most flexible, but still produces totally ugly/unusable results for simple XSDs. Apparently there does not exist a simple tool that outputs element and attribute documentation for a given XSD. It would be possible to write this with an XSLT, but that would be pretty complex.

If not being able to generate the wiki docs from the XSD is a blocking issue for adding documentation to the XSD, this ticket may be closed. In that case I can make a patch containing only the small number of problems I found between the wiki and the XSD.

[1] ​https://www.flexdoc.xyz/flexdoc-xml/xsddoc/

[stoecker]

Please add the necessary changes to the wiki. I'm not against applying this patch nevertheless, thought it will not solve the "documented elsewhere and twice" issue if we can't autogen the wiki (but that may change...)

[simon04]

In 16638/josm:

fix #19282 - Add documentation from wiki to tagging-preset.xsd (patch by hiddewie)

[simon04]

In 16639/josm:

see #19282 - Use CDATA inside tagging-preset.xsd

[simon04]

In 16640/josm:

see #19282 - Add TaggingPresetSchemeWikiGenerator to generate wiki content from tagging-preset.xsd