Drop annotations from generated Source section

This should cover W3C XML Schema, Relax NG and DTD related problems.
htello
Posts: 1

Drop annotations from generated Source section

Tue Mar 09, 2010 2:16 am

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?
adrian
Posts: 2336

Re: Drop annotations from generated Source section

Wed Mar 10, 2010 6:59 pm

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
Adrian Buza
<oXygen/> XML Editor, Schema Editor and XSLT Editor/Debugger
http://www.oxygenxml.com
adrian
Posts: 2336

Re: Drop annotations from generated Source section

Thu Mar 11, 2010 5:16 pm

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() = '&lt;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() = '&lt;/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
Adrian Buza
<oXygen/> XML Editor, Schema Editor and XSLT Editor/Debugger
http://www.oxygenxml.com

Return to “XML Schemas”

Who is online

Users browsing this forum: No registered users and 1 guest