0

I have been given a set of XML documents from a company that is meant to include the "documentation" of the XML schema. There are no XSDs provided.

How can I generate documentation (eg. HTML or CHM) from these XML documents that includes documentation as indicated below?

Here is an example of the XML content:

<ELEMENT1>

  <!--
  documentation text ....
  -->
  <ELEMENT2>
    <ELEMENT3>ABC</ELEMENT3>
  </ELEMENT3>

  <!--
  documentation text ....
  -->
  <ELEMENT4>
    <ELEMENT5>0534564117</ELEMENT5>
    <ELEMENT6>123456</ELEMENT6>
    <ELEMENT7>090314b4-fc7d-42c5-b382-a5b745671ee32b</ELEMENT7>
  </ELEMENT4>

</ELEMENT1>
CJ7
  • 22,579
  • 65
  • 193
  • 321
  • How do you want the documentation generator to understand how documentation has to be parsed if the schema of the document is unkown? – Cédric Bignon Jan 30 '13 at 00:57
  • I thought the above might be the standard way XML documents are documented so there would be a generator to create the documentation. – CJ7 Jan 30 '13 at 00:59
  • To your mind, how, in the given example, the HTML document should look like? – Cédric Bignon Jan 30 '13 at 01:04
  • Something like: http://oxygenxml.com/samples/xml-schema-documentation/personal/personal.pdf – CJ7 Jan 30 '13 at 01:15
  • This is a documentation for XSD. It is possible to generate it because XML Schema has a specific element _xs:annotation_ used for documentation. Also, XSD files are normalized files and their rules are used by XSD documentation generator to produce their output. – Cédric Bignon Jan 30 '13 at 01:19
  • So what you're saying is that it would be difficult to achieve this using the above pattern which I have been given? – CJ7 Jan 30 '13 at 01:20
  • So they've supplied the docs in the form of sample XML data with comments? That being the case you need an XSD, you can infer one from the XML data, then you can add annotations to the XSD (basically doing what they should have done in the first place). Once you have an annotated XSD there are several tools that will produce HTML documentation i,e. http://schemas.liquid-technologies.com/Office/2003/ – Sprotty Dec 14 '16 at 15:55
  • How do you infer the XSD? – CJ7 Dec 14 '16 at 20:12

1 Answers1

2

To solve your problem there may be a solution. But it will require some work:

  1. Generate XSD from the XML files (with trang for example -> tutorial)
  2. Add the documentation to the produced XSD file (using <xs:annotation/> elements)
  3. Generate documentation from the XSD (with xs3p)

All the tools here are free. But if you can pay, oXygen seems to have very powerful features.

Cédric Bignon
  • 12,892
  • 3
  • 39
  • 51
  • If I could automatically change all the ` – CJ7 Jan 30 '13 at 01:49
  • No, the comments are in your instance document, not in the schema. I would use a tool (such as oXygen) to generate a schema, then a custom XSLT transformation to extract the comments from your instance document and create annotation elements in your schema. It has to be a custom exercise because the "documentation" format you've got is non-standard. – Michael Kay Jan 30 '13 at 08:36
  • If I extract the comments from the instance document, how could I automatically insert them in the right place in the generated XSD? – CJ7 Jan 31 '13 at 23:23
  • @CJ7 I'm sure, doing it by hand is the easiest way. – Cédric Bignon Feb 01 '13 at 00:05