Better handling for literals (multiline) and comments

Previously, comments separated by one or more empty lines were merged
together;  now they are kept separated as intended (also trang's
behavior).

The literals can be multi-line (without strict check for triple quotes).

Signed-off-by: Jan Pokorný <jpokorny@redhat.com>

5 files changed, 880 insertions, 570 deletions

diff --git a/corosync.rnc b/corosync.rnc
index 7e90d2c..8236c83 100644
--- a/corosync.rnc
+++ b/corosync.rnc
@@ -1,62 +1,46 @@
-# Copyright 2013 Red Hat, Inc.
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-#
-# - Redistributions of source code must retain the above copyright notice,
-#   this list of conditions and the following disclaimer.
-# - Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the following disclaimer in the documentation
-#   and/or other materials provided with the distribution.
-# - Neither the name of the Red Hat, Inc. nor the names of its
-#   contributors may be used to endorse or promote products derived from this
-#   software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
-# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
-# THE POSSIBILITY OF SUCH DAMAGE.
-#
-# style guide (RELAX NG Compact only):
-# * '##' comments are wrapped at 50/80 (first line/rest), 2-spaced sentence
-#   separator, AsciiDoc formatting is used within them
-# * sort everything you can to ease the lookup
-
-namespace a     = "http://relaxng.org/ns/compatibility/annotations/1.0"
+# guidelines (relevant to source in RELAX NG Compact form):
+# * '##' comments are wrapped at 50/80 (first line/rest), 2-spaced sentence sep,
+#   AsciiDoc formatting is used within them
+# * sort everything (except for dependencies/nesting) to ease the lookup
+# * for common datatypes, refer to http://www.w3.org/TR/xmlschema11-2
+
+namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0"
 namespace a4doc = "http://people.redhat.com/jpokorny/ns/a4doc"
 
 start = corosync
 
 corosync =
-  element corosync {
+element corosync {
     (logging?
      & nodelist?
+     & resources?
      & quorum?
      & totem
      & uidgid?)
   }
 
-macro.logging_attributes =
+# LOGGING #####################################################################
+
+# only named set of attributes
+common_logging =
     # CFG: corosync.conf, cluster.conf
     ## This specifies whether debug output is
-    ## logged for this particular logger.  Also can contain value trace, what
-    ## is highest level of debug informations.
+    ## logged for this particular logger.  Also can contain value 'trace',
+    ## which is highest level of debug messages.
     [ a:defaultValue = "off" ]
-    attribute debug {"off"|"on"}?,
+    attribute debug {"off"|"on"|"trace"}?,
+
+    # CFG: corosync.conf, cluster.conf
+    ## If the *to_logfile* option is set to
+    ## 'yes', this option specifies the pathname of the log file.
+    attribute logfile {text}?,
 
     # CFG: corosync.conf, cluster.conf
-    ## This specifies the logfile level for this particular subsystem.  Ignored
-    ## if *debug* is 'on'.  Possible  values are: 'alert', 'crit', 'debug'
-    ## (same as *debug =* 'on'), 'emerg', 'err', 'info', 'notice' and 'warning'.
-    [ a:defaultValue = "info" ]
+    ## This specifies the logfile level for this
+    ## particular subsystem.  Ignored if *debug* is 'on'.
+    [ a:defaultValue = "info"
+      a4doc:hint = """
+        Value 'debug' is the same as if *debug* is 'on'.""" ]
     attribute logfile_priority {"alert"
                                |"crit"
                                |"debug"
@@ -69,9 +53,7 @@ macro.logging_attributes =
 
     # CFG: corosync.conf, cluster.conf
     ## This specifies the syslog facility type
-    ## that will be used for any messages sent to syslog.  Options are
-    ## 'daemon', 'local0', 'local1', 'local2', 'local3', 'local4', 'local5',
-    ## 'local6' and 'local7'.
+    ## that will be used for any messages sent to syslog.
     [ a:defaultValue = "daemon" ]
     attribute syslog_facility {"daemon"
                               |"local0"
@@ -86,10 +68,10 @@ macro.logging_attributes =
 
     # CFG: corosync.conf, cluster.conf
     ## This specifies the syslog level for this
-    ## particular subsystem.  Ignored if *debug* is 'on'.  Possible  values are:
-    ## 'alert', 'crit', 'debug' (same as *debug =* 'on'), 'emerg', 'err',
-    ## 'info', 'notice' and 'warning'.
-    [ a:defaultValue = "info" ]
+    ## particular subsystem.  Ignored if *debug* is 'on'.
+    [ a:defaultValue = "info"
+      a4doc:hint = """
+        Value 'debug' is the same as if *debug* is 'on'.""" ]
     attribute syslog_priority {"alert"
                               |"crit"
                               |"debug"
@@ -100,14 +82,17 @@ macro.logging_attributes =
                               |"warning"
     }?,
 
+    # XXX: undocumented
+    attribute tags {text}?,
+
     # CFG: corosync.conf, cluster.conf
-    ## This specifies the destination
-    ## of logging output.
+    ## This specifies whether to use
+    ## the respective destination of logging output.
     ##
     ## Please note, if you are using *to_logfile* and want to rotate the file,
     ## use `logrotate(8)` with the option `copytruncate`, e.g.
     ##
-    ## ---- 
+    ## ----
     ## /var/log/corosync.log {
     ##     missingok
     ##     compress
@@ -121,26 +106,22 @@ macro.logging_attributes =
     attribute to_logfile {"no"|"yes"}?,
 
     # CFG: corosync.conf
-    ## This specifies the destination
-    ## of logging output.
+    ## This specifies whether to use
+    ## the respective destination of logging output.
     [ a:defaultValue = "yes" ]
     attribute to_stderr {"no"|"yes"}?,
-    
+
     # CFG: corosync.conf, cluster.conf
-    ## This specifies the destination
-    ## of logging output.
+    ## This specifies whether to use
+    ## the respective destination of logging output.
     [ a:defaultValue = "yes" ]
     attribute to_syslog {"no"|"yes"}?
 
 logging =
+  ## In this configuration section, one can
+  ## adjust logging.
   element logging {
     # CFG: corosync.conf
-    ## This specifies that a timestamp is placed
-    ## on all log messages.
-    [ a:defaultValue = "off" ]
-    attribute timestamp {"off"|"on"}?,
-
-    # CFG: corosync.conf
     ## This specifies that file and line should
     ## be printed.
     [ a:defaultValue = "off" ]
@@ -152,25 +133,34 @@ logging =
     [ a:defaultValue = "off" ]
     attribute function_name {"off"|"on"}?,
 
-    macro.logging_attributes,
+    # CFG: corosync.conf
+    ## This specifies that a timestamp is placed
+    ## on all log messages.
+    [ a:defaultValue = "off" ]
+    attribute timestamp {"off"|"on"}?,
+
+    common_logging,
     logger_subsys*
   }
 
 logger_subsys =
   element logger_subsys {
-    macro.logging_attributes,
-
     # CFG: corosync.conf, cluster.conf
     ## This specifies the subsystem identity
     ## (name) for which logging is specified.  This is the name used by
-    ## a service in the `log_init` call.  E.g., 'CPG'.
-    ## This option is required.
-    attribute subsys {text}
+    ## a service in the `log_init` call, e.g., 'CPG'.
+    attribute subsys {text},
+
+    common_logging
   }
 
+# NODELIST ####################################################################
+
 nodelist =
+  ## In this configuration section, one can
+  ## adjust nodes in the cluster.
   element nodelist {
-    node?
+    node*
   }
 
 node =
@@ -178,13 +168,17 @@ node =
     # XXX: implied check
     # CFG: corosync.conf, cluster.conf
     ## This configuration option is optional when
-    ## using IPv4 and required when using IPv6.  This is a 32 bit value
+    ## using IPv4 and required when using IPv6.  This is a 32bit value
     ## specifying the node identifier delivered to the cluster membership
-    ## service.  If this is not specified with IPv4, the node id will be
-    ## determined from the 32 bit IP address the system to which the system
+    ## service.  If this is not specified with IPv4, *nodeid* will be
+    ## determined from the 32bit IP address the system to which the system
     ## is bound with ring identifier of 0.  The node identifier value of zero
     ## is reserved and should not be used.
-    attribute noid {xsd:unsignedInt}?,
+    attribute nodeid {xsd:unsignedInt}?,
+
+    # CFG: corosync.conf, cluster.conf
+    # NOTE: not a direct mapping in cluster.conf (clusternode/votes)
+    attribute quorum_votes {xsd:unsignedInt}?,
 
     # CFG: corosync.conf, cluster.conf
     ## This specifies IP address of one of the nodes for particular ring
@@ -202,34 +196,39 @@ node =
     # NOTE: Augeas lens for corosync.conf counts on X = 0..9 only
   }
 
+# QUORUM ######################################################################
+
 quorum =
+  ## In this configuration section, one can
+  ## adjust quorum.
   element quorum {
     # CFG: corosync.conf
     ## This enables Downscale feature
-    ## (see `votequorum(5)`).
+    ## (see **votequorum**(5)).
     [ a:defaultValue = "0" ]
     attribute allow_downscale {"0"|"1"}?,
 
     # CFG: corosync.conf
     ## This enables Auto Tie Breaker feature
-    ## (see `votequorum(5)`).
+    ## (see **votequorum**(5)).
     [ a:defaultValue = "0" ]
     attribute auto_tie_breaker {"0"|"1"}?,
 
     # CFG: corosync.conf, cluster.conf
-    ## This specifies the number of expected votes, overriding the number
-    ## implied by the number of *node* items within *nodes*.
+    ## This specifies the number of expected
+    ## votes, overriding the number implied by the number of *node* items
+    ## within *nodes*.
     attribute expected_votes {xsd:unsignedInt}?,
 
     # CFG: corosync.conf
     ## This enables Last Man Standing feature
-    ## (see `votequorum(5)`).
+    ## (see **votequorum**(5)).
     [ a:defaultValue = "0" ]
     attribute last_man_standing {"0"|"1"}?,
 
     # CFG: corosync.conf
     ## This specifies the tunable for Last Man
-    ## Standing feature (see `votequorum(5)`).
+    ## Standing feature (see **votequorum**(5)).
     [ a:defaultValue = "0" ]
     attribute last_man_standing_window {xsd:nonNegativeInteger}?,
 
@@ -240,32 +239,72 @@ quorum =
 
     # CFG: corosync.conf, cluster.conf
     ## This enables two node cluster operations
-    ## (see `votequorum(5)`).
+    ## (see **votequorum**(5)).
     [ a:defaultValue = "0" ]
     attribute two_node {"0"|"1"}?,
 
     # CFG: corosync.conf
+    attribute votes {xsd:unsignedInt}?,
+
+    # CFG: corosync.conf
     ## This enables Wait For All feature
-    ## (see `votequorum(5)`).
+    ## (see **votequorum**(5)).
     [ a:defaultValue = "0" ]
     attribute wait_for_all {"0"|"1"}?
   }
 
+# RESOURCES ###################################################################
+
+# only named set of attributes
+common_resource =
+  # XXX: undocumented
+  attribute max {xsd:decimal}?,
+
+  # XXX: undocumented
+  attribute poll_period {xsd:unsignedInt}?,
+
+  # XXX: undocumented
+  attribute recovery {"reboot"|"shutdown"|"watchdog"|"none"}?
+
+load_15min =
+  element load_15min {
+    common_resource?
+  }
+
+memory_used =
+  element memory_used {
+    common_resource?
+  }
+
+system =
+  element system {
+    (load_15min?
+     &memory_used?)
+  }
+
+resources =
+  element resources {
+    system?
+  }
+
+# TOTEM #######################################################################
+
 totem =
+  ## In this configuration section, one can
+  ## adjust totem protocol.
   element totem {
     # CFG: corosync.conf
-    ## This configuration option is optional and
-    ## is only relevant when no *nodeid* is specified.  Some corosync clients
-    ## require a signed 32 bit nodeid that is greater than zero however by
-    ## default corosync uses all 32 bits of the IPv4 address space when
-    ## generating a nodeid.  Set this option to 'yes' to force the high bit
-    ## to be zero and therefor ensure the nodeid is a positive signed 32 bit
-    ## integer.
+    ## This configuration option is only relevant
+    ## when no *nodeid* option within *nodelist* section is specified.  Some
+    ## corosync clients require a signed 32bit nodeid that is greater than
+    ## zero however, by default, corosync uses all 32 bits of the IPv4 address
+    ## space when generating a nodeid.
+    ## Set this option to 'yes' to force the high bit to be zero and therefor
+    ## ensure the nodeid is a positive signed 32bit integer.
     [ a:defaultValue = "no"
-      a4doc:discretion-hint =
-        "The clusters behavior is undefined if this option is enabled"
-        ~ " on only a subset of the cluster (for example during a rolling"
-        ~ " upgrade)." ]
+      a4doc:discretion-hint = """
+        The clusters behavior is undefined if this option is enabled on only
+        a subset of the cluster (for example during a rolling upgrade).""" ]
     attribute clear_node_high_bit {"no"|"yes"}?,
 
     # CFG: corosync.conf, cluster.conf
@@ -279,14 +318,14 @@ totem =
     ## This timeout specifies in milliseconds how
     ## long to wait for consensus to be achieved before starting a new round
     ## of membership configuration.  The minimum value for *consensus* must be
-    ## 1.2 * *token*.
+    ## 1.2 x *token*.
     ##
-    ## This value will be automatically calculated at 1.2 * *token* if
+    ## This value will be automatically calculated at 1.2 x *token* if
     ## the user doesn't specify a *consensus* value.
     ##
-    ## For two node clusters, a *consensus* larger then the *join* timeout but
-    ## less then *token* is safe.  For three node or larger clusters,
-    ## *consensus* should be larger then token.  There is an increasing risk
+    ## For two node clusters, a *consensus* larger than the *join* timeout but
+    ## less than *token* is safe.  For three-node or larger clusters,
+    ## *consensus* should be larger than *token*.  There is an increasing risk
     ## of odd membership changes, which still guarantee virtual synchrony,
     ## as node count grows if *consensus* is less than *token*.
     [ a:defaultValue = "1200" ]
@@ -295,22 +334,20 @@ totem =
     # XXX: missing nss?
     # CFG: corosync.conf
     ## This specifies which cipher should be used
-    ## to encrypt all messages.  Valid values are 'none' (no encryption),
-    ## 'aes256', 'aes192', 'aes128' and '3des'.
+    ## to encrypt all messages.
     [ a:defaultValue = "aes256" ]
     attribute crypto_cipher {"3des"|"aes128"|"aes192"|"aes256"|"none"}?,
 
-    # CFG: undocumented
+    # XXX: undocumented
     attribute crypto_compat {"2.0"|"2.2"}?,
 
     # CFG: corosync.conf
     ## This specifies which HMAC authentication
-    ## should be used to authenticate all messages.  Valid values are 'none'
-    ## (no authentication), 'md5', 'sha1', 'sha256', 'sha384' and 'sha512'.
+    ## should be used to authenticate all messages.
     [ a:defaultValue = "sha1" ]
     attribute crypto_hash {"none"|"md5"|"sha1"|"sha256"|"sha384"|"sha512"}?,
 
-    # CFG: undocumented
+    # XXX: undocumented
     attribute crypto_type {"3des"|"aes128"|"aes192"|"aes256"|"nss"}?,
 
     # CFG: corosync.conf
@@ -338,7 +375,7 @@ totem =
     ##
     ## This constant specifies the number of heartbeat failures the system
     ## should tolerate before declaring heartbeat failure, e.g., 3.
-    ## Also if this value is not set or is 0 then the heartbeat mechanism is
+    ## Also if this value is not set or is 0, the heartbeat mechanism is
     ## not engaged in the system and token rotation is the method of failure
     ## detection.  Zero disables the mechanism.
     [ a:defaultValue = "0" ]
@@ -349,9 +386,9 @@ totem =
     ## how long the token should be held by the representative when
     ## the protocol is under low utilization.
     [ a:defaultValue = "180"
-      a4doc:danger-hint =
-        "It is not recommended to override this value without guidance"
-        ~ " from the corosync community." ]
+      a4doc:danger-hint = """
+        It is not recommended to override this value without guidance from
+        the corosync community.""" ]
     attribute hold {xsd:unsignedInt}?,
 
     # CFG: corosync.conf, cluster.conf
@@ -396,30 +433,31 @@ totem =
 
     # CFG: corosync.conf, cluster.conf
     ## This specifies the network maximum transmit
-    ## unit.  To set this value beyond 1500, the regular frame MTU, requires
+    ## unit.  Setting this value beyond '1500', the regular frame MTU, requires
     ## ethernet devices that support large, or also called jumbo, frames.
     ## If any device in the network doesn't support large frames, the protocol
-    ## will not operate properly.  The hosts must also have their mtu size set
+    ## will not operate properly.  The hosts must also have their MTU size set
     ## from 1500 to whatever frame size is specified here.
-    ##
-    ## Please note while some NICs or switches
-    ## claim large frame support, they support 9000 MTU as the maximum frame
-    ## size including the IP header.  Setting the *netmtu* and host MTUs to 9000
-    ## will cause totem to use the full 9000 bytes of the frame.  Then Linux
-    ## will add a 18 byte header moving the full frame size to 9018.
-    ## As a result some hardware will not operate properly with this size
-    ## of data.  A *netmtu* of 8982 seems to work for the few large frame devices
-    ## that have been tested.  Some manufacturers claim large frame support
-    ## when in fact they support frame sizes of 4500 bytes.
-    ##
-    ## When sending multicast traffic, if the network frequently reconfigures,
-    ## chances are that some device in the network doesn't support large frames.
-    ##
-    ## Choose hardware carefully if intending to use large frame support.
-    [ a:defaultValue = "1500" ]
+    [ a:defaultValue = "1500"
+      a4doc:discretion-hint = """
+        While some NICs or switches claim large frame support, they support
+        9000 MTU as the maximum frame size including the IP header.  Setting
+        the *netmtu* and host MTUs to '9000' will cause totem to use the full
+        9000 bytes of the frame.  Then Linux will add an 18byte header moving
+        the full frame size to 9018.  As a result some hardware will not
+        operate properly with this size of data.  A *netmtu* of '8982' seems
+        to work for the few large frame devices that have been tested.
+        Some manufacturers claim large frame support when in fact they
+        support frame sizes of 4500 bytes.
+
+        When sending multicast traffic, if the network frequently
+        reconfigures, chances are that some device in the network doesn't
+        support large frames.
+        
+        Choose hardware carefully if intending to use large frame support.""" ]
     attribute netmtu {xsd:unsignedInt}?,
 
-    # CFG: undocumented
+    # XXX: undocumented
     attribute nodeid {xsd:unsignedInt}?,
 
     # CFG: corosync.conf
@@ -428,31 +466,30 @@ totem =
     [ a:defaultValue = "1000" ]
     attribute rrp_autorecovery_check_timeout {xsd:unsignedInt}?,
 
-    # XXX: implied check: active,passive -> count(interface) <= 2
+    # XXX: implied check: count(interface) <= 4 (2 active + 2 passive)
     # CFG: corosync.conf, cluster.conf
-    ## This specifies the mode of redundant ring,
-    ## which may be 'none', 'active', or 'passive'.  Active replication offers
-    ## none`, active, or passive.  Active replication offers
-    ## slightly lower latency from transmit to delivery in faulty network
-    ## environments but with less performance.  Passive replication may nearly
-    ## double the speed of the totem protocol if the protocol doesn't become
-    ## CPU bound.  The final option is none, in which case only one network
+    ## This specifies the mode of redundant ring.
+    ## Active replication ('active') offers slightly lower latency from
+    ## transmit to delivery in faulty network environments but with less
+    ## performance.  Passive replication ('passive') may nearly double
+    ## the speed of the totem protocol if it doesn't become CPU bound.
+    ## The remaining option is 'none', in which case only one network
     ## interface will be used to operate the totem protocol.
     ##
-    ## If only one *interface* directive is specified, 'none' is automatically
-    ## chosen.  If multiple *interface* directives are specified, only 'active'
+    ## If only one *interface* section is specified, 'none' is automatically
+    ## chosen.  If multiple *interface* sections are specified, only 'active'
     ## or 'passive' may be chosen.
     ##
-    ## The maximum number of *interface* directives that is allowed for either
+    ## The maximum number of *interface* sections that is allowed for either
     ## mode ('active' or 'passive') is 2.
     attribute rrp_mode {"active"|"none"|"passive"}?,
 
     # CFG: corosync.conf
     ## This specifies the number of times
     ## a problem is detected with multicast before setting the link faulty for
-    ## passive RRP mode.  This variable is unused in active RRP mode.
+    ## 'passive' *rrp_mode*.  This variable is unused in 'active' *rrp_mode*.
     ##
-    ## The default is 10 times *rrp_problem_count_threshold*.
+    ## The default is 10 x *rrp_problem_count_threshold*.
     attribute rrp_problem_count_mcast_threshold {xsd:unsignedInt}?,
 
     # XXX: implied check
@@ -465,8 +502,8 @@ totem =
     ##
     ## A problem is detected whenever all tokens from the proceeding
     ## processor have not been received within the *rrp_token_expired_timeout*.
-    ## The *rrp_problem_count_threshold* * *rrp_token_expired_timeout* should be
-    ## at least 50 milliseconds less then the *token* timeout, or a complete
+    ## The *rrp_problem_count_threshold* x *rrp_token_expired_timeout* should be
+    ## at least 50 milliseconds less than the *token* timeout, or a complete
     ## reconfiguration may occur.
     [ a:defaultValue = "10" ]
     attribute rrp_problem_count_threshold {xsd:unsignedInt}?,
@@ -486,39 +523,40 @@ totem =
     ## This value will automatically be calculated from the *token* timeout
     ## and *problem_count_threshold* but may be overridden.
     [ a:defaultValue = "47"
-      a4doc:danger-hint =
-        "It is not recommended to override this value without guidance"
-        ~ " from the corosync community." ]
+      a4doc:danger-hint = """
+        It is not recommended to override this value without guidance from
+        the corosync community.""" ]
     attribute rrp_token_expired_timeout {xsd:unsignedInt}?,
 
     # XXX: implied check/migration to current items
     # CFG: corosync.conf, cluster.conf
-    ## This specifies that HMAC/SHA1 authentication should be used
-    ## to authenticate all messages.  It further specifies that all data
-    ## should be encrypted with the nss library and aes256 encryption
-    ## algorithm to protect data from eavesdropping.
+    ## This specifies that HMAC/SHA1
+    ## authentication should be used to authenticate all messages.  It further
+    ## specifies that all data should be encrypted with the `nss` library and
+    ## `aes256` encryption algorithm to protect data from eavesdropping.
     ##
-    ## Enabling this option adds a encryption header to every message sent
+    ## Enabling this option adds an encryption header to every message sent
     ## by totem which reduces total throughput.  Also encryption and
     ## authentication consume extra CPU cycles in corosync.
     [ a:defaultValue = "on"
-      a4doc:deprecation-hint =
-      "It's recomended to use combination of *crypto_cipher* and *crypto_hash*."
-    ]
+      a4doc:deprecation-hint = """
+        It's recomended to use combination of *crypto_cipher* and *crypto_hash*
+        instead.""" ]
     attribute secauth {"off"|"on"}?,
 
     # CFG: corosync.conf
     ## This timeout specifies in milliseconds
     ## an upper range between 0 and *send_join* to wait before sending a join
-    ## message.  For eprecationtions with less then 32 nodes, this parameter
+    ## message.  For configurations with less than 32 nodes, this parameter
     ## is not necessary.  For larger rings, this parameter is necessary
     ## to ensure the NIC is not overflowed with join messages on formation of
     ## a new ring.  A reasonable value for large rings (128 nodes) would be
-    ## 80msec.  Other timer values must also change if this value is changed.
+    ## __80__msec.  Other timer values must also change if this value
+    ## is changed.
     [ a:defaultValue = "0"
-      a4doc:danger-hint =
-        "Seek advice from the corosync mailing list if trying to run"
-        ~ " larger configurations." ]
+      a4doc:danger-hint = """
+        Seek advice from the corosync mailing list if trying to run larger
+        configurations.""" ]
     attribute send_join {xsd:unsignedInt}?,
 
     # CFG: corosync.conf, cluster.conf
@@ -528,46 +566,47 @@ totem =
     [ a:defaultValue = "30" ]
     attribute seqno_unchanged_const {xsd:unsignedInt}?,
 
-    # CFG: undocumented
+    # XXX: undocumented
     attribute threads {xsd:unsignedInt}?,
 
     # CFG: corosync.conf, cluster.conf
-    ## This timeout specifies in milliseconds
-    ## until a token loss is declared after not receiving a token.  This is
-    ## the time spent detecting a failure of a processor in the current
-    ## configuration.  Reforming a new configuration takes about 50
-    ## milliseconds in addition to this timeout.
+    ## This timeout specifies a period in
+    ## milliseconds until a token loss is declared after not receiving
+    ## a token.  This is the time spent detecting a failure of a processor
+    ## in the current configuration.  Reforming a new configuration takes
+    ## about 50 milliseconds in addition to this timeout.
     [ a:defaultValue = "1000" ]
     attribute token {xsd:unsignedInt}?,
 
     # CFG: corosync.conf
-    ## This timeout specifies in milliseconds
-    ## after how long before receiving a token the token is retransmitted.
-    ## This will be automatically calculated if token is modified.
+    ## This timeout specifies a period in
+    ## milliseconds without receiving a token after which the token is
+    ## retransmitted.  This will be automatically calculated if *token* is
+    ## modified.
     [ a:defaultValue = "238"
-      a4doc:danger-hint =
-        "It is not recommended to override this value without guidance"
-        ~ " from the corosync community." ]
+      a4doc:danger-hint = """
+        It is not recommended to override this value without guidance from
+        the corosync community.""" ]
     attribute token_retransmit {xsd:unsignedInt}?,
 
     # CFG: corosync.conf, cluster.conf
     ## This value identifies how many token
     ## retransmits should be attempted before forming a new configuration.
     ## If this value is set, retransmit and hold will be automatically
-    ## calculated from *retransmits_before_loss* and token.
+    ## calculated from *retransmits_before_loss* and *token*.
     [ a:defaultValue = "4" ]
     attribute token_retransmits_before_loss_const {xsd:unsignedInt}?,
 
     # CFG: corosync.conf
-    [ a:defaultValue = "udp" ]
-    attribute transport {"iba"|"udp"|"udpu"}?,
     ## This option controls the transport
     ## mechanism used.  If the interface to which corosync is binding is
     ## an RDMA interface such as RoCEE or Infiniband, the 'iba' parameter
     ## may be specified.  To avoid the use of multicast entirely, a unicast
     ## transport parameter 'udpu' can be specified.  This requires specifying
-    ## the list of members in *nodelist* directive, that could potentially make
-    ## up the membership before deployment.
+    ## the list of members that could potentially make up the membership
+    ## in *nodelist* section before deployment.
+    [ a:defaultValue = "udp" ]
+    attribute transport {"iba"|"udp"|"udpu"}?,
 
     # CFG: corosync.conf
     ## This specifies the version of
@@ -578,8 +617,8 @@ totem =
     # CFG: corosync.conf
     ## This option controls the virtual
     ## synchrony filter type used to identify a primary component.
-    ## The preferred choice is YKD dynamic linear voting, however, for
-    ## clusters larger then 32 nodes YKD consumes alot of memory.  For large
+    ## The preferred choice is YKD dynamic linear voting ('ykd'), however, for
+    ## clusters larger than 32 nodes YKD consumes a lot of memory.  For large
     ## scale clusters that are created by changing the MAX_PROCESSORS_COUNT
     ## #define in the C code totem.h file, the virtual synchrony filter 'none'
     ## is recommended but then AMF and DLCK services (which are currently
@@ -590,11 +629,11 @@ totem =
     # CFG: corosync.conf, cluster.conf
     ## This constant specifies the maximum number
     ## of messages that may be sent on one token rotation.  If all processors
-    ## perform equally well, this value could be large (300), which would
+    ## perform equally well, this value could be large ('300'), which would
     ## introduce higher latency from origination to delivery for very large
-    ## rings.  To reduce latency in large rings (16+), the defaults are a safe
+    ## rings.  To reduce latency in large rings (16+), the default is a safe
     ## compromise.  If 1 or more slow processor(s) are present among fast
-    ## processors, *window_size* should be no larger then 256000 / *netmtu*
+    ## processors, *window_size* should be no larger than 256000 / *netmtu*
     ## to avoid overflow of the kernel receive buffers.  The user is notified
     ## of this by the display of a retransmit list in the notification logs.
     ## There is no loss of data, but performance is reduced when these errors
@@ -624,14 +663,14 @@ interface =
     ## automatic selection of the network interface within a specific subnet
     ## as with IPv4.
     ##
-    ## If IPv6 networking is used, the *nodeid* field in *nodelist* must be
-    ## specified.
+    ## If IPv6 networking is used, *nodeid* options within *nodelist* section
+    ## must be specified.
     attribute bindnetaddr {text}?,
 
     # CFG: corosync.conf
-    ## This is optional and can be set to 'yes'.  If it is set to 'yes',
-    ## the broadcast address will be used for communication.  If this option
-    ## is set, *mcastaddr* should not be set.
+    ## If this is set to 'yes', the broadcast
+    ## address will be used for communication.  If this option is set,
+    ## *mcastaddr* should not be set.
     [ a:defaultValue = "no" ]
     attribute broadcast {"no"|"yes"}?,
 
@@ -642,11 +681,12 @@ interface =
     ## to use.  Avoid `224.x.x.x` because this is a "config" multicast address.
     ##
     ## This may also be an IPv6 multicast address, in which case IPv6 networking
-    ## will be used.  If IPv6 networking is used, the *nodeid* field in
-    ## *nodelist* must be specified.
+    ## will be used.  If IPv6 networking is used, *nodeid* options within
+    ## *nodelist* section must be specified.
     ##
-    ## It's not needed to use this option if *cluster_name* option is used.
-    ## If both options are used, *mcastaddr* has higher priority.
+    ## It's not needed to use this option if *cluster_name* option in
+    ## *totem* section is used.  If both options are used, *mcastaddr* has
+    ## higher priority.
     attribute mcastaddr {text}?,
 
     # CFG: corosync.conf, cluster.conf
@@ -655,7 +695,7 @@ interface =
     ## the corosync services configured for different UDP ports.  Please note
     ## corosync uses two UDP ports *mcastport* (for mcast receives) and
     ## *mcastport* - 1 (for mcast sends).  If you have multiple  clusters
-    ## on the same network using the same *mcastaddr* please configure
+    ## on the same network using the same *mcastaddr*, please configure
     ## the **mcastport**s with a gap.
     attribute mcastport {xsd:unsignedShort}?,
 
@@ -664,21 +704,33 @@ interface =
     ## the interface.  When using the redundant ring protocol, each interface
     ## should specify separate ring numbers to uniquely identify to
     ## the membership protocol which interface to use for which redundant ring.
-    ## The *ringnumber* must start at 0.
+    ## The *ringnumber* must start at '0'.
     attribute ringnumber {xsd:unsignedByte}?,
 
+    # XXX: implied check
     # CFG: corosync.conf, cluster.conf
     ## This specifies the Time To Live (TTL).
-    ## If you run your cluster on a routed network then the default of '1' will
+    ## If you run your cluster on a routed network, the default of '1' will
     ## be too small.  This option provides a way to increase this up to '255'.
-    ## The valid range is '0..255'.  Note that this is only valid on multicast
-    ## transport types.
-    [ a:defaultValue = "1" ]
+    ## The valid range is '0..255'.
+    [ a:defaultValue = "1"
+      a4doc:dicretion-hint = """
+        This is only valid on multicast transport types.""" ]
     attribute ttl {xsd:unsignedByte}?
   }
 
-#uidgid =
-#  element uidgid {
-#    attribute uid {text}?,
-#    attribute gid {text}?
-#  }
+# UIDGID ######################################################################
+
+uidgid =
+  element uidgid {
+    # CFG: corosync.conf, cluster.conf
+    # XXX: undocumented
+    attribute uid {text}?,
+
+    # CFG: corosync.conf, cluster.conf
+    # XXX: undocumented
+    attribute gid {text}?
+  }
+
+
+# vim: set et ts=2 sw=2:
diff --git a/corosync.rng.expected b/corosync.rng.expected
index 3e4ca2f..464af86 100644
--- a/corosync.rng.expected
+++ b/corosync.rng.expected
@@ -4,37 +4,11 @@
     xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"
     xmlns:a4doc="http://people.redhat.com/jpokorny/ns/a4doc">
   <!--
-    Copyright 2013 Red Hat, Inc.
-    All rights reserved.
-    
-    Redistribution and use in source and binary forms, with or without
-    modification, are permitted provided that the following conditions are met:
-    
-    - Redistributions of source code must retain the above copyright notice,
-      this list of conditions and the following disclaimer.
-    - Redistributions in binary form must reproduce the above copyright notice,
-      this list of conditions and the following disclaimer in the documentation
-      and/or other materials provided with the distribution.
-    - Neither the name of the Red Hat, Inc. nor the names of its
-      contributors may be used to endorse or promote products derived from this
-      software without specific prior written permission.
-    
-    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-    ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
-    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
-    THE POSSIBILITY OF SUCH DAMAGE.
-    
-    style guide (RELAX NG Compact only):
-    * '##' comments are wrapped at 50/80 (first line/rest), 2-spaced sentence
-      separator, AsciiDoc formatting is used within them
-    * sort everything you can to ease the lookup
+    guidelines (relevant to source in RELAX NG Compact form):
+    * '##' comments are wrapped at 50/80 (first line/rest), 2-spaced sentence sep,
+      AsciiDoc formatting is used within them
+    * sort everything (except for dependencies/nesting) to ease the lookup
+    * for common datatypes, refer to http://www.w3.org/TR/xmlschema11-2
     -->
   <start>
     <ref name="corosync"/>
@@ -49,6 +23,9 @@
           <ref name="nodelist"/>
         </optional>
         <optional>
+          <ref name="resources"/>
+        </optional>
+        <optional>
           <ref name="quorum"/>
         </optional>
         <ref name="totem"/>
@@ -58,24 +35,36 @@
       </interleave>
     </element>
   </define>
-  <define name="macro.logging_attributes">
+  <!-- LOGGING ##################################################################### -->
+  <!-- only named set of attributes -->
+  <define name="common_logging">
     <optional>
       <attribute name="debug" a:defaultValue="off">
         <a:documentation>This specifies whether debug output is
-logged for this particular logger.  Also can contain value trace, what
-is highest level of debug informations.</a:documentation>
+logged for this particular logger.  Also can contain value 'trace',
+which is highest level of debug messages.</a:documentation>
         <!-- CFG: corosync.conf, cluster.conf -->
         <choice>
           <value>off</value>
           <value>on</value>
+          <value>trace</value>
         </choice>
       </attribute>
     </optional>
     <optional>
-      <attribute name="logfile_priority" a:defaultValue="info">
-        <a:documentation>This specifies the logfile level for this particular subsystem.  Ignored
-if *debug* is 'on'.  Possible  values are: 'alert', 'crit', 'debug'
-(same as *debug =* 'on'), 'emerg', 'err', 'info', 'notice' and 'warning'.</a:documentation>
+      <attribute name="logfile">
+        <a:documentation>If the *to_logfile* option is set to
+'yes', this option specifies the pathname of the log file.</a:documentation>
+        <!-- CFG: corosync.conf, cluster.conf -->
+        <text/>
+      </attribute>
+    </optional>
+    <optional>
+      <attribute name="logfile_priority" a:defaultValue="info"
+          a4doc:hint="
+        Value 'debug' is the same as if *debug* is 'on'.">
+        <a:documentation>This specifies the logfile level for this
+particular subsystem.  Ignored if *debug* is 'on'.</a:documentation>
         <!-- CFG: corosync.conf, cluster.conf -->
         <choice>
           <value>alert</value>
@@ -92,9 +81,7 @@ if *debug* is 'on'.  Possible  values are: 'alert', 'crit', 'debug'
     <optional>
       <attribute name="syslog_facility" a:defaultValue="daemon">
         <a:documentation>This specifies the syslog facility type
-that will be used for any messages sent to syslog.  Options are
-'daemon', 'local0', 'local1', 'local2', 'local3', 'local4', 'local5',
-'local6' and 'local7'.</a:documentation>
+that will be used for any messages sent to syslog.</a:documentation>
         <!-- CFG: corosync.conf, cluster.conf -->
         <choice>
           <value>daemon</value>
@@ -110,11 +97,11 @@ that will be used for any messages sent to syslog.  Options are
       </attribute>
     </optional>
     <optional>
-      <attribute name="syslog_priority" a:defaultValue="info">
+      <attribute name="syslog_priority" a:defaultValue="info"
+          a4doc:hint="
+        Value 'debug' is the same as if *debug* is 'on'.">
         <a:documentation>This specifies the syslog level for this
-particular subsystem.  Ignored if *debug* is 'on'.  Possible  values are:
-'alert', 'crit', 'debug' (same as *debug =* 'on'), 'emerg', 'err',
-'info', 'notice' and 'warning'.</a:documentation>
+particular subsystem.  Ignored if *debug* is 'on'.</a:documentation>
         <!-- CFG: corosync.conf, cluster.conf -->
         <choice>
           <value>alert</value>
@@ -129,9 +116,15 @@ particular subsystem.  Ignored if *debug* is 'on'.  Possible  values are:
       </attribute>
     </optional>
     <optional>
+      <attribute name="tags">
+        <!-- XXX: undocumented -->
+        <text/>
+      </attribute>
+    </optional>
+    <optional>
       <attribute name="to_logfile" a:defaultValue="no">
-        <a:documentation>This specifies the destination
-of logging output.
+        <a:documentation>This specifies whether to use
+the respective destination of logging output.
 
 Please note, if you are using *to_logfile* and want to rotate the file,
 use `logrotate(8)` with the option `copytruncate`, e.g.
@@ -155,8 +148,8 @@ use `logrotate(8)` with the option `copytruncate`, e.g.
     </optional>
     <optional>
       <attribute name="to_stderr" a:defaultValue="yes">
-        <a:documentation>This specifies the destination
-of logging output.</a:documentation>
+        <a:documentation>This specifies whether to use
+the respective destination of logging output.</a:documentation>
         <!-- CFG: corosync.conf -->
         <choice>
           <value>no</value>
@@ -166,8 +159,8 @@ of logging output.</a:documentation>
     </optional>
     <optional>
       <attribute name="to_syslog" a:defaultValue="yes">
-        <a:documentation>This specifies the destination
-of logging output.</a:documentation>
+        <a:documentation>This specifies whether to use
+the respective destination of logging output.</a:documentation>
         <!-- CFG: corosync.conf, cluster.conf -->
         <choice>
           <value>no</value>
@@ -178,11 +171,13 @@ of logging output.</a:documentation>
   </define>
   <define name="logging">
     <element name="logging">
+      <a:documentation>In this configuration section, one can
+adjust logging.</a:documentation>
       <group>
         <optional>
-          <attribute name="timestamp" a:defaultValue="off">
-            <a:documentation>This specifies that a timestamp is placed
-on all log messages.</a:documentation>
+          <attribute name="fileline" a:defaultValue="off">
+            <a:documentation>This specifies that file and line should
+be printed.</a:documentation>
             <!-- CFG: corosync.conf -->
             <choice>
               <value>off</value>
@@ -191,9 +186,9 @@ on all log messages.</a:documentation>
           </attribute>
         </optional>
         <optional>
-          <attribute name="fileline" a:defaultValue="off">
-            <a:documentation>This specifies that file and line should
-be printed.</a:documentation>
+          <attribute name="function_name" a:defaultValue="off">
+            <a:documentation>This specifies that the code function name
+should be printed.</a:documentation>
             <!-- CFG: corosync.conf -->
             <choice>
               <value>off</value>
@@ -202,9 +197,9 @@ be printed.</a:documentation>
           </attribute>
         </optional>
         <optional>
-          <attribute name="function_name" a:defaultValue="off">
-            <a:documentation>This specifies that the code function name
-should be printed.</a:documentation>
+          <attribute name="timestamp" a:defaultValue="off">
+            <a:documentation>This specifies that a timestamp is placed
+on all log messages.</a:documentation>
             <!-- CFG: corosync.conf -->
             <choice>
               <value>off</value>
@@ -212,7 +207,7 @@ should be printed.</a:documentation>
             </choice>
           </attribute>
         </optional>
-        <ref name="macro.logging_attributes"/>
+        <ref name="common_logging"/>
         <zeroOrMore>
           <ref name="logger_subsys"/>
         </zeroOrMore>
@@ -222,35 +217,37 @@ should be printed.</a:documentation>
   <define name="logger_subsys">
     <element name="logger_subsys">
       <group>
-        <ref name="macro.logging_attributes"/>
         <attribute name="subsys">
           <a:documentation>This specifies the subsystem identity
 (name) for which logging is specified.  This is the name used by
-a service in the `log_init` call.  E.g., 'CPG'.
-This option is required.</a:documentation>
+a service in the `log_init` call, e.g., 'CPG'.</a:documentation>
           <!-- CFG: corosync.conf, cluster.conf -->
           <text/>
         </attribute>
+        <ref name="common_logging"/>
       </group>
     </element>
   </define>
+  <!-- NODELIST #################################################################### -->
   <define name="nodelist">
     <element name="nodelist">
-      <optional>
+      <a:documentation>In this configuration section, one can
+adjust nodes in the cluster.</a:documentation>
+      <zeroOrMore>
         <ref name="node"/>
-      </optional>
+      </zeroOrMore>
     </element>
   </define>
   <define name="node">
     <element name="node">
       <group>
         <optional>
-          <attribute name="noid">
+          <attribute name="nodeid">
             <a:documentation>This configuration option is optional when
-using IPv4 and required when using IPv6.  This is a 32 bit value
+using IPv4 and required when using IPv6.  This is a 32bit value
 specifying the node identifier delivered to the cluster membership
-service.  If this is not specified with IPv4, the node id will be
-determined from the 32 bit IP address the system to which the system
+service.  If this is not specified with IPv4, *nodeid* will be
+determined from the 32bit IP address the system to which the system
 is bound with ring identifier of 0.  The node identifier value of zero
 is reserved and should not be used.</a:documentation>
             <!--
@@ -260,6 +257,15 @@ is reserved and should not be used.</a:documentation>
             <data type="unsignedInt"/>
           </attribute>
         </optional>
+        <optional>
+          <attribute name="quorum_votes">
+            <!--
+              CFG: corosync.conf, cluster.conf
+              NOTE: not a direct mapping in cluster.conf (clusternode/votes)
+              -->
+            <data type="unsignedInt"/>
+          </attribute>
+        </optional>
         <attribute name="ring0_addr">
           <a:documentation>This specifies IP address of one of the nodes for particular ring
 as denoted by its number (instead 0, there can be higher numbers).</a:documentation>
@@ -297,13 +303,16 @@ as denoted by its number (instead 0, there can be higher numbers).</a:documentat
       <!-- NOTE: Augeas lens for corosync.conf counts on X = 0..9 only -->
     </element>
   </define>
+  <!-- QUORUM ###################################################################### -->
   <define name="quorum">
     <element name="quorum">
+      <a:documentation>In this configuration section, one can
+adjust quorum.</a:documentation>
       <group>
         <optional>
           <attribute name="allow_downscale" a:defaultValue="0">
             <a:documentation>This enables Downscale feature
-(see `votequorum(5)`).</a:documentation>
+(see **votequorum**(5)).</a:documentation>
             <!-- CFG: corosync.conf -->
             <choice>
               <value>0</value>
@@ -314,7 +323,7 @@ as denoted by its number (instead 0, there can be higher numbers).</a:documentat
         <optional>
           <attribute name="auto_tie_breaker" a:defaultValue="0">
             <a:documentation>This enables Auto Tie Breaker feature
-(see `votequorum(5)`).</a:documentation>
+(see **votequorum**(5)).</a:documentation>
             <!-- CFG: corosync.conf -->
             <choice>
               <value>0</value>
@@ -324,8 +333,9 @@ as denoted by its number (instead 0, there can be higher numbers).</a:documentat
         </optional>
         <optional>
           <attribute name="expected_votes">
-            <a:documentation>This specifies the number of expected votes, overriding the number
-implied by the number of *node* items within *nodes*.</a:documentation>
+            <a:documentation>This specifies the number of expected
+votes, overriding the number implied by the number of *node* items
+within *nodes*.</a:documentation>
             <!-- CFG: corosync.conf, cluster.conf -->
             <data type="unsignedInt"/>
           </attribute>
@@ -333,7 +343,7 @@ implied by the number of *node* items within *nodes*.</a:documentation>
         <optional>
           <attribute name="last_man_standing" a:defaultValue="0">
             <a:documentation>This enables Last Man Standing feature
-(see `votequorum(5)`).</a:documentation>
+(see **votequorum**(5)).</a:documentation>
             <!-- CFG: corosync.conf -->
             <choice>
               <value>0</value>
@@ -344,7 +354,7 @@ implied by the number of *node* items within *nodes*.</a:documentation>
         <optional>
           <attribute name="last_man_standing_window" a:defaultValue="0">
             <a:documentation>This specifies the tunable for Last Man
-Standing feature (see `votequorum(5)`).</a:documentation>
+Standing feature (see **votequorum**(5)).</a:documentation>
             <!-- CFG: corosync.conf -->
             <data type="nonNegativeInteger"/>
           </attribute>
@@ -360,7 +370,7 @@ As of now, only 'corosync_votequorum' is supported.</a:documentation>
         <optional>
           <attribute name="two_node" a:defaultValue="0">
             <a:documentation>This enables two node cluster operations
-(see `votequorum(5)`).</a:documentation>
+(see **votequorum**(5)).</a:documentation>
             <!-- CFG: corosync.conf, cluster.conf -->
             <choice>
               <value>0</value>
@@ -369,9 +379,15 @@ As of now, only 'corosync_votequorum' is supported.</a:documentation>
           </attribute>
         </optional>
         <optional>
+          <attribute name="votes">
+            <!-- CFG: corosync.conf -->
+            <data type="unsignedInt"/>
+          </attribute>
+        </optional>
+        <optional>
           <attribute name="wait_for_all" a:defaultValue="0">
             <a:documentation>This enables Wait For All feature
-(see `votequorum(5)`).</a:documentation>
+(see **votequorum**(5)).</a:documentation>
             <!-- CFG: corosync.conf -->
             <choice>
               <value>0</value>
@@ -382,19 +398,84 @@ As of now, only 'corosync_votequorum' is supported.</a:documentation>
       </group>
     </element>
   </define>
+  <!-- RESOURCES ################################################################### -->
+  <!-- only named set of attributes -->
+  <define name="common_resource">
+    <optional>
+      <attribute name="max">
+        <!-- XXX: undocumented -->
+        <data type="decimal"/>
+      </attribute>
+    </optional>
+    <optional>
+      <attribute name="poll_period">
+        <!-- XXX: undocumented -->
+        <data type="unsignedInt"/>
+      </attribute>
+    </optional>
+    <optional>
+      <attribute name="recovery">
+        <!-- XXX: undocumented -->
+        <choice>
+          <value>reboot</value>
+          <value>shutdown</value>
+          <value>watchdog</value>
+          <value>none</value>
+        </choice>
+      </attribute>
+    </optional>
+  </define>
+  <define name="load_15min">
+    <element name="load_15min">
+      <optional>
+        <ref name="common_resource"/>
+      </optional>
+    </element>
+  </define>
+  <define name="memory_used">
+    <element name="memory_used">
+      <optional>
+        <ref name="common_resource"/>
+      </optional>
+    </element>
+  </define>
+  <define name="system">
+    <element name="system">
+      <interleave>
+        <optional>
+          <ref name="load_15min"/>
+        </optional>
+        <optional>
+          <ref name="memory_used"/>
+        </optional>
+      </interleave>
+    </element>
+  </define>
+  <define name="resources">
+    <element name="resources">
+      <optional>
+        <ref name="system"/>
+      </optional>
+    </element>
+  </define>
+  <!-- TOTEM ####################################################################### -->
   <define name="totem">
     <element name="totem">
+      <a:documentation>In this configuration section, one can
+adjust totem protocol.</a:documentation>
       <group>
         <optional>
           <attribute name="clear_node_high_bit" a:defaultValue="no"
-              a4doc:discretion-hint="The clusters behavior is undefined if this option is enabled on only a subset of the cluster (for example during a rolling upgrade).">
-            <a:documentation>This configuration option is optional and
-is only relevant when no *nodeid* is specified.  Some corosync clients
-require a signed 32 bit nodeid that is greater than zero however by
-default corosync uses all 32 bits of the IPv4 address space when
-generating a nodeid.  Set this option to 'yes' to force the high bit
-to be zero and therefor ensure the nodeid is a positive signed 32 bit
-integer.</a:documentation>
+              a4doc:discretion-hint="
+        The clusters behavior is undefined if this option is enabled on only
+        a subset of the cluster (for example during a rolling upgrade).">
+            <a:documentation>This configuration option is only relevant
+when no *nodeid* option within *nodelist* section is specified.  Some
+corosync clients require a signed 32bit nodeid that is greater than
+zero however, by default, corosync uses all 32 bits of the IPv4 address
+space when generating a nodeid.
+Set this option to 'yes' to force the high bit to be zero and therefor
+ensure the nodeid is a positive signed 32bit integer.</a:documentation>
             <!-- CFG: corosync.conf -->
             <choice>
               <value>no</value>
@@ -418,14 +499,14 @@ used for automatic generating of multicast address.</a:documentation>
             <a:documentation>This timeout specifies in milliseconds how
 long to wait for consensus to be achieved before starting a new round
 of membership configuration.  The minimum value for *consensus* must be
-1.2 * *token*.
+1.2 x *token*.
 
-This value will be automatically calculated at 1.2 * *token* if
+This value will be automatically calculated at 1.2 x *token* if
 the user doesn't specify a *consensus* value.
 
-For two node clusters, a *consensus* larger then the *join* timeout but
-less then *token* is safe.  For three node or larger clusters,
-*consensus* should be larger then token.  There is an increasing risk
+For two node clusters, a *consensus* larger than the *join* timeout but
+less than *token* is safe.  For three-node or larger clusters,
+*consensus* should be larger than *token*.  There is an increasing risk
 of odd membership changes, which still guarantee virtual synchrony,
 as node count grows if *consensus* is less than *token*.</a:documentation>
             <!--
@@ -438,8 +519,7 @@ as node count grows if *consensus* is less than *token*.</a:documentation>
         <optional>
           <attribute name="crypto_cipher" a:defaultValue="aes256">
             <a:documentation>This specifies which cipher should be used
-to encrypt all messages.  Valid values are 'none' (no encryption),
-'aes256', 'aes192', 'aes128' and '3des'.</a:documentation>
+to encrypt all messages.</a:documentation>
             <!--
               XXX: missing nss?
               CFG: corosync.conf
@@ -455,7 +535,7 @@ to encrypt all messages.  Valid values are 'none' (no encryption),
         </optional>
         <optional>
           <attribute name="crypto_compat">
-            <!-- CFG: undocumented -->
+            <!-- XXX: undocumented -->
             <choice>
               <value>2.0</value>
               <value>2.2</value>
@@ -465,8 +545,7 @@ to encrypt all messages.  Valid values are 'none' (no encryption),
         <optional>
           <attribute name="crypto_hash" a:defaultValue="sha1">
             <a:documentation>This specifies which HMAC authentication
-should be used to authenticate all messages.  Valid values are 'none'
-(no authentication), 'md5', 'sha1', 'sha256', 'sha384' and 'sha512'.</a:documentation>
+should be used to authenticate all messages.</a:documentation>
             <!-- CFG: corosync.conf -->
             <choice>
               <value>none</value>
@@ -480,7 +559,7 @@ should be used to authenticate all messages.  Valid values are 'none'
         </optional>
         <optional>
           <attribute name="crypto_type">
-            <!-- CFG: undocumented -->
+            <!-- XXX: undocumented -->
             <choice>
               <value>3des</value>
               <value>aes128</value>
@@ -520,7 +599,7 @@ failure in low to medium utilized networks.
 
 This constant specifies the number of heartbeat failures the system
 should tolerate before declaring heartbeat failure, e.g., 3.
-Also if this value is not set or is 0 then the heartbeat mechanism is
+Also if this value is not set or is 0, the heartbeat mechanism is
 not engaged in the system and token rotation is the method of failure
 detection.  Zero disables the mechanism.</a:documentation>
             <!-- CFG: corosync.conf -->
@@ -529,7 +608,9 @@ detection.  Zero disables the mechanism.</a:documentation>
         </optional>
         <optional>
           <attribute name="hold" a:defaultValue="180"
-              a4doc:danger-hint="It is not recommended to override this value without guidance from the corosync community.">
+              a4doc:danger-hint="
+        It is not recommended to override this value without guidance from
+        the corosync community.">
             <a:documentation>This timeout specifies in milliseconds
 how long the token should be held by the representative when
 the protocol is under low utilization.</a:documentation>
@@ -588,35 +669,36 @@ The default setting works well for nearly all modern switches.</a:documentation>
           </attribute>
         </optional>
         <optional>
-          <attribute name="netmtu" a:defaultValue="1500">
+          <attribute name="netmtu" a:defaultValue="1500"
+              a4doc:discretion-hint="
+        While some NICs or switches claim large frame support, they support
+        9000 MTU as the maximum frame size including the IP header.  Setting
+        the *netmtu* and host MTUs to '9000' will cause totem to use the full
+        9000 bytes of the frame.  Then Linux will add an 18byte header moving
+        the full frame size to 9018.  As a result some hardware will not
+        operate properly with this size of data.  A *netmtu* of '8982' seems
+        to work for the few large frame devices that have been tested.
+        Some manufacturers claim large frame support when in fact they
+        support frame sizes of 4500 bytes.
+
+        When sending multicast traffic, if the network frequently
+        reconfigures, chances are that some device in the network doesn't
+        support large frames.
+        
+        Choose hardware carefully if intending to use large frame support.">
             <a:documentation>This specifies the network maximum transmit
-unit.  To set this value beyond 1500, the regular frame MTU, requires
+unit.  Setting this value beyond '1500', the regular frame MTU, requires
 ethernet devices that support large, or also called jumbo, frames.
 If any device in the network doesn't support large frames, the protocol
-will not operate properly.  The hosts must also have their mtu size set
-from 1500 to whatever frame size is specified here.
-
-Please note while some NICs or switches
-claim large frame support, they support 9000 MTU as the maximum frame
-size including the IP header.  Setting the *netmtu* and host MTUs to 9000
-will cause totem to use the full 9000 bytes of the frame.  Then Linux
-will add a 18 byte header moving the full frame size to 9018.
-As a result some hardware will not operate properly with this size
-of data.  A *netmtu* of 8982 seems to work for the few large frame devices
-that have been tested.  Some manufacturers claim large frame support
-when in fact they support frame sizes of 4500 bytes.
-
-When sending multicast traffic, if the network frequently reconfigures,
-chances are that some device in the network doesn't support large frames.
-
-Choose hardware carefully if intending to use large frame support.</a:documentation>
+will not operate properly.  The hosts must also have their MTU size set
+from 1500 to whatever frame size is specified here.</a:documentation>
             <!-- CFG: corosync.conf, cluster.conf -->
             <data type="unsignedInt"/>
           </attribute>
         </optional>
         <optional>
           <attribute name="nodeid">
-            <!-- CFG: undocumented -->
+            <!-- XXX: undocumented -->
             <data type="unsignedInt"/>
           </attribute>
         </optional>
@@ -630,23 +712,22 @@ to check if the failed ring can be auto-recovered.</a:documentation>
         </optional>
         <optional>
           <attribute name="rrp_mode">
-            <a:documentation>This specifies the mode of redundant ring,
-which may be 'none', 'active', or 'passive'.  Active replication offers
-none`, active, or passive.  Active replication offers
-slightly lower latency from transmit to delivery in faulty network
-environments but with less performance.  Passive replication may nearly
-double the speed of the totem protocol if the protocol doesn't become
-CPU bound.  The final option is none, in which case only one network
+            <a:documentation>This specifies the mode of redundant ring.
+Active replication ('active') offers slightly lower latency from
+transmit to delivery in faulty network environments but with less
+performance.  Passive replication ('passive') may nearly double
+the speed of the totem protocol if it doesn't become CPU bound.
+The remaining option is 'none', in which case only one network
 interface will be used to operate the totem protocol.
 
-If only one *interface* directive is specified, 'none' is automatically
-chosen.  If multiple *interface* directives are specified, only 'active'
+If only one *interface* section is specified, 'none' is automatically
+chosen.  If multiple *interface* sections are specified, only 'active'
 or 'passive' may be chosen.
 
-The maximum number of *interface* directives that is allowed for either
+The maximum number of *interface* sections that is allowed for either
 mode ('active' or 'passive') is 2.</a:documentation>
             <!--
-              XXX: implied check: active,passive -> count(interface) <= 2
+              XXX: implied check: count(interface) <= 4 (2 active + 2 passive)
               CFG: corosync.conf, cluster.conf
               -->
             <choice>
@@ -660,9 +741,9 @@ mode ('active' or 'passive') is 2.</a:documentation>
           <attribute name="rrp_problem_count_mcast_threshold">
             <a:documentation>This specifies the number of times
 a problem is detected with multicast before setting the link faulty for
-passive RRP mode.  This variable is unused in active RRP mode.
+'passive' *rrp_mode*.  This variable is unused in 'active' *rrp_mode*.
 
-The default is 10 times *rrp_problem_count_threshold*.</a:documentation>
+The default is 10 x *rrp_problem_count_threshold*.</a:documentation>
             <!-- CFG: corosync.conf -->
             <data type="unsignedInt"/>
           </attribute>
@@ -677,8 +758,8 @@ timeout expires.
 
 A problem is detected whenever all tokens from the proceeding
 processor have not been received within the *rrp_token_expired_timeout*.
-The *rrp_problem_count_threshold* * *rrp_token_expired_timeout* should be
-at least 50 milliseconds less then the *token* timeout, or a complete
+The *rrp_problem_count_threshold* x *rrp_token_expired_timeout* should be
+at least 50 milliseconds less than the *token* timeout, or a complete
 reconfiguration may occur.</a:documentation>
             <!--
               XXX: implied check
@@ -698,7 +779,9 @@ to ensure a link is not marked faulty for transient network failures.</a:documen
         </optional>
         <optional>
           <attribute name="rrp_token_expired_timeout" a:defaultValue="47"
-              a4doc:danger-hint="It is not recommended to override this value without guidance from the corosync community.">
+              a4doc:danger-hint="
+        It is not recommended to override this value without guidance from
+        the corosync community.">
             <a:documentation>This specifies the time in milliseconds
 to increment the problem counter for the redundant ring protocol after
 not having received a token from all rings for a particular processor.
@@ -711,13 +794,15 @@ and *problem_count_threshold* but may be overridden.</a:documentation>
         </optional>
         <optional>
           <attribute name="secauth" a:defaultValue="on"
-              a4doc:deprecation-hint="It's recomended to use combination of *crypto_cipher* and *crypto_hash*.">
-            <a:documentation>This specifies that HMAC/SHA1 authentication should be used
-to authenticate all messages.  It further specifies that all data
-should be encrypted with the nss library and aes256 encryption
-algorithm to protect data from eavesdropping.
+              a4doc:deprecation-hint="
+        It's recomended to use combination of *crypto_cipher* and *crypto_hash*
+        instead.">
+            <a:documentation>This specifies that HMAC/SHA1
+authentication should be used to authenticate all messages.  It further
+specifies that all data should be encrypted with the `nss` library and
+`aes256` encryption algorithm to protect data from eavesdropping.
 
-Enabling this option adds a encryption header to every message sent
+Enabling this option adds an encryption header to every message sent
 by totem which reduces total throughput.  Also encryption and
 authentication consume extra CPU cycles in corosync.</a:documentation>
             <!--
@@ -732,14 +817,17 @@ authentication consume extra CPU cycles in corosync.</a:documentation>
         </optional>
         <optional>
           <attribute name="send_join" a:defaultValue="0"
-              a4doc:danger-hint="Seek advice from the corosync mailing list if trying to run larger configurations.">
+              a4doc:danger-hint="
+        Seek advice from the corosync mailing list if trying to run larger
+        configurations.">
             <a:documentation>This timeout specifies in milliseconds
 an upper range between 0 and *send_join* to wait before sending a join
-message.  For eprecationtions with less then 32 nodes, this parameter
+message.  For configurations with less than 32 nodes, this parameter
 is not necessary.  For larger rings, this parameter is necessary
 to ensure the NIC is not overflowed with join messages on formation of
 a new ring.  A reasonable value for large rings (128 nodes) would be
-80msec.  Other timer values must also change if this value is changed.</a:documentation>
+__80__msec.  Other timer values must also change if this value
+is changed.</a:documentation>
             <!-- CFG: corosync.conf -->
             <data type="unsignedInt"/>
           </attribute>
@@ -755,27 +843,30 @@ timer is started.</a:documentation>
         </optional>
         <optional>
           <attribute name="threads">
-            <!-- CFG: undocumented -->
+            <!-- XXX: undocumented -->
             <data type="unsignedInt"/>
           </attribute>
         </optional>
         <optional>
           <attribute name="token" a:defaultValue="1000">
-            <a:documentation>This timeout specifies in milliseconds
-until a token loss is declared after not receiving a token.  This is
-the time spent detecting a failure of a processor in the current
-configuration.  Reforming a new configuration takes about 50
-milliseconds in addition to this timeout.</a:documentation>
+            <a:documentation>This timeout specifies a period in
+milliseconds until a token loss is declared after not receiving
+a token.  This is the time spent detecting a failure of a processor
+in the current configuration.  Reforming a new configuration takes
+about 50 milliseconds in addition to this timeout.</a:documentation>
             <!-- CFG: corosync.conf, cluster.conf -->
             <data type="unsignedInt"/>
           </attribute>
         </optional>
         <optional>
           <attribute name="token_retransmit" a:defaultValue="238"
-              a4doc:danger-hint="It is not recommended to override this value without guidance from the corosync community.">
-            <a:documentation>This timeout specifies in milliseconds
-after how long before receiving a token the token is retransmitted.
-This will be automatically calculated if token is modified.</a:documentation>
+              a4doc:danger-hint="
+        It is not recommended to override this value without guidance from
+        the corosync community.">
+            <a:documentation>This timeout specifies a period in
+milliseconds without receiving a token after which the token is
+retransmitted.  This will be automatically calculated if *token* is
+modified.</a:documentation>
             <!-- CFG: corosync.conf -->
             <data type="unsignedInt"/>
           </attribute>
@@ -785,13 +876,20 @@ This will be automatically calculated if token is modified.</a:documentation>
             <a:documentation>This value identifies how many token
 retransmits should be attempted before forming a new configuration.
 If this value is set, retransmit and hold will be automatically
-calculated from *retransmits_before_loss* and token.</a:documentation>
+calculated from *retransmits_before_loss* and *token*.</a:documentation>
             <!-- CFG: corosync.conf, cluster.conf -->
             <data type="unsignedInt"/>
           </attribute>
         </optional>
         <optional>
           <attribute name="transport" a:defaultValue="udp">
+            <a:documentation>This option controls the transport
+mechanism used.  If the interface to which corosync is binding is
+an RDMA interface such as RoCEE or Infiniband, the 'iba' parameter
+may be specified.  To avoid the use of multicast entirely, a unicast
+transport parameter 'udpu' can be specified.  This requires specifying
+the list of members that could potentially make up the membership
+in *nodelist* section before deployment.</a:documentation>
             <!-- CFG: corosync.conf -->
             <choice>
               <value>iba</value>
@@ -801,13 +899,6 @@ calculated from *retransmits_before_loss* and token.</a:documentation>
           </attribute>
         </optional>
         <attribute name="version">
-          <a:documentation>This option controls the transport
-mechanism used.  If the interface to which corosync is binding is
-an RDMA interface such as RoCEE or Infiniband, the 'iba' parameter
-may be specified.  To avoid the use of multicast entirely, a unicast
-transport parameter 'udpu' can be specified.  This requires specifying
-the list of members in *nodelist* directive, that could potentially make
-up the membership before deployment.</a:documentation>
           <a:documentation>This specifies the version of
 the configuration file.  Currently the only valid value for this
 option is '2'.</a:documentation>
@@ -818,8 +909,8 @@ option is '2'.</a:documentation>
           <attribute name="vsftype" a:defaultValue="ykd">
             <a:documentation>This option controls the virtual
 synchrony filter type used to identify a primary component.
-The preferred choice is YKD dynamic linear voting, however, for
-clusters larger then 32 nodes YKD consumes alot of memory.  For large
+The preferred choice is YKD dynamic linear voting ('ykd'), however, for
+clusters larger than 32 nodes YKD consumes a lot of memory.  For large
 scale clusters that are created by changing the MAX_PROCESSORS_COUNT
 #define in the C code totem.h file, the virtual synchrony filter 'none'
 is recommended but then AMF and DLCK services (which are currently
@@ -835,11 +926,11 @@ experimental) are not safe for use.</a:documentation>
           <attribute name="window_size" a:defaultValue="50">
             <a:documentation>This constant specifies the maximum number
 of messages that may be sent on one token rotation.  If all processors
-perform equally well, this value could be large (300), which would
+perform equally well, this value could be large ('300'), which would
 introduce higher latency from origination to delivery for very large
-rings.  To reduce latency in large rings (16+), the defaults are a safe
+rings.  To reduce latency in large rings (16+), the default is a safe
 compromise.  If 1 or more slow processor(s) are present among fast
-processors, *window_size* should be no larger then 256000 / *netmtu*
+processors, *window_size* should be no larger than 256000 / *netmtu*
 to avoid overflow of the kernel receive buffers.  The user is notified
 of this by the display of a retransmit list in the notification logs.
 There is no loss of data, but performance is reduced when these errors
@@ -875,17 +966,17 @@ used.  In this case, the exact address must be specified and there is no
 automatic selection of the network interface within a specific subnet
 as with IPv4.
 
-If IPv6 networking is used, the *nodeid* field in *nodelist* must be
-specified.</a:documentation>
+If IPv6 networking is used, *nodeid* options within *nodelist* section
+must be specified.</a:documentation>
             <!-- CFG: corosync.conf, cluster.conf -->
             <text/>
           </attribute>
         </optional>
         <optional>
           <attribute name="broadcast" a:defaultValue="no">
-            <a:documentation>This is optional and can be set to 'yes'.  If it is set to 'yes',
-the broadcast address will be used for communication.  If this option
-is set, *mcastaddr* should not be set.</a:documentation>
+            <a:documentation>If this is set to 'yes', the broadcast
+address will be used for communication.  If this option is set,
+*mcastaddr* should not be set.</a:documentation>
             <!-- CFG: corosync.conf -->
             <choice>
               <value>no</value>
@@ -901,11 +992,12 @@ the network administrator should be queried about a multicast address
 to use.  Avoid `224.x.x.x` because this is a "config" multicast address.
 
 This may also be an IPv6 multicast address, in which case IPv6 networking
-will be used.  If IPv6 networking is used, the *nodeid* field in
-*nodelist* must be specified.
+will be used.  If IPv6 networking is used, *nodeid* options within
+*nodelist* section must be specified.
 
-It's not needed to use this option if *cluster_name* option is used.
-If both options are used, *mcastaddr* has higher priority.</a:documentation>
+It's not needed to use this option if *cluster_name* option in
+*totem* section is used.  If both options are used, *mcastaddr* has
+higher priority.</a:documentation>
             <!-- CFG: corosync.conf, cluster.conf -->
             <text/>
           </attribute>
@@ -917,7 +1009,7 @@ It is possible to use the same multicast address on a network with
 the corosync services configured for different UDP ports.  Please note
 corosync uses two UDP ports *mcastport* (for mcast receives) and
 *mcastport* - 1 (for mcast sends).  If you have multiple  clusters
-on the same network using the same *mcastaddr* please configure
+on the same network using the same *mcastaddr*, please configure
 the **mcastport**s with a gap.</a:documentation>
             <!-- CFG: corosync.conf, cluster.conf -->
             <data type="unsignedShort"/>
@@ -929,30 +1021,53 @@ the **mcastport**s with a gap.</a:documentation>
 the interface.  When using the redundant ring protocol, each interface
 should specify separate ring numbers to uniquely identify to
 the membership protocol which interface to use for which redundant ring.
-The *ringnumber* must start at 0.</a:documentation>
+The *ringnumber* must start at '0'.</a:documentation>
             <!-- CFG: corosync.conf, cluster.conf -->
             <data type="unsignedByte"/>
           </attribute>
         </optional>
         <optional>
-          <attribute name="ttl" a:defaultValue="1">
+          <attribute name="ttl" a:defaultValue="1"
+              a4doc:dicretion-hint="
+        This is only valid on multicast transport types.">
             <a:documentation>This specifies the Time To Live (TTL).
-If you run your cluster on a routed network then the default of '1' will
+If you run your cluster on a routed network, the default of '1' will
 be too small.  This option provides a way to increase this up to '255'.
-The valid range is '0..255'.  Note that this is only valid on multicast
-transport types.</a:documentation>
-            <!-- CFG: corosync.conf, cluster.conf -->
+The valid range is '0..255'.</a:documentation>
+            <!--
+              XXX: implied check
+              CFG: corosync.conf, cluster.conf
+              -->
             <data type="unsignedByte"/>
           </attribute>
         </optional>
       </group>
     </element>
   </define>
-  <!--
-    uidgid =
-     element uidgid {
-       attribute uid {text}?,
-       attribute gid {text}?
-     }
-    -->
+  <!-- UIDGID ###################################################################### -->
+  <define name="uidgid">
+    <element name="uidgid">
+      <group>
+        <optional>
+          <attribute name="uid">
+            <!--
+              CFG: corosync.conf, cluster.conf
+              XXX: undocumented
+              -->
+            <text/>
+          </attribute>
+        </optional>
+        <optional>
+          <attribute name="gid">
+            <!--
+              CFG: corosync.conf, cluster.conf
+              XXX: undocumented
+              -->
+            <text/>
+          </attribute>
+        </optional>
+      </group>
+    </element>
+  </define>
+  <!-- vim: set et ts=2 sw=2: -->
 </grammar>
diff --git a/corosync.rng.trang b/corosync.rng.trang
index e53e6a0..cc2c6a8 100644
--- a/corosync.rng.trang
+++ b/corosync.rng.trang
@@ -1,9 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
-  style guide (RELAX NG Compact only):
-  * '##' comments are wrapped at 50/80 (first line/rest), 2-spaced sentence
-    separator, AsciiDoc formatting is used within them
-  * sort everything you can to ease the lookup
+  guidelines (relevant to source in RELAX NG Compact form):
+  * '##' comments are wrapped at 50/80 (first line/rest), 2-spaced sentence sep,
+    AsciiDoc formatting is used within them
+  * sort everything (except for dependencies/nesting) to ease the lookup
+  * for common datatypes, refer to http://www.w3.org/TR/xmlschema11-2
 -->
 <grammar xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0" xmlns:a4doc="http://people.redhat.com/jpokorny/ns/a4doc" xmlns="http://relaxng.org/ns/structure/1.0" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
   <start>
@@ -19,6 +20,9 @@
           <ref name="nodelist"/>
         </optional>
         <optional>
+          <ref name="resources"/>
+        </optional>
+        <optional>
           <ref name="quorum"/>
         </optional>
         <ref name="totem"/>
@@ -28,25 +32,35 @@
       </interleave>
     </element>
   </define>
-  <define name="macro.logging_attributes">
+  <!-- LOGGING ##################################################################### -->
+  <!-- only named set of attributes -->
+  <define name="common_logging">
     <optional>
       <!-- CFG: corosync.conf, cluster.conf -->
       <attribute name="debug" a:defaultValue="off">
         <a:documentation>This specifies whether debug output is
-logged for this particular logger.  Also can contain value trace, what
-is highest level of debug informations.</a:documentation>
+logged for this particular logger.  Also can contain value 'trace',
+which is highest level of debug messages.</a:documentation>
         <choice>
           <value>off</value>
           <value>on</value>
+          <value>trace</value>
         </choice>
       </attribute>
     </optional>
     <optional>
       <!-- CFG: corosync.conf, cluster.conf -->
-      <attribute name="logfile_priority" a:defaultValue="info">
-        <a:documentation>This specifies the logfile level for this particular subsystem.  Ignored
-if *debug* is 'on'.  Possible  values are: 'alert', 'crit', 'debug'
-(same as *debug =* 'on'), 'emerg', 'err', 'info', 'notice' and 'warning'.</a:documentation>
+      <attribute name="logfile">
+        <a:documentation>If the *to_logfile* option is set to
+'yes', this option specifies the pathname of the log file.</a:documentation>
+      </attribute>
+    </optional>
+    <optional>
+      <!-- CFG: corosync.conf, cluster.conf -->
+      <attribute name="logfile_priority" a:defaultValue="info" a4doc:hint="
+        Value 'debug' is the same as if *debug* is 'on'.">
+        <a:documentation>This specifies the logfile level for this
+particular subsystem.  Ignored if *debug* is 'on'.</a:documentation>
         <choice>
           <value>alert</value>
           <value>crit</value>
@@ -63,9 +77,7 @@ if *debug* is 'on'.  Possible  values are: 'alert', 'crit', 'debug'
       <!-- CFG: corosync.conf, cluster.conf -->
       <attribute name="syslog_facility" a:defaultValue="daemon">
         <a:documentation>This specifies the syslog facility type
-that will be used for any messages sent to syslog.  Options are
-'daemon', 'local0', 'local1', 'local2', 'local3', 'local4', 'local5',
-'local6' and 'local7'.</a:documentation>
+that will be used for any messages sent to syslog.</a:documentation>
         <choice>
           <value>daemon</value>
           <value>local0</value>
@@ -81,11 +93,10 @@ that will be used for any messages sent to syslog.  Options are
     </optional>
     <optional>
       <!-- CFG: corosync.conf, cluster.conf -->
-      <attribute name="syslog_priority" a:defaultValue="info">
+      <attribute name="syslog_priority" a:defaultValue="info" a4doc:hint="
+        Value 'debug' is the same as if *debug* is 'on'.">
         <a:documentation>This specifies the syslog level for this
-particular subsystem.  Ignored if *debug* is 'on'.  Possible  values are:
-'alert', 'crit', 'debug' (same as *debug =* 'on'), 'emerg', 'err',
-'info', 'notice' and 'warning'.</a:documentation>
+particular subsystem.  Ignored if *debug* is 'on'.</a:documentation>
         <choice>
           <value>alert</value>
           <value>crit</value>
@@ -99,15 +110,19 @@ particular subsystem.  Ignored if *debug* is 'on'.  Possible  values are:
       </attribute>
     </optional>
     <optional>
+      <!-- XXX: undocumented -->
+      <attribute name="tags"/>
+    </optional>
+    <optional>
       <!-- CFG: corosync.conf, cluster.conf -->
       <attribute name="to_logfile" a:defaultValue="no">
-        <a:documentation>This specifies the destination
-of logging output.
+        <a:documentation>This specifies whether to use
+the respective destination of logging output.
 
 Please note, if you are using *to_logfile* and want to rotate the file,
 use `logrotate(8)` with the option `copytruncate`, e.g.
 
----- 
+----
 /var/log/corosync.log {
     missingok
     compress
@@ -126,8 +141,8 @@ use `logrotate(8)` with the option `copytruncate`, e.g.
     <optional>
       <!-- CFG: corosync.conf -->
       <attribute name="to_stderr" a:defaultValue="yes">
-        <a:documentation>This specifies the destination
-of logging output.</a:documentation>
+        <a:documentation>This specifies whether to use
+the respective destination of logging output.</a:documentation>
         <choice>
           <value>no</value>
           <value>yes</value>
@@ -137,8 +152,8 @@ of logging output.</a:documentation>
     <optional>
       <!-- CFG: corosync.conf, cluster.conf -->
       <attribute name="to_syslog" a:defaultValue="yes">
-        <a:documentation>This specifies the destination
-of logging output.</a:documentation>
+        <a:documentation>This specifies whether to use
+the respective destination of logging output.</a:documentation>
         <choice>
           <value>no</value>
           <value>yes</value>
@@ -148,11 +163,13 @@ of logging output.</a:documentation>
   </define>
   <define name="logging">
     <element name="logging">
+      <a:documentation>In this configuration section, one can
+adjust logging.</a:documentation>
       <optional>
         <!-- CFG: corosync.conf -->
-        <attribute name="timestamp" a:defaultValue="off">
-          <a:documentation>This specifies that a timestamp is placed
-on all log messages.</a:documentation>
+        <attribute name="fileline" a:defaultValue="off">
+          <a:documentation>This specifies that file and line should
+be printed.</a:documentation>
           <choice>
             <value>off</value>
             <value>on</value>
@@ -161,9 +178,9 @@ on all log messages.</a:documentation>
       </optional>
       <optional>
         <!-- CFG: corosync.conf -->
-        <attribute name="fileline" a:defaultValue="off">
-          <a:documentation>This specifies that file and line should
-be printed.</a:documentation>
+        <attribute name="function_name" a:defaultValue="off">
+          <a:documentation>This specifies that the code function name
+should be printed.</a:documentation>
           <choice>
             <value>off</value>
             <value>on</value>
@@ -172,16 +189,16 @@ be printed.</a:documentation>
       </optional>
       <optional>
         <!-- CFG: corosync.conf -->
-        <attribute name="function_name" a:defaultValue="off">
-          <a:documentation>This specifies that the code function name
-should be printed.</a:documentation>
+        <attribute name="timestamp" a:defaultValue="off">
+          <a:documentation>This specifies that a timestamp is placed
+on all log messages.</a:documentation>
           <choice>
             <value>off</value>
             <value>on</value>
           </choice>
         </attribute>
       </optional>
-      <ref name="macro.logging_attributes"/>
+      <ref name="common_logging"/>
       <zeroOrMore>
         <ref name="logger_subsys"/>
       </zeroOrMore>
@@ -189,21 +206,23 @@ should be printed.</a:documentation>
   </define>
   <define name="logger_subsys">
     <element name="logger_subsys">
-      <ref name="macro.logging_attributes"/>
       <!-- CFG: corosync.conf, cluster.conf -->
       <attribute name="subsys">
         <a:documentation>This specifies the subsystem identity
 (name) for which logging is specified.  This is the name used by
-a service in the `log_init` call.  E.g., 'CPG'.
-This option is required.</a:documentation>
+a service in the `log_init` call, e.g., 'CPG'.</a:documentation>
       </attribute>
+      <ref name="common_logging"/>
     </element>
   </define>
+  <!-- NODELIST #################################################################### -->
   <define name="nodelist">
     <element name="nodelist">
-      <optional>
+      <a:documentation>In this configuration section, one can
+adjust nodes in the cluster.</a:documentation>
+      <zeroOrMore>
         <ref name="node"/>
-      </optional>
+      </zeroOrMore>
     </element>
   </define>
   <define name="node">
@@ -214,17 +233,26 @@ This option is required.</a:documentation>
             XXX: implied check
             CFG: corosync.conf, cluster.conf
           -->
-          <attribute name="noid">
+          <attribute name="nodeid">
             <a:documentation>This configuration option is optional when
-using IPv4 and required when using IPv6.  This is a 32 bit value
+using IPv4 and required when using IPv6.  This is a 32bit value
 specifying the node identifier delivered to the cluster membership
-service.  If this is not specified with IPv4, the node id will be
-determined from the 32 bit IP address the system to which the system
+service.  If this is not specified with IPv4, *nodeid* will be
+determined from the 32bit IP address the system to which the system
 is bound with ring identifier of 0.  The node identifier value of zero
 is reserved and should not be used.</a:documentation>
             <data type="unsignedInt"/>
           </attribute>
         </optional>
+        <optional>
+          <!--
+            CFG: corosync.conf, cluster.conf
+            NOTE: not a direct mapping in cluster.conf (clusternode/votes)
+          -->
+          <attribute name="quorum_votes">
+            <data type="unsignedInt"/>
+          </attribute>
+        </optional>
         <!-- CFG: corosync.conf, cluster.conf -->
         <attribute name="ring0_addr">
           <a:documentation>This specifies IP address of one of the nodes for particular ring
@@ -261,13 +289,16 @@ as denoted by its number (instead 0, there can be higher numbers).</a:documentat
       <!-- NOTE: Augeas lens for corosync.conf counts on X = 0..9 only -->
     </element>
   </define>
+  <!-- QUORUM ###################################################################### -->
   <define name="quorum">
     <element name="quorum">
+      <a:documentation>In this configuration section, one can
+adjust quorum.</a:documentation>
       <optional>
         <!-- CFG: corosync.conf -->
         <attribute name="allow_downscale" a:defaultValue="0">
           <a:documentation>This enables Downscale feature
-(see `votequorum(5)`).</a:documentation>
+(see **votequorum**(5)).</a:documentation>
           <choice>
             <value>0</value>
             <value>1</value>
@@ -278,7 +309,7 @@ as denoted by its number (instead 0, there can be higher numbers).</a:documentat
         <!-- CFG: corosync.conf -->
         <attribute name="auto_tie_breaker" a:defaultValue="0">
           <a:documentation>This enables Auto Tie Breaker feature
-(see `votequorum(5)`).</a:documentation>
+(see **votequorum**(5)).</a:documentation>
           <choice>
             <value>0</value>
             <value>1</value>
@@ -288,8 +319,9 @@ as denoted by its number (instead 0, there can be higher numbers).</a:documentat
       <optional>
         <!-- CFG: corosync.conf, cluster.conf -->
         <attribute name="expected_votes">
-          <a:documentation>This specifies the number of expected votes, overriding the number
-implied by the number of *node* items within *nodes*.</a:documentation>
+          <a:documentation>This specifies the number of expected
+votes, overriding the number implied by the number of *node* items
+within *nodes*.</a:documentation>
           <data type="unsignedInt"/>
         </attribute>
       </optional>
@@ -297,7 +329,7 @@ implied by the number of *node* items within *nodes*.</a:documentation>
         <!-- CFG: corosync.conf -->
         <attribute name="last_man_standing" a:defaultValue="0">
           <a:documentation>This enables Last Man Standing feature
-(see `votequorum(5)`).</a:documentation>
+(see **votequorum**(5)).</a:documentation>
           <choice>
             <value>0</value>
             <value>1</value>
@@ -308,7 +340,7 @@ implied by the number of *node* items within *nodes*.</a:documentation>
         <!-- CFG: corosync.conf -->
         <attribute name="last_man_standing_window" a:defaultValue="0">
           <a:documentation>This specifies the tunable for Last Man
-Standing feature (see `votequorum(5)`).</a:documentation>
+Standing feature (see **votequorum**(5)).</a:documentation>
           <data type="nonNegativeInteger"/>
         </attribute>
       </optional>
@@ -324,7 +356,7 @@ As of now, only 'corosync_votequorum' is supported.</a:documentation>
         <!-- CFG: corosync.conf, cluster.conf -->
         <attribute name="two_node" a:defaultValue="0">
           <a:documentation>This enables two node cluster operations
-(see `votequorum(5)`).</a:documentation>
+(see **votequorum**(5)).</a:documentation>
           <choice>
             <value>0</value>
             <value>1</value>
@@ -333,9 +365,15 @@ As of now, only 'corosync_votequorum' is supported.</a:documentation>
       </optional>
       <optional>
         <!-- CFG: corosync.conf -->
+        <attribute name="votes">
+          <data type="unsignedInt"/>
+        </attribute>
+      </optional>
+      <optional>
+        <!-- CFG: corosync.conf -->
         <attribute name="wait_for_all" a:defaultValue="0">
           <a:documentation>This enables Wait For All feature
-(see `votequorum(5)`).</a:documentation>
+(see **votequorum**(5)).</a:documentation>
           <choice>
             <value>0</value>
             <value>1</value>
@@ -344,18 +382,83 @@ As of now, only 'corosync_votequorum' is supported.</a:documentation>
       </optional>
     </element>
   </define>
+  <!-- RESOURCES ################################################################### -->
+  <!-- only named set of attributes -->
+  <define name="common_resource">
+    <optional>
+      <!-- XXX: undocumented -->
+      <attribute name="max">
+        <data type="decimal"/>
+      </attribute>
+    </optional>
+    <optional>
+      <!-- XXX: undocumented -->
+      <attribute name="poll_period">
+        <data type="unsignedInt"/>
+      </attribute>
+    </optional>
+    <optional>
+      <!-- XXX: undocumented -->
+      <attribute name="recovery">
+        <choice>
+          <value>reboot</value>
+          <value>shutdown</value>
+          <value>watchdog</value>
+          <value>none</value>
+        </choice>
+      </attribute>
+    </optional>
+  </define>
+  <define name="load_15min">
+    <element name="load_15min">
+      <optional>
+        <ref name="common_resource"/>
+      </optional>
+    </element>
+  </define>
+  <define name="memory_used">
+    <element name="memory_used">
+      <optional>
+        <ref name="common_resource"/>
+      </optional>
+    </element>
+  </define>
+  <define name="system">
+    <element name="system">
+      <interleave>
+        <optional>
+          <ref name="load_15min"/>
+        </optional>
+        <optional>
+          <ref name="memory_used"/>
+        </optional>
+      </interleave>
+    </element>
+  </define>
+  <define name="resources">
+    <element name="resources">
+      <optional>
+        <ref name="system"/>
+      </optional>
+    </element>
+  </define>
+  <!-- TOTEM ####################################################################### -->
   <define name="totem">
     <element name="totem">
+      <a:documentation>In this configuration section, one can
+adjust totem protocol.</a:documentation>
       <optional>
         <!-- CFG: corosync.conf -->
-        <attribute name="clear_node_high_bit" a:defaultValue="no" a4doc:discretion-hint="The clusters behavior is undefined if this option is enabled on only a subset of the cluster (for example during a rolling upgrade).">
-          <a:documentation>This configuration option is optional and
-is only relevant when no *nodeid* is specified.  Some corosync clients
-require a signed 32 bit nodeid that is greater than zero however by
-default corosync uses all 32 bits of the IPv4 address space when
-generating a nodeid.  Set this option to 'yes' to force the high bit
-to be zero and therefor ensure the nodeid is a positive signed 32 bit
-integer.</a:documentation>
+        <attribute name="clear_node_high_bit" a:defaultValue="no" a4doc:discretion-hint="
+        The clusters behavior is undefined if this option is enabled on only
+        a subset of the cluster (for example during a rolling upgrade).">
+          <a:documentation>This configuration option is only relevant
+when no *nodeid* option within *nodelist* section is specified.  Some
+corosync clients require a signed 32bit nodeid that is greater than
+zero however, by default, corosync uses all 32 bits of the IPv4 address
+space when generating a nodeid.
+Set this option to 'yes' to force the high bit to be zero and therefor
+ensure the nodeid is a positive signed 32bit integer.</a:documentation>
           <choice>
             <value>no</value>
             <value>yes</value>
@@ -381,14 +484,14 @@ used for automatic generating of multicast address.</a:documentation>
           <a:documentation>This timeout specifies in milliseconds how
 long to wait for consensus to be achieved before starting a new round
 of membership configuration.  The minimum value for *consensus* must be
-1.2 * *token*.
+1.2 x *token*.
 
-This value will be automatically calculated at 1.2 * *token* if
+This value will be automatically calculated at 1.2 x *token* if
 the user doesn't specify a *consensus* value.
 
-For two node clusters, a *consensus* larger then the *join* timeout but
-less then *token* is safe.  For three node or larger clusters,
-*consensus* should be larger then token.  There is an increasing risk
+For two node clusters, a *consensus* larger than the *join* timeout but
+less than *token* is safe.  For three-node or larger clusters,
+*consensus* should be larger than *token*.  There is an increasing risk
 of odd membership changes, which still guarantee virtual synchrony,
 as node count grows if *consensus* is less than *token*.</a:documentation>
           <data type="unsignedInt"/>
@@ -401,8 +504,7 @@ as node count grows if *consensus* is less than *token*.</a:documentation>
         -->
         <attribute name="crypto_cipher" a:defaultValue="aes256">
           <a:documentation>This specifies which cipher should be used
-to encrypt all messages.  Valid values are 'none' (no encryption),
-'aes256', 'aes192', 'aes128' and '3des'.</a:documentation>
+to encrypt all messages.</a:documentation>
           <choice>
             <value>3des</value>
             <value>aes128</value>
@@ -413,7 +515,7 @@ to encrypt all messages.  Valid values are 'none' (no encryption),
         </attribute>
       </optional>
       <optional>
-        <!-- CFG: undocumented -->
+        <!-- XXX: undocumented -->
         <attribute name="crypto_compat">
           <choice>
             <value>2.0</value>
@@ -425,8 +527,7 @@ to encrypt all messages.  Valid values are 'none' (no encryption),
         <!-- CFG: corosync.conf -->
         <attribute name="crypto_hash" a:defaultValue="sha1">
           <a:documentation>This specifies which HMAC authentication
-should be used to authenticate all messages.  Valid values are 'none'
-(no authentication), 'md5', 'sha1', 'sha256', 'sha384' and 'sha512'.</a:documentation>
+should be used to authenticate all messages.</a:documentation>
           <choice>
             <value>none</value>
             <value>md5</value>
@@ -438,7 +539,7 @@ should be used to authenticate all messages.  Valid values are 'none'
         </attribute>
       </optional>
       <optional>
-        <!-- CFG: undocumented -->
+        <!-- XXX: undocumented -->
         <attribute name="crypto_type">
           <choice>
             <value>3des</value>
@@ -480,7 +581,7 @@ failure in low to medium utilized networks.
 
 This constant specifies the number of heartbeat failures the system
 should tolerate before declaring heartbeat failure, e.g., 3.
-Also if this value is not set or is 0 then the heartbeat mechanism is
+Also if this value is not set or is 0, the heartbeat mechanism is
 not engaged in the system and token rotation is the method of failure
 detection.  Zero disables the mechanism.</a:documentation>
           <data type="unsignedInt"/>
@@ -488,7 +589,9 @@ detection.  Zero disables the mechanism.</a:documentation>
       </optional>
       <optional>
         <!-- CFG: corosync.conf -->
-        <attribute name="hold" a:defaultValue="180" a4doc:danger-hint="It is not recommended to override this value without guidance from the corosync community.">
+        <attribute name="hold" a:defaultValue="180" a4doc:danger-hint="
+        It is not recommended to override this value without guidance from
+        the corosync community.">
           <a:documentation>This timeout specifies in milliseconds
 how long the token should be held by the representative when
 the protocol is under low utilization.</a:documentation>
@@ -547,33 +650,33 @@ The default setting works well for nearly all modern switches.</a:documentation>
       </optional>
       <optional>
         <!-- CFG: corosync.conf, cluster.conf -->
-        <attribute name="netmtu" a:defaultValue="1500">
+        <attribute name="netmtu" a:defaultValue="1500" a4doc:discretion-hint="
+        While some NICs or switches claim large frame support, they support
+        9000 MTU as the maximum frame size including the IP header.  Setting
+        the *netmtu* and host MTUs to '9000' will cause totem to use the full
+        9000 bytes of the frame.  Then Linux will add an 18byte header moving
+        the full frame size to 9018.  As a result some hardware will not
+        operate properly with this size of data.  A *netmtu* of '8982' seems
+        to work for the few large frame devices that have been tested.
+        Some manufacturers claim large frame support when in fact they
+        support frame sizes of 4500 bytes.
+
+        When sending multicast traffic, if the network frequently
+        reconfigures, chances are that some device in the network doesn't
+        support large frames.
+        
+        Choose hardware carefully if intending to use large frame support.">
           <a:documentation>This specifies the network maximum transmit
-unit.  To set this value beyond 1500, the regular frame MTU, requires
+unit.  Setting this value beyond '1500', the regular frame MTU, requires
 ethernet devices that support large, or also called jumbo, frames.
 If any device in the network doesn't support large frames, the protocol
-will not operate properly.  The hosts must also have their mtu size set
-from 1500 to whatever frame size is specified here.
-
-Please note while some NICs or switches
-claim large frame support, they support 9000 MTU as the maximum frame
-size including the IP header.  Setting the *netmtu* and host MTUs to 9000
-will cause totem to use the full 9000 bytes of the frame.  Then Linux
-will add a 18 byte header moving the full frame size to 9018.
-As a result some hardware will not operate properly with this size
-of data.  A *netmtu* of 8982 seems to work for the few large frame devices
-that have been tested.  Some manufacturers claim large frame support
-when in fact they support frame sizes of 4500 bytes.
-
-When sending multicast traffic, if the network frequently reconfigures,
-chances are that some device in the network doesn't support large frames.
-
-Choose hardware carefully if intending to use large frame support.</a:documentation>
+will not operate properly.  The hosts must also have their MTU size set
+from 1500 to whatever frame size is specified here.</a:documentation>
           <data type="unsignedInt"/>
         </attribute>
       </optional>
       <optional>
-        <!-- CFG: undocumented -->
+        <!-- XXX: undocumented -->
         <attribute name="nodeid">
           <data type="unsignedInt"/>
         </attribute>
@@ -588,24 +691,23 @@ to check if the failed ring can be auto-recovered.</a:documentation>
       </optional>
       <optional>
         <!--
-          XXX: implied check: active,passive -> count(interface) <= 2
+          XXX: implied check: count(interface) <= 4 (2 active + 2 passive)
           CFG: corosync.conf, cluster.conf
         -->
         <attribute name="rrp_mode">
-          <a:documentation>This specifies the mode of redundant ring,
-which may be 'none', 'active', or 'passive'.  Active replication offers
-none`, active, or passive.  Active replication offers
-slightly lower latency from transmit to delivery in faulty network
-environments but with less performance.  Passive replication may nearly
-double the speed of the totem protocol if the protocol doesn't become
-CPU bound.  The final option is none, in which case only one network
+          <a:documentation>This specifies the mode of redundant ring.
+Active replication ('active') offers slightly lower latency from
+transmit to delivery in faulty network environments but with less
+performance.  Passive replication ('passive') may nearly double
+the speed of the totem protocol if it doesn't become CPU bound.
+The remaining option is 'none', in which case only one network
 interface will be used to operate the totem protocol.
 
-If only one *interface* directive is specified, 'none' is automatically
-chosen.  If multiple *interface* directives are specified, only 'active'
+If only one *interface* section is specified, 'none' is automatically
+chosen.  If multiple *interface* sections are specified, only 'active'
 or 'passive' may be chosen.
 
-The maximum number of *interface* directives that is allowed for either
+The maximum number of *interface* sections that is allowed for either
 mode ('active' or 'passive') is 2.</a:documentation>
           <choice>
             <value>active</value>
@@ -619,9 +721,9 @@ mode ('active' or 'passive') is 2.</a:documentation>
         <attribute name="rrp_problem_count_mcast_threshold">
           <a:documentation>This specifies the number of times
 a problem is detected with multicast before setting the link faulty for
-passive RRP mode.  This variable is unused in active RRP mode.
+'passive' *rrp_mode*.  This variable is unused in 'active' *rrp_mode*.
 
-The default is 10 times *rrp_problem_count_threshold*.</a:documentation>
+The default is 10 x *rrp_problem_count_threshold*.</a:documentation>
           <data type="unsignedInt"/>
         </attribute>
       </optional>
@@ -639,8 +741,8 @@ timeout expires.
 
 A problem is detected whenever all tokens from the proceeding
 processor have not been received within the *rrp_token_expired_timeout*.
-The *rrp_problem_count_threshold* * *rrp_token_expired_timeout* should be
-at least 50 milliseconds less then the *token* timeout, or a complete
+The *rrp_problem_count_threshold* x *rrp_token_expired_timeout* should be
+at least 50 milliseconds less than the *token* timeout, or a complete
 reconfiguration may occur.</a:documentation>
           <data type="unsignedInt"/>
         </attribute>
@@ -656,7 +758,9 @@ to ensure a link is not marked faulty for transient network failures.</a:documen
       </optional>
       <optional>
         <!-- CFG: corosync.conf -->
-        <attribute name="rrp_token_expired_timeout" a:defaultValue="47" a4doc:danger-hint="It is not recommended to override this value without guidance from the corosync community.">
+        <attribute name="rrp_token_expired_timeout" a:defaultValue="47" a4doc:danger-hint="
+        It is not recommended to override this value without guidance from
+        the corosync community.">
           <a:documentation>This specifies the time in milliseconds
 to increment the problem counter for the redundant ring protocol after
 not having received a token from all rings for a particular processor.
@@ -671,13 +775,15 @@ and *problem_count_threshold* but may be overridden.</a:documentation>
           XXX: implied check/migration to current items
           CFG: corosync.conf, cluster.conf
         -->
-        <attribute name="secauth" a:defaultValue="on" a4doc:deprecation-hint="It's recomended to use combination of *crypto_cipher* and *crypto_hash*.">
-          <a:documentation>This specifies that HMAC/SHA1 authentication should be used
-to authenticate all messages.  It further specifies that all data
-should be encrypted with the nss library and aes256 encryption
-algorithm to protect data from eavesdropping.
+        <attribute name="secauth" a:defaultValue="on" a4doc:deprecation-hint="
+        It's recomended to use combination of *crypto_cipher* and *crypto_hash*
+        instead.">
+          <a:documentation>This specifies that HMAC/SHA1
+authentication should be used to authenticate all messages.  It further
+specifies that all data should be encrypted with the `nss` library and
+`aes256` encryption algorithm to protect data from eavesdropping.
 
-Enabling this option adds a encryption header to every message sent
+Enabling this option adds an encryption header to every message sent
 by totem which reduces total throughput.  Also encryption and
 authentication consume extra CPU cycles in corosync.</a:documentation>
           <choice>
@@ -688,14 +794,17 @@ authentication consume extra CPU cycles in corosync.</a:documentation>
       </optional>
       <optional>
         <!-- CFG: corosync.conf -->
-        <attribute name="send_join" a:defaultValue="0" a4doc:danger-hint="Seek advice from the corosync mailing list if trying to run larger configurations.">
+        <attribute name="send_join" a:defaultValue="0" a4doc:danger-hint="
+        Seek advice from the corosync mailing list if trying to run larger
+        configurations.">
           <a:documentation>This timeout specifies in milliseconds
 an upper range between 0 and *send_join* to wait before sending a join
-message.  For eprecationtions with less then 32 nodes, this parameter
+message.  For configurations with less than 32 nodes, this parameter
 is not necessary.  For larger rings, this parameter is necessary
 to ensure the NIC is not overflowed with join messages on formation of
 a new ring.  A reasonable value for large rings (128 nodes) would be
-80msec.  Other timer values must also change if this value is changed.</a:documentation>
+__80__msec.  Other timer values must also change if this value
+is changed.</a:documentation>
           <data type="unsignedInt"/>
         </attribute>
       </optional>
@@ -709,7 +818,7 @@ timer is started.</a:documentation>
         </attribute>
       </optional>
       <optional>
-        <!-- CFG: undocumented -->
+        <!-- XXX: undocumented -->
         <attribute name="threads">
           <data type="unsignedInt"/>
         </attribute>
@@ -717,20 +826,23 @@ timer is started.</a:documentation>
       <optional>
         <!-- CFG: corosync.conf, cluster.conf -->
         <attribute name="token" a:defaultValue="1000">
-          <a:documentation>This timeout specifies in milliseconds
-until a token loss is declared after not receiving a token.  This is
-the time spent detecting a failure of a processor in the current
-configuration.  Reforming a new configuration takes about 50
-milliseconds in addition to this timeout.</a:documentation>
+          <a:documentation>This timeout specifies a period in
+milliseconds until a token loss is declared after not receiving
+a token.  This is the time spent detecting a failure of a processor
+in the current configuration.  Reforming a new configuration takes
+about 50 milliseconds in addition to this timeout.</a:documentation>
           <data type="unsignedInt"/>
         </attribute>
       </optional>
       <optional>
         <!-- CFG: corosync.conf -->
-        <attribute name="token_retransmit" a:defaultValue="238" a4doc:danger-hint="It is not recommended to override this value without guidance from the corosync community.">
-          <a:documentation>This timeout specifies in milliseconds
-after how long before receiving a token the token is retransmitted.
-This will be automatically calculated if token is modified.</a:documentation>
+        <attribute name="token_retransmit" a:defaultValue="238" a4doc:danger-hint="
+        It is not recommended to override this value without guidance from
+        the corosync community.">
+          <a:documentation>This timeout specifies a period in
+milliseconds without receiving a token after which the token is
+retransmitted.  This will be automatically calculated if *token* is
+modified.</a:documentation>
           <data type="unsignedInt"/>
         </attribute>
       </optional>
@@ -740,13 +852,20 @@ This will be automatically calculated if token is modified.</a:documentation>
           <a:documentation>This value identifies how many token
 retransmits should be attempted before forming a new configuration.
 If this value is set, retransmit and hold will be automatically
-calculated from *retransmits_before_loss* and token.</a:documentation>
+calculated from *retransmits_before_loss* and *token*.</a:documentation>
           <data type="unsignedInt"/>
         </attribute>
       </optional>
       <optional>
         <!-- CFG: corosync.conf -->
         <attribute name="transport" a:defaultValue="udp">
+          <a:documentation>This option controls the transport
+mechanism used.  If the interface to which corosync is binding is
+an RDMA interface such as RoCEE or Infiniband, the 'iba' parameter
+may be specified.  To avoid the use of multicast entirely, a unicast
+transport parameter 'udpu' can be specified.  This requires specifying
+the list of members that could potentially make up the membership
+in *nodelist* section before deployment.</a:documentation>
           <choice>
             <value>iba</value>
             <value>udp</value>
@@ -754,15 +873,8 @@ calculated from *retransmits_before_loss* and token.</a:documentation>
           </choice>
         </attribute>
       </optional>
+      <!-- CFG: corosync.conf -->
       <attribute name="version">
-        <a:documentation>This option controls the transport
-mechanism used.  If the interface to which corosync is binding is
-an RDMA interface such as RoCEE or Infiniband, the 'iba' parameter
-may be specified.  To avoid the use of multicast entirely, a unicast
-transport parameter 'udpu' can be specified.  This requires specifying
-the list of members in *nodelist* directive, that could potentially make
-up the membership before deployment.</a:documentation>
-        <!-- CFG: corosync.conf -->
         <a:documentation>This specifies the version of
 the configuration file.  Currently the only valid value for this
 option is '2'.</a:documentation>
@@ -773,8 +885,8 @@ option is '2'.</a:documentation>
         <attribute name="vsftype" a:defaultValue="ykd">
           <a:documentation>This option controls the virtual
 synchrony filter type used to identify a primary component.
-The preferred choice is YKD dynamic linear voting, however, for
-clusters larger then 32 nodes YKD consumes alot of memory.  For large
+The preferred choice is YKD dynamic linear voting ('ykd'), however, for
+clusters larger than 32 nodes YKD consumes a lot of memory.  For large
 scale clusters that are created by changing the MAX_PROCESSORS_COUNT
 #define in the C code totem.h file, the virtual synchrony filter 'none'
 is recommended but then AMF and DLCK services (which are currently
@@ -790,11 +902,11 @@ experimental) are not safe for use.</a:documentation>
         <attribute name="window_size" a:defaultValue="50">
           <a:documentation>This constant specifies the maximum number
 of messages that may be sent on one token rotation.  If all processors
-perform equally well, this value could be large (300), which would
+perform equally well, this value could be large ('300'), which would
 introduce higher latency from origination to delivery for very large
-rings.  To reduce latency in large rings (16+), the defaults are a safe
+rings.  To reduce latency in large rings (16+), the default is a safe
 compromise.  If 1 or more slow processor(s) are present among fast
-processors, *window_size* should be no larger then 256000 / *netmtu*
+processors, *window_size* should be no larger than 256000 / *netmtu*
 to avoid overflow of the kernel receive buffers.  The user is notified
 of this by the display of a retransmit list in the notification logs.
 There is no loss of data, but performance is reduced when these errors
@@ -828,16 +940,16 @@ used.  In this case, the exact address must be specified and there is no
 automatic selection of the network interface within a specific subnet
 as with IPv4.
 
-If IPv6 networking is used, the *nodeid* field in *nodelist* must be
-specified.</a:documentation>
+If IPv6 networking is used, *nodeid* options within *nodelist* section
+must be specified.</a:documentation>
         </attribute>
       </optional>
       <optional>
         <!-- CFG: corosync.conf -->
         <attribute name="broadcast" a:defaultValue="no">
-          <a:documentation>This is optional and can be set to 'yes'.  If it is set to 'yes',
-the broadcast address will be used for communication.  If this option
-is set, *mcastaddr* should not be set.</a:documentation>
+          <a:documentation>If this is set to 'yes', the broadcast
+address will be used for communication.  If this option is set,
+*mcastaddr* should not be set.</a:documentation>
           <choice>
             <value>no</value>
             <value>yes</value>
@@ -853,11 +965,12 @@ the network administrator should be queried about a multicast address
 to use.  Avoid `224.x.x.x` because this is a "config" multicast address.
 
 This may also be an IPv6 multicast address, in which case IPv6 networking
-will be used.  If IPv6 networking is used, the *nodeid* field in
-*nodelist* must be specified.
+will be used.  If IPv6 networking is used, *nodeid* options within
+*nodelist* section must be specified.
 
-It's not needed to use this option if *cluster_name* option is used.
-If both options are used, *mcastaddr* has higher priority.</a:documentation>
+It's not needed to use this option if *cluster_name* option in
+*totem* section is used.  If both options are used, *mcastaddr* has
+higher priority.</a:documentation>
         </attribute>
       </optional>
       <optional>
@@ -868,7 +981,7 @@ It is possible to use the same multicast address on a network with
 the corosync services configured for different UDP ports.  Please note
 corosync uses two UDP ports *mcastport* (for mcast receives) and
 *mcastport* - 1 (for mcast sends).  If you have multiple  clusters
-on the same network using the same *mcastaddr* please configure
+on the same network using the same *mcastaddr*, please configure
 the **mcastport**s with a gap.</a:documentation>
           <data type="unsignedShort"/>
         </attribute>
@@ -880,28 +993,44 @@ the **mcastport**s with a gap.</a:documentation>
 the interface.  When using the redundant ring protocol, each interface
 should specify separate ring numbers to uniquely identify to
 the membership protocol which interface to use for which redundant ring.
-The *ringnumber* must start at 0.</a:documentation>
+The *ringnumber* must start at '0'.</a:documentation>
           <data type="unsignedByte"/>
         </attribute>
       </optional>
       <optional>
-        <!-- CFG: corosync.conf, cluster.conf -->
-        <attribute name="ttl" a:defaultValue="1">
+        <!--
+          XXX: implied check
+          CFG: corosync.conf, cluster.conf
+        -->
+        <attribute name="ttl" a:defaultValue="1" a4doc:dicretion-hint="
+        This is only valid on multicast transport types.">
           <a:documentation>This specifies the Time To Live (TTL).
-If you run your cluster on a routed network then the default of '1' will
+If you run your cluster on a routed network, the default of '1' will
 be too small.  This option provides a way to increase this up to '255'.
-The valid range is '0..255'.  Note that this is only valid on multicast
-transport types.</a:documentation>
+The valid range is '0..255'.</a:documentation>
           <data type="unsignedByte"/>
         </attribute>
       </optional>
     </element>
   </define>
+  <!-- UIDGID ###################################################################### -->
+  <define name="uidgid">
+    <element name="uidgid">
+      <optional>
+        <!--
+          CFG: corosync.conf, cluster.conf
+          XXX: undocumented
+        -->
+        <attribute name="uid"/>
+      </optional>
+      <optional>
+        <!--
+          CFG: corosync.conf, cluster.conf
+          XXX: undocumented
+        -->
+        <attribute name="gid"/>
+      </optional>
+    </element>
+  </define>
 </grammar>
-<!--
-  uidgid =
-   element uidgid {
-     attribute uid {text}?,
-     attribute gid {text}?
-   }
--->
+<!-- vim: set et ts=2 sw=2: -->
diff --git a/rnc_tokenize.py b/rnc_tokenize.py
index 3620825..0c614fc 100644
--- a/rnc_tokenize.py
+++ b/rnc_tokenize.py
@@ -69,7 +69,7 @@ immediate_tokens = tuple('''
   NAME
   PATTERN
   SEQ
-  WHITESPACE
+  VSPACE
   '''.split()) + quant_tokens
 
 # http://relaxng.org/compact-20021121.html#syntax
@@ -136,9 +136,6 @@ NCName = NCName_start + "(?:" + NCName_nonstart + ")*"
 
 # lex internals
 
-t_ignore = " \t\n"
-
-
 def t_error(t):
     try:
         t.lexer.skip(1)
@@ -155,23 +152,23 @@ t_INTERLEAVE = r'&'
 t_MAYBE      = r'\?'
 t_SEQ        = r','
 t_SOME       = r'\+'
-t_WHITESPACE = r'\s+'
+t_VSPACE     = r'\n\s*\n'
 
 
 def t_ANNOTATION(t):
-    r"\#\#[ \t]?.*"
+    r"\#\#[ \t]?[^\n]*"
     t.value = t.value.replace('# ', '#', 1).split('##', 1)[1].rstrip()
     return t
 
 
 def t_COMMENT(t):
-    r"\#[ \t]?.*"
+    r"\#[ \t]?[^\n]*"
     t.value = t.value.replace('# ', '#', 1).split('#', 1)[1].rstrip()
     return t
 
 
 def t_DATATYPES(t):
-    r"datatypes\s+xsd\s*=\s*.*"
+    r"datatypes\s+xsd\s*=\s*[^\n]*"
     t.value = t.value.split('=', 1)[1].strip()
     return t
 
@@ -183,7 +180,7 @@ def t_DATATAG(t):
 
 
 def t_DEFAULT_NS(t):
-    r"default\s+namespace\s*=\s*.*"
+    r"default\s+namespace\s*=\s*[^\n]*"
     t.value = t.value.split('=', 1)[1].strip()
     return t
 
@@ -194,9 +191,16 @@ def t_INCLUDE(t):
 t_INCLUDE.__doc__ = r'include\s*"' + NCName + '"'
 
 
+# literal ::= literalSegment ("~" literalSegment)*
+# XXX: only the first literalSegment is guarded for matching quotes
+# NB: this is what required multi-line and dot-matches-all as
+#     triple-quoted literals can contain newlines
 def t_LITERAL(t):
-    r'".+?"(?:\s*[~]\s*".+?")*'
-    t.value = ' '.join(i.strip(' \n"') for i in t.value.split('~'))
+    r'''(?msx)(?P<start>(?P<start1>["'])(?:(?P=start1){2})?).*?(?P=start)
+        (?:\s*[~]\s*(?:['"]{1,3}).*?(?:['"]{1,3}))*'''
+    #r'".+?"(?:\s*[~]\s*".+?")*'
+    #r'''(["'])(\1{2})?.*?\1\2(?:\s*[~]\s*\1\2.?*\1\2)*'''
+    t.value = ' '.join(i.rstrip("\n").strip(' "') for i in t.value.split('~'))
     return t
 
 
@@ -208,13 +212,13 @@ t_NAME.__doc__ = r"\\[.]" + NCName
 
 
 def t_NS(t):
-    r"namespace\s+.*"
+    r"namespace\s+[^\n]*"
     t.value = t.value.split(None, 1)[1]
     return t
 
 
 def t_PATTERN(t):
-    r'{\s*pattern\s*=\s*".*"\s*}'
+    r'{\s*pattern\s*=\s*"[^\n]*"\s*}'
     t.value = t.value[:-1].split('=', 1)[1].strip()[1:-1]
     return t
 
diff --git a/rnctree.py b/rnctree.py
index 90d935a..d0eee84 100755
--- a/rnctree.py
+++ b/rnctree.py
@@ -131,6 +131,7 @@ class Node(object):
         write = out.append
         if isinstance(self.value, str):
             if self.type == COMMENT:
+            #if self.value:
                 write('  ' * (1 + indent) + self.value)
         else:
             for node in self.value:
@@ -331,6 +332,7 @@ def match_pairs(nodes):
 
     Other effects:
         - merge comments/annotations
+        - remove VSPACEs
     """
     newnodes = []
     i = 0
@@ -359,6 +361,11 @@ def match_pairs(nodes):
         else:
             newnodes.append(node)
             i += 1
+
+        # remove VSPACEs (already added to newnodes to prevent comments merge)
+        if len(newnodes) > 1 and newnodes[-2].type == VSPACE:
+            newnodes = newnodes[:-2] + [newnodes.pop()]
+
         if i >= len(nodes):
             break
         if nodes[i].type in (ANY, SOME, MAYBE):
@@ -547,9 +554,12 @@ def nest_defines(nodes):
             else:
                 node.value = grp.value[:]
             # when _nest_annotations returned *not* due to reaching DEFINE,
-            # but trailing comments are tolerated
-            if i + 1 > len(nodes) or nodes[i + 1].type not in (DEFINE, COMMENT):
+            # but trailing comments are tolerated (already proceeded -> skip)
+            if i >= len(nodes) or nodes[i + 1].type not in (DEFINE, COMMENT):
                 break
+            elif nodes[i + 1].type != COMMENT:
+                for c in mapping['COMMENT']:
+                    newnodes.append(c)
         elif node.type == ELEM:
             # top-level element
             _intersperse(Node(GROUP, [node]))