docs: add new user guide
This has also been reviewed to death on evolve-testers. There are
still a couple of short sections to write (clearly marked "TODO"), and
one example to add. But (if I may be so bold) this is a gigantic
improvement over the current docs, so it really should get merged.
Incidentally, the figures are all SVG files created with Inkscape.
They're not perfect, but they're pretty nice. Anyone who knows a
better way to create technical diagrams is welcome to contribute.
One wart: there's a test script that accompanies the document and
largely duplicates it, but I haven't unified them. I've been
concentrating on writing the best possible content, not on fiddling
with tools. I suspect that unifying them will be non-trivial, but
definitely worth doing.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="250"
height="150"
id="svg10360"
version="1.1"
inkscape:version="0.48.4 r9939"
sodipodi:docname="figure-ug09.svg">
<defs
id="defs10362">
<marker
inkscape:stockid="Arrow2Mend"
orient="auto"
refY="0"
refX="0"
id="Arrow2Mend-2"
style="overflow:visible">
<path
id="path5316-7"
style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
transform="scale(-0.6,-0.6)"
inkscape:connector-curvature="0" />
</marker>
<marker
inkscape:stockid="Arrow2Mend"
orient="auto"
refY="0"
refX="0"
id="marker10584"
style="overflow:visible">
<path
id="path10586"
style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round"
d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
transform="scale(-0.6,-0.6)"
inkscape:connector-curvature="0" />
</marker>
<marker
inkscape:stockid="DotM"
orient="auto"
refY="0"
refX="0"
id="DotM"
style="overflow:visible">
<path
id="path4193"
d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z"
style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
transform="matrix(0.4,0,0,0.4,2.96,0.4)"
inkscape:connector-curvature="0" />
</marker>
</defs>
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="2.180467"
inkscape:cx="119.78971"
inkscape:cy="57.203827"
inkscape:document-units="px"
inkscape:current-layer="layer1"
showgrid="false"
fit-margin-top="0"
fit-margin-left="0"
fit-margin-right="0"
fit-margin-bottom="0"
inkscape:window-width="866"
inkscape:window-height="800"
inkscape:window-x="548"
inkscape:window-y="176"
inkscape:window-maximized="0" />
<metadata
id="metadata10365">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title></dc:title>
</cc:Work>
</rdf:RDF>
</metadata>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(-52.986766,123.22995)">
<text
xml:space="preserve"
style="font-size:12px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Monospace;-inkscape-font-specification:Monospace"
x="132.17838"
y="-88.939552"
id="text5217-8-0"
sodipodi:linespacing="125%"
transform="scale(0.9999979,1.0000021)"><tspan
sodipodi:role="line"
id="tspan8594"
x="132.17838"
y="-88.939552">hg evolve --all</tspan></text>
<g
id="g6372"
transform="translate(82.830913,-142.84994)">
<path
inkscape:connector-curvature="0"
id="path8598"
d="m 36.655932,74.035228 3.649333,6.320665 3.711171,-6.427764"
style="fill:none;stroke:#808080;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<g
transform="matrix(1,0,0,1.5998137,5.836184,-16.712267)"
id="g3821">
<path
style="fill:none;stroke:#808080;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
d="M 35.5,23.60911 35.5,59.5"
id="path8466-5"
inkscape:connector-curvature="0" />
<path
style="fill:none;stroke:#808080;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
d="M 33.5,23.60911 33.5,59.5"
id="path8466-4-7"
inkscape:connector-curvature="0" />
</g>
</g>
<g
transform="matrix(1.0000032,0,0,0.99999991,52.986844,-844.35614)"
id="g8678-6">
<rect
y="793.80884"
x="0.4999997"
height="18.053268"
width="21.481806"
id="rect2987-4-9"
style="fill:none;stroke:#000000;stroke-width:0.9999994;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
<text
sodipodi:linespacing="125%"
id="text5217-8-32"
y="807.20361"
x="3.4977415"
style="font-size:11.99999332px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
xml:space="preserve"><tspan
id="tspan6156-8"
sodipodi:role="line"
x="3.4977415"
y="807.20361">18</tspan></text>
</g>
<g
id="g11168"
transform="translate(0,112)">
<rect
y="-162.54732"
x="113.48685"
height="18.053268"
width="21.481808"
id="rect2987-4-02-6"
style="fill:none;stroke:#000000;stroke-width:0.99999946;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:0.99999946, 3.99999783;stroke-dashoffset:0" />
<text
sodipodi:linespacing="125%"
id="text5217-8-72-1"
y="-149.15291"
x="116.53148"
style="font-size:11.99999428px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
xml:space="preserve"><tspan
id="tspan6156-9-8"
sodipodi:role="line"
x="116.53148"
y="-149.15291">19</tspan></text>
</g>
<g
id="g11163"
transform="translate(0,112)">
<rect
y="-162.5473"
x="173.48705"
height="18.053268"
width="21.481808"
id="rect2987-4-026-7"
style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:1, 4;stroke-dashoffset:0" />
<text
sodipodi:linespacing="125%"
id="text5217-8-3-8"
y="-149.15244"
x="176.41162"
style="font-size:11.99999428px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
xml:space="preserve"><tspan
id="tspan6156-0-9"
sodipodi:role="line"
x="176.41162"
y="-149.15244">20</tspan></text>
</g>
<path
style="fill:none;stroke:#000000;stroke-width:1.00000155px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Mend-2);display:inline"
d="m 74.96872,-41.52073 38.51813,3.7e-5"
id="path3178-9"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-end="#g11168"
inkscape:connection-end-point="d4"
inkscape:connection-start="#g8678-6"
inkscape:connection-start-point="d4" />
<path
style="fill:none;stroke:#000000;stroke-width:1.00000155px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Mend-2);display:inline"
d="m 134.96865,-41.520681 38.5184,1e-5"
id="path3180-1"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-start="#g11168"
inkscape:connection-start-point="d4"
inkscape:connection-end="#g11163"
inkscape:connection-end-point="d4" />
<g
transform="matrix(1.0000032,0,0,0.99999991,172.98684,-795.29459)"
id="g8678-6-4">
<rect
y="793.80884"
x="0.4999997"
height="18.053268"
width="21.481806"
id="rect2987-4-9-5"
style="fill:none;stroke:#000000;stroke-width:0.9999994;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" />
<text
sodipodi:linespacing="125%"
id="text5217-8-32-6"
y="807.20361"
x="3.4977415"
style="font-size:11.99999332px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
xml:space="preserve"><tspan
id="tspan6156-8-9"
sodipodi:role="line"
x="3.4977415"
y="807.20361">21</tspan></text>
</g>
<path
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#marker10584)"
d="M 74.96872,-37.129348 173.48684,3.1494178"
id="path11202"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-start="#g8678-6"
inkscape:connection-start-point="d4"
inkscape:connection-end="#g8678-6-4"
inkscape:connection-end-point="d4" />
<path
style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:1, 3;stroke-dashoffset:0;marker-start:url(#DotM);display:inline"
d="m 184.22792,-32.494034 -1.1e-4,31.0082104"
id="path4123-2"
inkscape:connector-type="polyline"
inkscape:connector-curvature="0"
inkscape:connection-start="#g11163"
inkscape:connection-start-point="d4"
inkscape:connection-end="#g8678-6-4"
inkscape:connection-end-point="d4" />
<text
xml:space="preserve"
style="font-size:10px;font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans Italic"
x="188.27898"
y="-68.730186"
id="text11674"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan11676"
x="188.27898"
y="-68.730186">obsolete, hidden</tspan></text>
<text
xml:space="preserve"
style="font-size:10px;font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans Italic"
x="229.09592"
y="4.1899796"
id="text11678"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan11680"
x="229.09592"
y="4.1899796">successor,</tspan><tspan
sodipodi:role="line"
x="229.09592"
y="16.68998"
id="tspan11682">working dir</tspan></text>
<path
style="color:#000000;fill:none;stroke:#707070;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker:none;marker-end:url(#marker10584);visibility:visible;display:inline;overflow:visible;enable-background:accumulate"
d="m 224.96835,6.48307 c -14.81489,-0.42162 -8.84647,9.26545 -25.22395,4.58617"
id="path11688"
inkscape:connector-curvature="0" />
<path
style="color:#000000;fill:none;stroke:#707070;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker:none;marker-end:url(#marker10584);visibility:visible;display:inline;overflow:visible;enable-background:accumulate"
d="m 230.01314,-64.60262 c -9.90102,12.73442 -31.46298,0.0328 -40.81693,11.46543"
id="path12074"
inkscape:connector-curvature="0" />
<path
style="color:#000000;fill:none;stroke:#707070;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker:none;marker-end:url(#marker10584);visibility:visible;display:inline;overflow:visible;enable-background:accumulate"
d="m 225.88558,-65.97848 c -32.80764,7.84904 -73.26593,-8.64954 -95.3924,11.46544"
id="path12076"
inkscape:connector-curvature="0" />
</g>
</svg>
