Schema Documentation

[adsmart]

I'm really liking the new schema documentation feature in 4.2. Its going to make my clients really happy when I give them my schema to work with (those whom I've convinced to use Oxygen at any rate).

However, I'm running into a problem. I want to use HTML for my documentation, complete with links to the documentation for other parts of the schema. Its probable (since I'll be introducing my own tags to the documentation to make certain things easier) that the documentation I want to write will not be suitable for Oxygen.

I think that it might be benificial to have some way to distinguish between documentation for Oxygen and for other purposes. Perhaps if a particular tag (in some oxygenxml.com namespace) is encountered that content is used and the other documentation tags are ignored. Or perhaps its more appropriate to use the appinfo element if its available.

Just a thought.

[george]

Hi,

Oxygen extracts all the text content inside the schema annotation element. This should work if you have links by ignoring the link tag and presenting only the text of the link.

For performance reasons we decided to go, at least for start, with text only content. However we added some support for a couple of tags in order to be able to better format the documentation. The supported tags are p, br, ul and li. The first tags will generally add new lines while the last tag, li, will add an indent followed by an asterisk at start so that

Code: Select all

<ul>

  <li>item1</li>

  <li>item2</li>

  <li>etc.</li>

</ul>

will be rendered as:

Code: Select all

  * item1

  * item2 

  * etc.

Best Regards,
George

[Hemenkah]

I read this thread with some interest, considering that I had similar requirements to the original poster. My attempt to use any of the mentioned formatting tags proved unsuccessful in version 4.2. The inclusion of the following in a schema:
<xsd:annotation><xsd:documentation><ul><li>this</li><li>that</li><li>huh</li></ul></xsd:documentation></xsd:annotation>
does not produce any formatting... the tags and text are printed verbatim. Interestingly, enclosing the formatting in an <xsd:appinfo> element does result in some formatting... the <li> items are indented, however the tags themselves <ol>,<li>, etc are also printed....

Any ideas?

Thanks,
Kevin

[Radu]

Hi , Kevin

The support for the "p, br, ul and li" tags that George talked about seems to have been introduced after the 4.2 version was launched.

So the next version will surely contain that.

Regards, Radu.

[Hemenkah]

Thanks for the info! Spent a few hours in vain, but I've saved many more hours with the other great features of the product... In the event that anyone else out there wants/needs to cheat similar functionality in, I threw together a little perl script that I use to reprocess the generated report and substitute back in the html codes.... granted, it doesn't use correct <ul></ul> nesting, but is a decent stop gap until oxygen rolls the feature...

Code: Select all

$file = "./schema_doc.html";

open INFILE, "<  $file" or die "Couldn't open $file";

local $/ = undef; 

$slurp = <INFILE>;

close INFILE;



$subs{'<br/>'}='<br/>';

$subs{'<li/>'}='<br/> - ';

$subs{'<p/>'}='<p/>';

$subs{'<b>'}='<b>';

$subs{'</b>'}='</b>';

$subs{'<i>'}='<i>';

$subs{'</i>'}='</i>';



foreach ( keys(%subs) ) { $slurp=~s/$_/$subs{$_}/g; }

open(FILE, ">./$file");

print FILE $slurp;

Thanks again,
Kevin

[george]

Hi Kevin,

If you want to use this new funtionality and do not mind using a development snapshot please write to support@oxygenxml.com and and we will give you access to it.

Best Regards,
George

[NicoleTedesco]

Hmm...interesting thread...here's an idea: I wonder if a lot of problems could be solved if schema documentation was processed through an XSLT transform or two. That way the user could have a choice of using the default formatting (or two, or three...) or defining their own. .CSS stylesheet files would also be nice.

Generating readable API documentation from the annotations in the .XSD itself is very important for our customers. I'd write my own transforms, but I like the images you guys generate...as a work-around, is there a way of generating those images in a batch process and linking them in to my own transform?

[sorin_ristache]

Hello,

Schema documentation is generated with an XSLT transform. I think the formatting of the HTML output should be done with a .CSS stylesheet and the schema documentation dialog should add the possibility to specify it. In this way generating and formatting of the HTML code remain separate.

Take a look at the schemaDocumentation.bat (for Windows) / schemaDocumentation.sh (for Linux) script located in the install directory. It generates the documentation with all images in one directory in a batch process.

Regards,
Sorin

[sorin_ristache]

Hello,

I think the formatting of the HTML output should be done with a .CSS stylesheet and the schema documentation dialog should add the possibility to specify it.

We added the possibility to specify the path of a CSS file for the HTML output. It will be available in version 7.2.

Regards,
Sorin