generate XML schema docs from XML schemas themselves

1 files changed, 108 insertions, 19 deletions

diff --git a/schemas/info.xsd b/schemas/info.xsd
index 83a8173d2..24538ffe3 100644
--- a/schemas/info.xsd
+++ b/schemas/info.xsd
@@ -1,8 +1,7 @@
 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xml:lang="en">
-
   <xsd:annotation>
     <xsd:documentation>
-      info.xml schema for bcfg2
+      ``info.xml`` schema for Bcfg2
     </xsd:documentation>
   </xsd:annotation>
 
@@ -10,39 +9,129 @@
   <xsd:include schemaLocation="types.xsd"/>
 
   <xsd:complexType name='InfoType'>
+    <xsd:annotation>
+      <xsd:documentation>
+        The Info tag specifies metadata (ownership, permissions, etc.)
+        for entries that are generated by various plugins.
+      </xsd:documentation>
+    </xsd:annotation>
     <xsd:choice minOccurs='0' maxOccurs='unbounded'>
       <xsd:element name='ACL' type='ACLType'/>
     </xsd:choice>
-    <xsd:attribute name='encoding' type='xsd:string'/>
-    <xsd:attribute name='group' type='xsd:string'/>
-    <xsd:attribute name='important' type='xsd:string'/>
-    <xsd:attribute name='owner' type='xsd:string'/>
-    <xsd:attribute name='mode' type='xsd:string'/>
-    <xsd:attribute name='secontext' type='xsd:string'/>
-    <xsd:attribute name='paranoid' type='xsd:boolean'/>
-    <xsd:attribute name='sensitive' type='xsd:boolean'/>
+    <xsd:attribute name='encoding' type='xsd:token' default='ascii'>
+      <xsd:annotation>
+        <xsd:documentation>
+          Encoding of the file for tranfer to the client.  Use
+          ``base64`` for binary files.
+        </xsd:documentation>
+      </xsd:annotation>
+    </xsd:attribute>
+    <xsd:attribute name='group' type='xsd:token' default="root">
+      <xsd:annotation>
+        <xsd:documentation>
+          Sets group of the file.
+        </xsd:documentation>
+      </xsd:annotation>
+    </xsd:attribute>
+    <xsd:attribute name='important' type='xsd:boolean' default="false">
+      <xsd:annotation>
+        <xsd:documentation>
+          Important entries are installed first during client
+          execution.
+        </xsd:documentation>
+      </xsd:annotation>
+    </xsd:attribute>
+    <xsd:attribute name='owner' type='xsd:token' default="root">
+      <xsd:annotation>
+        <xsd:documentation>
+          Sets owner of the file.
+        </xsd:documentation>
+      </xsd:annotation>
+    </xsd:attribute>
+    <xsd:attribute name='mode' type='xsd:string' default="0644">
+      <xsd:annotation>
+        <xsd:documentation>
+          Sets the mode of the file from the octal value given.
+        </xsd:documentation>
+      </xsd:annotation>
+    </xsd:attribute>
+    <xsd:attribute name='secontext' type='xsd:token' default="__default__">
+      <xsd:annotation>
+        <xsd:documentation>
+          Sets the SELinux context of the file, or sets to the default
+          context for that path set by policy if set to the special
+          value ``__default__``.
+        </xsd:documentation>
+      </xsd:annotation>
+    </xsd:attribute>
+    <xsd:attribute name='paranoid' type='xsd:boolean' default='true'>
+      <xsd:annotation>
+        <xsd:documentation>
+          If true, files that are replaced will be backed up first.
+        </xsd:documentation>
+      </xsd:annotation>
+    </xsd:attribute>
+    <xsd:attribute name='sensitive' type='xsd:boolean' default="false">
+      <xsd:annotation>
+        <xsd:documentation>
+          The contents of sensitive entries aren't included in reports.
+        </xsd:documentation>
+      </xsd:annotation>
+    </xsd:attribute>
   </xsd:complexType>
 
-  <xsd:complexType name='GroupType'>
+  <xsd:complexType name='InfoGroupType'>
+    <xsd:annotation>
+      <xsd:documentation>
+        An **InfoGroupType** is a ``info.xml`` tag used to provide
+        logic.  Child entries of such a tag only apply to machines
+        that match the condition specified -- membership in a group, a
+        matching client name, or a matching path for the file being
+        generated.  :xml:attribute:`InfoGroupType:negate` can be set
+        to negate the sense of the match.
+      </xsd:documentation>
+    </xsd:annotation>
     <xsd:choice minOccurs='1' maxOccurs='1'>
       <xsd:element name='Info' type='InfoType'/>
-      <xsd:element name='Group' type='GroupType' minOccurs='0'
+      <xsd:element name='Group' type='InfoGroupType' minOccurs='0'
                    maxOccurs='unbounded'/>
-      <xsd:element name='Client' type='GroupType' minOccurs='0'
+      <xsd:element name='Client' type='InfoGroupType' minOccurs='0'
                    maxOccurs='unbounded'/>
-      <xsd:element name='Path' type='GroupType' minOccurs='0'
+      <xsd:element name='Path' type='InfoGroupType' minOccurs='0'
                    maxOccurs='unbounded'/>
     </xsd:choice>
-    <xsd:attribute type='xsd:string' name='name' use='required'/>
-    <xsd:attribute type='xsd:boolean' name='negate' />
+    <xsd:attribute type='xsd:string' name='name' use='required'>
+      <xsd:annotation>
+        <xsd:documentation>
+          The name of the client or group, or the full path to match
+          on.  Child entries will only apply to this client or group
+          (unless :xml:attribute:`InfoGroupType:negate` is set).
+        </xsd:documentation>
+      </xsd:annotation>
+    </xsd:attribute>
+    <xsd:attribute type='xsd:boolean' name='negate' default="false">
+      <xsd:annotation>
+        <xsd:documentation>
+          Negate the sense of the match, so that child entries only
+          apply to a client if it is not a member of the given group,
+          does not have the given client name, or the path names do
+          not match.
+        </xsd:documentation>
+      </xsd:annotation>
+    </xsd:attribute>
   </xsd:complexType>
 
   <xsd:element name='FileInfo'>
+    <xsd:annotation>
+      <xsd:documentation>
+        Top-level tag for ``info.xml``.
+      </xsd:documentation>
+    </xsd:annotation>
     <xsd:complexType>
       <xsd:choice minOccurs='0' maxOccurs='unbounded'>
-        <xsd:element name='Group' type='GroupType'/>
-        <xsd:element name='Client' type='GroupType'/>
-        <xsd:element name='Path' type='GroupType'/>
+        <xsd:element name='Group' type='InfoGroupType'/>
+        <xsd:element name='Client' type='InfoGroupType'/>
+        <xsd:element name='Path' type='InfoGroupType'/>
         <xsd:element name='Info' type='InfoType'/>
       </xsd:choice>
     </xsd:complexType>