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">
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:
- 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.