Document reconstitution

doc/index.xml

@@ -34,6 +34,7 @@
 <ch><ti>SQL Back-end</ti><fi>sql</fi></ch>
 <ch><ti>Schema of the Generated Database</ti><fi>dbschema</fi></ch>
 <ch><ti>Examples of SQL Queries</ti><fi>qeg</fi></ch>
+<ch><ti>Source Code Reconstitution</ti><fi>reconst</fi></ch>
 <ch><ti>Details of the Collected Metrics</ti><fi>metrics</fi></ch>
 <ch><ti>Shortcomings</ti><fi>short</fi></ch>
 <ch><ti>Error Messages</ti><fi>error</fi></ch>

doc/reconst.xml

@@ -0,0 +1,46 @@
+<?xml version="1.0" ?>
+<notes>
+<p>
+The data stored in the database allow the exact reconstitution
+of the original source code.
+All that is required is to run an appropriate query and filter
+its results to recreate the original line breaks from irs output.
+Elements modified in the database, such as identifier names or
+comment contents, will be correctly mirrored in the generated output.
+</p>
+<p>
+	The following is the required SQL query for the SQLite database
+	to reconstitute the contents of the file with
+	file identifier (<code>fid</code>) 4.
+</p>
+<!-- sql01-index.sql -->
+<fmtcode ext="SQL">
+.print "Starting dump"
+
+SELECT s FROM (
+  SELECT name AS s, foffset
+    FROM ids
+    INNER JOIN tokens ON ids.eid = tokens.eid
+    WHERE fid = 4
+  UNION SELECT code AS s, foffset FROM rest WHERE fid = 4
+  UNION SELECT comment AS s, foffset FROM comments WHERE fid = 4
+  UNION SELECT string AS s, foffset FROM strings WHERE fid = 4
+  )
+ORDER BY foffset;
+</fmtcode>
+<p>
+The query's output needs to be pipped to the following commands
+to adjust it as needed.
+</p>
+<fmtcode ext="sh">
+# Remove header and footer lines
+sed -e '1,/^Starting dump/d;/^[0-9][0-9]* rows/d' |
+
+# Remove line breaks added by the database engine
+tr -d '\n\r' |
+
+# Add line breaks appearing in the database output as Unicode escapes
+perl -pe 's/\\u0000d\\u0000a/\n/g;s/\\u0000a/\n/g' >test/chunk/$NAME
+</fmtcode>
+<p />
+</notes>