0 Replies Latest reply on Feb 7, 2013 8:06 AM by borges

    Schema and options reference

    borges Novice


      Since yesterday, the user-manual configuration reference is generated from hornetq-configuration.xsd. So when a new option is created all you have to do is add and document it in the schema. Some notes:

      • the XSLT is at docs/user-manual/src/main/resources/schemaToTable.xsl
      • docs/user-manual/pom.xml is configured to run the XSLT when compiling the manual.
      • do `cd docs/user-manual && mvn compile`, and check the actual file at target/generated-resources/xml/xslt/hornetq-configuration.xml
      • there are loads of undocumented options (hey, before I did this they were undocumented AND unlisted)
      • for the time being hornetq-jms.xsd is not being processed by an XSLT


      A properly documented option in hornetq-configuration.xsd now looks like this:


         <xsd:element name="refresh-timeout" type="xsd:int" default="5000" maxOccurs="1" minOccurs="0">        
             <xsd:annotation hq:linkend="configuration.discovery-group.refresh-timeout"                          
                             hq:default="(in milliseconds)">                                                     
                       Period the discovery group waits after receiving the last broadcast from a
                       particular server before removing that servers connector pair entry from its list.

      Other than being a correct XML Schema element definition, there are 4 things to it:

      • REQUIRED the element's default is defined in the Schema default="5000". We will use this value to document the default in the manual.
      • REQUIRED, a documentation element inside an annotation element, with a description of the option:

      <xsd:annotation><xsd:documentation>DESCRIPTION TEXT</xsd:documentation></xsd:annotation>

      • REQUIRED, a <xsd:annotation hq:linkend="link.at.the.manual"/> attribute. Its value is used to link the option to an DocBook "id" anchor in the manual.
      • OPTIONALLY, you can add a <xsd:annotation hq:default="(in milliseconds)"/> this is a help text to add to the default's description in the manual.


      Adding this to the forum, as it can serve as future reference.