Update doc development overview [ci skip]

Includes updates to the diagram that shows the doc flow
(although it could still be improved. I'm not a diagramming
expert so settling for what I could accomplish)

Signed-off-by: Mats Wichmann <mats@linux.com>

3 files changed, 75 insertions, 55 deletions

diff --git a/doc/images/overview.graphml b/doc/images/overview.graphml
index 74f80d7..63ecd36 100644
--- a/doc/images/overview.graphml
+++ b/doc/images/overview.graphml
@@ -1,39 +1,39 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:y="http://www.yworks.com/xml/graphml" xmlns:yed="http://www.yworks.com/xml/yed/3" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://www.yworks.com/xml/schema/graphml/1.1/ygraphml.xsd">
-  <!--Created by yFiles for Java 2.9-->
-  <key for="graphml" id="d0" yfiles.type="resources"/>
+<graphml xmlns="http://graphml.graphdrawing.org/xmlns" xmlns:java="http://www.yworks.com/xml/yfiles-common/1.0/java" xmlns:sys="http://www.yworks.com/xml/yfiles-common/markup/primitives/2.0" xmlns:x="http://www.yworks.com/xml/yfiles-common/markup/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:y="http://www.yworks.com/xml/graphml" xmlns:yed="http://www.yworks.com/xml/yed/3" xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns http://www.yworks.com/xml/schema/graphml/1.1/ygraphml.xsd">
+  <!--Created by yEd 3.18.0.2-->
+  <key attr.name="Beschreibung" attr.type="string" for="graph" id="d0"/>
   <key for="port" id="d1" yfiles.type="portgraphics"/>
   <key for="port" id="d2" yfiles.type="portgeometry"/>
   <key for="port" id="d3" yfiles.type="portuserdata"/>
   <key attr.name="url" attr.type="string" for="node" id="d4"/>
   <key attr.name="description" attr.type="string" for="node" id="d5"/>
   <key for="node" id="d6" yfiles.type="nodegraphics"/>
-  <key attr.name="Beschreibung" attr.type="string" for="graph" id="d7"/>
+  <key for="graphml" id="d7" yfiles.type="resources"/>
   <key attr.name="url" attr.type="string" for="edge" id="d8"/>
   <key attr.name="description" attr.type="string" for="edge" id="d9"/>
   <key for="edge" id="d10" yfiles.type="edgegraphics"/>
   <graph edgedefault="directed" id="G">
-    <data key="d7"/>
+    <data key="d0"/>
     <node id="n0" yfiles.foldertype="group">
       <data key="d4"/>
       <data key="d6">
         <y:ProxyAutoBoundsNode>
           <y:Realizers active="0">
             <y:GroupNode>
-              <y:Geometry height="269.01233212809916" width="204.95703125" x="100.521484375" y="53.0390625"/>
+              <y:Geometry height="269.01233212809916" width="212.95703125" x="96.521484375" y="53.0390625"/>
               <y:Fill color="#F5F5F5" transparent="false"/>
               <y:BorderStyle color="#000000" type="dashed" width="1.0"/>
-              <y:NodeLabel alignment="right" autoSizePolicy="node_width" backgroundColor="#EBEBEB" borderDistance="0.0" fontFamily="Dialog" fontSize="15" fontStyle="plain" hasLineColor="false" height="21.4609375" modelName="internal" modelPosition="t" textColor="#000000" visible="true" width="204.95703125" x="0.0" y="0.0">User's view</y:NodeLabel>
+              <y:NodeLabel alignment="right" autoSizePolicy="node_width" backgroundColor="#EBEBEB" borderDistance="0.0" fontFamily="Dialog" fontSize="15" fontStyle="plain" hasLineColor="false" height="21.4609375" horizontalTextPosition="center" iconTextGap="4" modelName="internal" modelPosition="t" textColor="#000000" verticalTextPosition="bottom" visible="true" width="212.95703125" x="0.0" y="0.0">User's view</y:NodeLabel>
               <y:Shape type="roundrectangle"/>
               <y:State closed="false" closedHeight="50.0" closedWidth="50.0" innerGraphDisplayEnabled="false"/>
               <y:Insets bottom="15" bottomF="15.0" left="15" leftF="15.0" right="15" rightF="15.0" top="15" topF="15.0"/>
-              <y:BorderInsets bottom="0" bottomF="0.0" left="0" leftF="0.0" right="0" rightF="0.0" top="3" topF="3.0"/>
+              <y:BorderInsets bottom="0" bottomF="0.0" left="6" leftF="5.916015625" right="0" rightF="0.0" top="3" topF="3.0"/>
             </y:GroupNode>
             <y:GroupNode>
               <y:Geometry height="50.0" width="50.0" x="0.0" y="60.0"/>
               <y:Fill color="#F5F5F5" transparent="false"/>
               <y:BorderStyle color="#000000" type="dashed" width="1.0"/>
-              <y:NodeLabel alignment="right" autoSizePolicy="node_width" backgroundColor="#EBEBEB" borderDistance="0.0" fontFamily="Dialog" fontSize="15" fontStyle="plain" hasLineColor="false" height="21.4609375" modelName="internal" modelPosition="t" textColor="#000000" visible="true" width="65.201171875" x="-7.6005859375" y="0.0">Folder 1</y:NodeLabel>
+              <y:NodeLabel alignment="right" autoSizePolicy="node_width" backgroundColor="#EBEBEB" borderDistance="0.0" fontFamily="Dialog" fontSize="15" fontStyle="plain" hasLineColor="false" height="21.4609375" horizontalTextPosition="center" iconTextGap="4" modelName="internal" modelPosition="t" textColor="#000000" verticalTextPosition="bottom" visible="true" width="65.201171875" x="-7.6005859375" y="0.0">Folder 1</y:NodeLabel>
               <y:Shape type="roundrectangle"/>
               <y:State closed="true" closedHeight="50.0" closedWidth="50.0" innerGraphDisplayEnabled="false"/>
               <y:Insets bottom="5" bottomF="5.0" left="5" leftF="5.0" right="5" rightF="5.0" top="5" topF="5.0"/>
@@ -46,10 +46,11 @@
         <node id="n0::n0">
           <data key="d6">
             <y:ShapeNode>
-              <y:Geometry height="30.0" width="174.95703125" x="115.521484375" y="185.05694731404958"/>
+              <y:Geometry height="41.9375" width="177.041015625" x="117.4375" y="173.11944731404958"/>
               <y:Fill color="#FFCC00" transparent="false"/>
               <y:BorderStyle color="#000000" type="line" width="1.0"/>
-              <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="164.95703125" x="5.0" y="6.015625">XML files (src/user/man/...)<y:LabelModel>
+              <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="31.9375" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="141.26171875" x="17.8896484375" y="5.0">XML files (user guide,
+manpage, source tree)<y:LabelModel>
                   <y:SmartNodeLabelModel distance="4.0"/>
                 </y:LabelModel>
                 <y:ModelParameter>
@@ -63,10 +64,10 @@
         <node id="n0::n1">
           <data key="d6">
             <y:ShapeNode>
-              <y:Geometry height="41.9375" width="158.357421875" x="123.8212890625" y="265.11389462809916"/>
+              <y:Geometry height="41.9375" width="173.041015625" x="117.4375" y="265.11389462809916"/>
               <y:Fill color="#FFCC00" transparent="false"/>
               <y:BorderStyle color="#000000" type="line" width="1.0"/>
-              <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="92.154296875" x="33.1015625" y="11.984375">XML validation<y:LabelModel>
+              <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="92.154296875" x="40.443359375" y="11.984375">XML validation<y:LabelModel>
                   <y:SmartNodeLabelModel distance="4.0"/>
                 </y:LabelModel>
                 <y:ModelParameter>
@@ -83,7 +84,8 @@
               <y:Geometry height="52.0" width="51.154296875" x="177.4228515625" y="92.5"/>
               <y:Fill color="#CCCCFF" transparent="false"/>
               <y:BorderStyle color="#000000" type="line" width="1.0"/>
-              <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="41.154296875" x="42.63675428695848" y="20.570887005532427">Writer<y:LabelModel>
+              <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="31.9375" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="65.03125" x="37.69503542507212" y="6.602137005532427">Writer
+                <y:LabelModel>
                   <y:SmartNodeLabelModel distance="4.0"/>
                 </y:LabelModel>
                 <y:ModelParameter>
@@ -102,11 +104,10 @@
     <node id="n1">
       <data key="d6">
         <y:ShapeNode>
-          <y:Geometry height="41.9375" width="225.341796875" x="90.3291015625" y="339.03125"/>
+          <y:Geometry height="41.9375" width="171.125" x="117.4375" y="339.03125"/>
           <y:Fill color="#FFCC00" transparent="false"/>
           <y:BorderStyle color="#000000" type="line" width="1.0"/>
-          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="121.650390625" x="51.845703125" y="11.984375">Creating entity lists
-<y:LabelModel>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="121.650390625" x="24.7373046875" y="11.984375">Creating entity lists<y:LabelModel>
               <y:SmartNodeLabelModel distance="4.0"/>
             </y:LabelModel>
             <y:ModelParameter>
@@ -120,11 +121,11 @@
     <node id="n2">
       <data key="d6">
         <y:ShapeNode>
-          <y:Geometry height="41.9375" width="134.7734375" x="382.61328125" y="339.03125"/>
+          <y:Geometry height="41.9375" width="163.35546875" x="368.322265625" y="339.03125"/>
           <y:Fill color="#FFCC00" transparent="false"/>
           <y:BorderStyle color="#000000" type="line" width="1.0"/>
-          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="31.9375" modelName="custom" textColor="#000000" visible="true" width="124.7734375" x="5.0" y="5.0">Check that example
-names are unique<y:LabelModel>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="31.9375" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="132.40234375" x="15.4765625" y="5.0"> Check that example 
+ names are unique<y:LabelModel>
               <y:SmartNodeLabelModel distance="4.0"/>
             </y:LabelModel>
             <y:ModelParameter>
@@ -141,7 +142,7 @@ names are unique<y:LabelModel>
           <y:Geometry height="41.9375" width="163.35546875" x="368.322265625" y="410.96875"/>
           <y:Fill color="#FFCC00" transparent="false"/>
           <y:BorderStyle color="#000000" type="line" width="1.0"/>
-          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="149.458984375" x="6.9482421875" y="11.984375">Create example outputs<y:LabelModel>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="149.458984375" x="6.9482421875" y="11.984375">Create example outputs<y:LabelModel>
               <y:SmartNodeLabelModel distance="4.0"/>
             </y:LabelModel>
             <y:ModelParameter>
@@ -158,8 +159,8 @@ names are unique<y:LabelModel>
           <y:Geometry height="41.9375" width="171.125" x="117.4375" y="410.96875"/>
           <y:Fill color="#FFCC00" transparent="false"/>
           <y:BorderStyle color="#000000" type="line" width="1.0"/>
-          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="31.9375" modelName="custom" textColor="#000000" visible="true" width="161.125" x="5.0" y="5.0">Resolve XIncludes for text
-and examples<y:LabelModel>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="31.9375" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="137.23046875" x="16.947265625" y="5.0">Resolve XIncludes for 
+ text and examples<y:LabelModel>
               <y:SmartNodeLabelModel distance="4.0"/>
             </y:LabelModel>
             <y:ModelParameter>
@@ -173,10 +174,10 @@ and examples<y:LabelModel>
     <node id="n5">
       <data key="d6">
         <y:ShapeNode>
-          <y:Geometry height="30.0" width="155.29296875" x="125.353515625" y="497.09375"/>
+          <y:Geometry height="30.0" width="173.041015625" x="117.4375" y="497.09375"/>
           <y:Fill color="#FFCC00" transparent="false"/>
           <y:BorderStyle color="#000000" type="line" width="1.0"/>
-          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="custom" textColor="#000000" visible="true" width="145.29296875" x="5.0" y="6.015625">Create HTML, PDF, Man<y:LabelModel>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="145.29296875" x="13.8740234375" y="6.015625">Create HTML, PDF, Man<y:LabelModel>
               <y:SmartNodeLabelModel distance="4.0"/>
             </y:LabelModel>
             <y:ModelParameter>
@@ -190,10 +191,10 @@ and examples<y:LabelModel>
     <node id="n6">
       <data key="d6">
         <y:ShapeNode>
-          <y:Geometry height="41.9375" width="144.6171875" x="130.69140625" y="563.21875"/>
+          <y:Geometry height="41.9375" width="173.041015625" x="117.4375" y="563.21875"/>
           <y:Fill color="#FFCC00" transparent="false"/>
           <y:BorderStyle color="#000000" type="line" width="1.0"/>
-          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="31.9375" modelName="custom" textColor="#000000" visible="true" width="134.6171875" x="5.0" y="5.0">Install in proper place
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="31.9375" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="134.6171875" x="19.2119140625" y="5.0">Install in proper place
 for packaging<y:LabelModel>
               <y:SmartNodeLabelModel distance="4.0"/>
             </y:LabelModel>
@@ -208,11 +209,11 @@ for packaging<y:LabelModel>
     <node id="n7">
       <data key="d6">
         <y:ShapeNode>
-          <y:Geometry height="41.9375" width="102.306640625" x="398.8466796875" y="491.125"/>
+          <y:Geometry height="41.9375" width="163.35546875" x="368.322265625" y="491.125"/>
           <y:Fill color="#FFCC00" transparent="false"/>
           <y:BorderStyle color="#000000" type="line" width="1.0"/>
-          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="31.9375" modelName="custom" textColor="#000000" visible="true" width="92.306640625" x="5.0" y="5.0">Create API doc
-(Epydoc)<y:LabelModel>
+          <y:NodeLabel alignment="center" autoSizePolicy="content" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="31.9375" horizontalTextPosition="center" iconTextGap="4" modelName="custom" textColor="#000000" verticalTextPosition="bottom" visible="true" width="92.306640625" x="35.5244140625" y="5.0">Create API doc
+(Sphinx)<y:LabelModel>
               <y:SmartNodeLabelModel distance="4.0"/>
             </y:LabelModel>
             <y:ModelParameter>
@@ -229,7 +230,8 @@ for packaging<y:LabelModel>
           <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
           <y:LineStyle color="#000000" type="line" width="1.0"/>
           <y:Arrows source="none" target="standard"/>
-          <y:EdgeLabel alignment="center" distance="2.0" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="six_pos" modelPosition="tail" preferredPlacement="anywhere" ratio="0.5" textColor="#000000" visible="true" width="83.318359375" x="2.0" y="16.04410017029312">get validated</y:EdgeLabel>
+          <y:EdgeLabel alignment="center" distance="2.0" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" horizontalTextPosition="center" iconTextGap="4" modelName="six_pos" modelPosition="tail" preferredPlacement="anywhere" ratio="0.5" textColor="#000000" verticalTextPosition="bottom" visible="true" width="83.318359375" x="1.6511958708837824" y="16.04410017029312">get validated<y:PreferredPlacementDescriptor angle="0.0" angleOffsetOnRightSide="0" angleReference="absolute" angleRotationOnRightSide="co" distance="-1.0" frozen="true" placement="anywhere" side="anywhere" sideReference="relative_to_edge_flow"/>
+          </y:EdgeLabel>
           <y:BendStyle smoothed="false"/>
         </y:PolyLineEdge>
       </data>
@@ -267,7 +269,9 @@ for packaging<y:LabelModel>
     <edge id="e3" source="n2" target="n3">
       <data key="d10">
         <y:PolyLineEdge>
-          <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
+          <y:Path sx="0.0" sy="0.0" tx="0.0" ty="-12.9375">
+            <y:Point x="450.0" y="405.0"/>
+          </y:Path>
           <y:LineStyle color="#000000" type="line" width="1.0"/>
           <y:Arrows source="none" target="standard"/>
           <y:BendStyle smoothed="false"/>
@@ -300,7 +304,8 @@ for packaging<y:LabelModel>
           <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
           <y:LineStyle color="#000000" type="line" width="1.0"/>
           <y:Arrows source="none" target="standard"/>
-          <y:EdgeLabel alignment="center" distance="2.0" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="six_pos" modelPosition="tail" preferredPlacement="anywhere" ratio="0.5" textColor="#000000" visible="true" width="132.970703125" x="2.0" y="13.109375">switching to Docbook</y:EdgeLabel>
+          <y:EdgeLabel alignment="center" distance="2.0" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" horizontalTextPosition="center" iconTextGap="4" modelName="six_pos" modelPosition="tail" preferredPlacement="anywhere" ratio="0.5" textColor="#000000" verticalTextPosition="bottom" visible="true" width="132.970703125" x="2.371441114994525" y="13.109375">switching to Docbook<y:PreferredPlacementDescriptor angle="0.0" angleOffsetOnRightSide="0" angleReference="absolute" angleRotationOnRightSide="co" distance="-1.0" frozen="true" placement="anywhere" side="anywhere" sideReference="relative_to_edge_flow"/>
+          </y:EdgeLabel>
           <y:BendStyle smoothed="false"/>
         </y:PolyLineEdge>
       </data>
@@ -333,13 +338,14 @@ for packaging<y:LabelModel>
           <y:Path sx="0.0" sy="0.0" tx="0.0" ty="0.0"/>
           <y:LineStyle color="#000000" type="line" width="1.0"/>
           <y:Arrows source="none" target="standard"/>
-          <y:EdgeLabel alignment="center" distance="2.0" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" modelName="six_pos" modelPosition="tail" preferredPlacement="anywhere" ratio="0.5" textColor="#000000" visible="true" width="81.94140625" x="2.0" y="11.289856713665415">edits/creates</y:EdgeLabel>
+          <y:EdgeLabel alignment="center" distance="2.0" fontFamily="Dialog" fontSize="12" fontStyle="plain" hasBackgroundColor="false" hasLineColor="false" height="17.96875" horizontalTextPosition="center" iconTextGap="4" modelName="six_pos" modelPosition="tail" preferredPlacement="anywhere" ratio="0.5" textColor="#000000" verticalTextPosition="bottom" visible="true" width="81.94140625" x="2.910770900654086" y="5.304993432415415">edits/creates<y:PreferredPlacementDescriptor angle="0.0" angleOffsetOnRightSide="0" angleReference="absolute" angleRotationOnRightSide="co" distance="-1.0" frozen="true" placement="anywhere" side="anywhere" sideReference="relative_to_edge_flow"/>
+          </y:EdgeLabel>
           <y:BendStyle smoothed="false"/>
         </y:PolyLineEdge>
       </data>
     </edge>
   </graph>
-  <data key="d0">
+  <data key="d7">
     <y:Resources>
       <y:Resource id="1">&lt;?xml version="1.0" encoding="utf-8"?&gt;
 &lt;!-- Generator: Adobe Illustrator 15.0.2, SVG Export Plug-In . SVG Version: 6.00 Build 0)  --&gt;
diff --git a/doc/images/overview.png b/doc/images/overview.png
index f1189c9..b83e955 100644
--- a/doc/images/overview.png
+++ b/doc/images/overview.png
diff --git a/doc/overview.rst b/doc/overview.rst
index 79b407a..8a1d56a 100644
--- a/doc/overview.rst
+++ b/doc/overview.rst
@@ -6,19 +6,25 @@ SCons Documentation Toolchain
 Introduction
 ============
 
-This text tries to give an overview of the current SCons documentation
-toolchain.  As a prospective doc editor, you should be able to quickly
+This is an overview of the current SCons documentation toolchain.
+As a prospective doc editor, you should be able to quickly
 understand the basic concepts (if not, please let the project know how
 it falls short).  It is also a reference for core developers and the
 release team.
 
 .. image:: images/overview.png
 
-The diagram above roughly shows the steps that we currently need for
-creating all the MAN pages, User manuals and reference documents. You
-may think: "Geeez, that looks so complicated. Why can't they simply
-convert XML files to PDF with Docbook, or use reST?" Please be patient,
-and continue reading. Things will get a little clearer soon.
+The diagram above roughly shows the steps that we currently use.
+Note there are two separate sets of documentation maintained with
+the project code itself: the reference manual and user guide,
+which have xml source files; and the docstrings in the Python code,
+from which the API documentation is generated. Most of the time
+when we talk about "SCons Documentation" we mean the former,
+as that's what is intended for end-user consumption.
+
+If you look at the diagram, it looks a bit complicated. after
+reading this overview, it will be clear what is actually happening,
+and why we need all these steps.
 
 Our toolchain doesn't only produce HTML and PDF files that are nice
 to look at, it also performs a lot of processing under the covers. We
@@ -30,31 +36,36 @@ So let's start right at the top...
 Writer's view
 =============
 
-SCons documentation is written in Docbook (the xml variant).
-The toolchain is set up so that a writer has a restricted view of the
+SCons documentation is written in Docbook XML.
+The toolchain is set up so a writer has a restricted view of the
 whole "document processing thingy". All you should need to be concerned
 with is to edit existing text or write new sections and paragraphs.
 Sometimes even a completely new chapter has to be added. The hope
 is that you can fire up your XML editor of choice and type away.
 
-XML is easy to get wrong, so you need to case about
+XML is easy to get wrong, so you need to care about
 validating the XML files
-against our special "SCons Docbook DTD/XSD". You can run the
-special script
+against our special "SCons Docbook DTD/XSD".
+If you're not using an XML editor, validate by
 
 ::
 
     python bin/docs-validate.py
 
 
-from the top source folder to validate. If you are able to use
-an XML editor, many of the potential problems are avoided -
-the most common error is not matching tag opening and closing
+from the top source folder. If you are able to use
+an XML editor, many of the potential problems are avoided,
+as it will complain real-time.
+The most common error is not matching tag opening and closing
 (for example ``<tag>foo<tag>`` is an easy typing error to make,
 as is starting a ``<para>``, typing text, and not adding the
-closing ``</para>``). XML editors make it much harder to make
-those errors, which minor though they seem, will completely
-break the document build.
+closing ``</para>``, as is mistyping one of the two
+tag markers). XML editors make it much harder to make
+those errors, which, minor though they seem, will completely
+break the document build. Unfortunately, the validation tools
+(which rely on the capabilities of the XML parser in use)
+are not that hard to fool, so you may get errors which are
+not that easy to deciper. There isn't much we can do about that.
 
 Everything's looking okay, all validation passed? Good, then simply
 commits your new work, and create a pull request on Github. That's it!
@@ -71,6 +82,8 @@ the actual XML files. You can call
 
 from within the directory, and have the MAN pages or HTML created...even
 PDF, if you have a renderer installed (``fop``, ``xep`` or ``jw``).
+At least ``fop`` doesn't like everything the docbook/xml chain
+produces and will spew a lot of errors, which we *think* are harmless.
 
 Validation
 ==========
@@ -149,7 +162,7 @@ By calling the script
 
 you can recreate the lists of entities (``*.mod``) in the ``generated``
 folder.  At the same time, this will generate the matching ``*.gen``
-files, which list the full description of all the Builders, Tools,
+files, which hold the full descriptions of all the Builders, Tools,
 Functions and CVars for the MAN page and the User Guide's appendix.
 Thus, you want to regenerate when there's a change to
 any of those four special elements, or an added or deleted element.
@@ -217,7 +230,7 @@ For example, when documenting a Tool in
 ``SCons/Tool/newtool.xml`` using the ``<tool>`` tag,
 and noting that the tool ``<uses>`` or ``<sets>``
 certain construction variables,
-those construction variables can be documented 
+those construction variables can be documented
 right there as well using ``<cvar>`` tags.
 When processed with ``SConsDoc`` module,
 this will generate xml from the
@@ -279,6 +292,7 @@ part so that the version control system can show any unexpected
 changes in the outputs after editing the docs:
 
 ::
+
    git diff doc/generated/examples
 
 Some of the changes in example text are phony: despite best