Page 1 of 1

Drop annotations from generated Source section

Posted: Tue Mar 09, 2010 2:16 am
by htello
The Schema document generator includes an Annotation section under the namespace. The source also has the annotation element and whatever documentation contents are within that the xsd annotation element.

For a schema with lots of documentation, showing the annotation documentation twice really distracts from the source view. As I'm not an XSLT expert, any quick hints on how I can alter the XSLT files so that the annotations are excluded from the source section but remain in the Annotations section? Are they a particular token type?

Re: Drop annotations from generated Source section

Posted: Wed Mar 10, 2010 6:59 pm
by adrian
Hello,

There is no built in way to exclude annotations from source.

The documentation process uses an intermediate xml format on which it applies a stylesheet in order to obtain HTML/PDF etc. It is possible to modify that stylesheet (frameworks\schema_documentation\xsl\xsdDocHtml.xsl for HTML format or frameworks\schema_documentation\xsl\xsdDocDocbook.xsl for Docbook or PDF format)to exclude annotations from the source. See template formatXmlSource.

I'll have to see if I can modify the stylesheet to do what you need.

Regards,
Adrian

Re: Drop annotations from generated Source section

Posted: Thu Mar 11, 2010 5:16 pm
by adrian
Hi,

HTML
Open frameworks\schema_documentation\xsl\xsdDocHtml.xsl and look for a template named formatXmlSource. Replace it with the templates found here:

Code: Select all

<xsl:template name="format">
<xsl:param name="tokens"/>
<xsl:param name="index" as="xs:integer"/>
<xsl:param name="skip" as="xs:boolean"/>
<!-- test if we should skip-->
<xsl:variable name="token" select="$tokens[$index]"/>
<xsl:choose>
<!-- Ignore all tokens starting with this one -->
<xsl:when test="$token/@type = 'tEl' and $token/text() = '<xs:annotation'">
<xsl:call-template name="format">
<xsl:with-param name="tokens" select="$tokens"/>
<xsl:with-param name="index" select="$index+1"/>
<xsl:with-param name="skip" select="true()"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:choose>
<!-- Process all tokens after this one -->
<xsl:when test="$token/@type = 'tEl' and $token/text() = '</xs:annotation>'">
<xsl:call-template name="format">
<xsl:with-param name="tokens" select="$tokens"/>
<xsl:with-param name="index" select="$index+1"/>
<xsl:with-param name="skip" select="false()"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<!-- Keep the current state. Either ignore or process. -->
<xsl:if test="not($skip)">
<xsl:element name="span">
<xsl:attribute name="class" select="$token/@type"/>
<!-- On IE the pre-wrap does not normalize the text. Doing it here. -->
<xsl:choose>
<xsl:when test="$token/@type = 'tokenText'">
<xsl:choose>
<xsl:when test="$token/text() = ' '">
<!-- Just a whitespace should preserve it,
may be it dellimits something. -->
<xsl:text xml:space="preserve"> </xsl:text>
</xsl:when>
<xsl:otherwise>
<xsl:choose>
<xsl:when test="$token/@xml:space = 'preserve'">
<xsl:value-of select="$token/text()"/>
</xsl:when>
<xsl:otherwise>
<!-- Because we normalize there is no need to keep the whitespace preserve -->
<xsl:attribute name="style">white-space:normal</xsl:attribute>
<xsl:value-of select="normalize-space($token/text())"/>
</xsl:otherwise>
</xsl:choose>
</xsl:otherwise>
</xsl:choose>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$token/text()"/>
</xsl:otherwise>
</xsl:choose>
</xsl:element>
</xsl:if>

<xsl:if test="count($tokens) > $index">
<xsl:call-template name="format">
<xsl:with-param name="tokens" select="$tokens"/>
<xsl:with-param name="index" select="$index+1"/>
<xsl:with-param name="skip" select="$skip"/>
</xsl:call-template>
</xsl:if>
</xsl:otherwise>
</xsl:choose>

</xsl:otherwise>
</xsl:choose>



</xsl:template>

<xsl:template name="formatXmlSource">
<xsl:param name="tokens"/>

<!-- I have to put the PRE in a TABLE to convince the Internet Explorer
to wrap the PRE. In addition to putting it into a table, the css
must contain the bloc:

pre {
white-space: pre-wrap; /* css-3 */
white-space: -moz-pre-wrap; /* Mozilla, since 1999 */
white-space: -pre-wrap; /* Opera 4-6 */
white-space: -o-pre-wrap; /* Opera 7 */
word-wrap: break-word; /* Internet Explorer 5.5+ */
_white-space: pre; /* IE only hack to re-specify in addition to word-wrap */
}
-->
<table
style="table-layout:fixed;white-space:pre-wrap;white-space:-moz-pre-wrap;white-space:-pre-wrap;white-space: -o-pre-wrap;word-wrap: break-word;_white-space:pre;"
class="preWrapContainer">
<tr>
<td width="100%">
<pre>
<xsl:call-template name="format">
<xsl:with-param name="tokens" select="$tokens"/>
<xsl:with-param name="index" select="1"/>
<xsl:with-param name="skip" select="false()"/>
</xsl:call-template>
</pre>
</td>
</tr>
</table>
</xsl:template>
To use this customized stylesheet in the Schema Documentation dialog you have to select Format -> Custom instead of HTML/PDF/Docbook, press Options and browse for the stylesheet. Make sure the Output file has the .html file extension(Default for HTML is ${cfn}.html).


PDF
For PDF it's a bit more complicated. First you have to make the same modifications to frameworks\schema_documentation\xsl\xsdDocDocbook.xsl. And just as for HTML choose the stylesheet in the the Schema Documentation dialog Format -> Custom -> Options.
But in this case the output is actually going to be a Docbook XML so make sure the Output file has the .xml file extension(Default for Docbook is ${cfn}.xml).
Afterwards you have to open the Docbook XML and execute a Docbook to PDF transformation scenario(Document -> Transformation -> Apply Transformation Scenario).


Replace built-in stylesheets
There is another trick that you can do to replace the Oxygen built-in stylesheets with the customized ones so that you won't have to always choose the custom stylesheet or transform from Docbook to PDF.

Create a jar or zip file with the directory structure: builtin\documentation\schema_documentation and inside schema_documentation place the customized stylesheets(make sure they have their original names: xsdDocHtml.xsl and xsdDocDocbook.xsl). Inside oxygen-installation-folder/bin create a folder named endorsed and inside it place the jar/zip and restart Oxygen.

After this you will be able to use the Schema Documentation dialog as usual with the HTML or PDF format.

Let me know if you need further help or information.

PS:
If you find the modifications difficult to do contact us at support@oxygenxml.com and we will provide the modified stylesheets(or the jar itself).

Regards,
Adrian