Modify

Opened 2 weeks ago

Last modified 9 days ago

#19282 new enhancement

[PATCH] Add documentation from wiki to Presets XSD

Reported by: hiddewie Owned by: team
Priority: minor Milestone:
Component: Core Version:
Keywords: schema xsd presets documentation Cc: stoecker

Description

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

Attachments (2)

Screenshot from 2020-05-23 18-37-23.png (60.5 KB) - added by hiddewie 2 weeks ago.
Add_documentation_to_XSD_for_default_presets.patch (32.7 KB) - added by hiddewie 2 weeks ago.

Download all attachments as: .zip

Change History (6)

Changed 2 weeks ago by hiddewie

comment:1 in reply to:  description ; Changed 13 days ago by simon04

Cc: stoecker added
Keywords: schema xsd presets documentation added

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?

comment:2 in reply to:  1 Changed 12 days ago by 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

comment:3 Changed 9 days ago by 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/

comment:4 Changed 9 days ago by 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...)

Modify Ticket

Change Properties
Set your email in Preferences
Action
as new The owner will remain team.
as The resolution will be set.
to The owner will be changed from team to the specified user.
The owner will change to hiddewie
as duplicate The resolution will be set to duplicate.The specified ticket will be cross-referenced with this ticket
The owner will be changed from team to anonymous.

Add Comment


E-mail address and name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.