Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to format XSD documentation?

Tags:

xml

xsd

The Problem:

I have a xsd schema with included documentation, like:

<xs:element name="Tag" type="XTag">
  <xs:annotation>
    <xs:documentation>
      Do like this:
       - foo
       - bar
    </xs:documentation>
  </xs:annotation>
</xs:element>

When I view the documentation in Eclipse, the white-spaces are truncated to a single space, so I end up with:

Do like this: - foo - bar

This naturally limits readability when documentation is more than a little note. In javadoc for instance, one can one html tags to format the documentation

The question:

Is there any way to format the documentation, at least just adding newlines?

Some details:

I'm doing everything in Eclipse. The XSD i write is added to preferences -> XML -> XML catalog, so I can get content assist and view documentation in the XML editor.

It's an internal tool and the only foreseeable place the documentation will be viewed is through Eclipse in the way described above. So if it works in eclipse, it's good enough :)

like image 991
Tobber Avatar asked Jun 19 '12 16:06

Tobber


People also ask

What is XSD documentation?

An XML schema definition (XSD), is a framework document that defines the rules and constraints for XML documents. An XSD formally describes the elements in an XML document and can be used to validate the contents of the XML document to make sure that it adheres to the rules of the XSD.

How do I create an XSD file?

In Visual Studio, open the File menu and select New > File. Or, use the Ctrl+N keyboard shortcut. In the New File dialog box, select XML Schema and then select Open. A new file is created.

How do I edit an XSD file?

In the context menu of an XSD file, choose Open . The XSD editor opens. In the context menu of Elements on the Design tab page, choose Add Element . Select an element under Elements and define its properties in the Properties view.

How do I create an XSD file in Excel?

Select any cell in the EXCEL table. On the ADD-INS tab, in the Menu commands group, click the arrow next to the XML Tools and then click Create XSD file for the XML Schema. In Notepad, click File and Save AS.


2 Answers

Try using html like <br/> for newline and List<ul><li>item</li></ul> for list items.

Not sure if you should be embedding "under construction" animated gifs or even tables though. It worked for me while documenting an xsd and creating a corresponding xml using oXygen XML editor.

like image 20
jos Avatar answered Sep 28 '22 13:09

jos


Embed your documentation into <![CDATA[ ]]> and use html expressions. Sample below should be rendered correctly.

<xs:annotation>
    <xs:documentation>
    <![CDATA[
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.<br/>
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 
<p><b>Duis aute</b> irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. </p>
<br/>
<b>Excepteur sint occaecat cupidatat non proident,<br/>
<ul>
    <li>sunt in culpa qui officia</li> 
    <li>deserunt mollit anim</li>
    <li>id est laborum.</li>
</ul>
    ]]>
    </xs:documentation>
</xs:annotation>

Tested with Spring Tool Suite v3.6.4 (Eclipse 4.4.2)

like image 160
vahapt Avatar answered Sep 28 '22 14:09

vahapt