Document railroad diagram generation.

h2/src/docsrc/html/build.html

@@ -32,6 +32,8 @@ Build
     Providing Patches</a><br />
 <a href="#automated">
     Automated Build</a><br />
+<a href="#railroad">
+    Generating Railroad Diagrams</a><br />
 
 <h2 id="portability">Portability</h2>
 <p>
@@ -220,9 +222,23 @@ The last results are available here:
 <ul><li><a href="http://h2database.com/html/testOutput.html">Test Output</a>
 </li><li><a href="http://h2database.com/coverage/overview.html">Code Coverage Summary</a>
 </li><li><a href="http://h2database.com/coverage/coverage.zip">Code Coverage Details (download, 1.3 MB)</a>
-</li><li><a href="http://www.h2database.com/automated/newsfeed.xml">Build Newsfeed</a>
+</li><li><a href="http://www.h2database.com/automated/news.xml">Build Newsfeed</a>
 </li><li><a href="http://www.h2database.com/automated/h2-latest.jar">Latest Jar File (download, 1 MB)</a>
 </li></ul>
 
+<h2 id="railroad">Generating Railroad Diagrams</h2>
+<p>
+The railroad diagrams are HTML, formatted as nested tables.
+The diagrams are generated as follows:
+</p>
+<ul><li>The BNF parser (<code>org.h2.bnf.Bnf</code>) reads and parses the BNF from the file <code>help.csv</code>.
+</li><li>The page parser (<code>org.h2.server.web.PageParser</code>) reads the template HTML file and fills in the diagrams.
+</li><li>The rail images (one straight, four junctions, two turns) are generated using a simple Java application.
+</li></ul>
+<p>
+To generate railroad diagrams for other grammars, see the package <code>org.h2.jcr</code>.
+This package is used to generate the SQL-2 railroad diagrams for the JCR 2.0 specification.
+</p>
+
 <!-- [close] { --></div></td></tr></table><!-- } --><!-- analytics --></body></html>
 

h2/src/tools/org/h2/build/doc/RailroadImages.java

@@ -33,7 +33,7 @@ public class RailroadImages {
      *
      * @param args the command line parameters
      */
-    public static void main(String[] args) {
+    public static void main(String... args) {
         new RailroadImages().run("docs/html/images");
     }
 

h2/src/tools/org/h2/jcr/Railroads.java

+/*
+ * Copyright 2004-2009 H2 Group. Multiple-Licensed under the H2 License,
+ * Version 1.0, and under the Eclipse Public License, Version 1.0
+ * (http://h2database.com/html/license.html).
+ * Initial Developer: H2 Group
+ */
+package org.h2.jcr;
+
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.FileOutputStream;
+import java.io.InputStreamReader;
+import java.io.Reader;
+import java.sql.ResultSet;
+import java.sql.ResultSetMetaData;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import org.h2.bnf.Bnf;
+import org.h2.build.BuildBase;
+import org.h2.build.doc.RailroadImages;
+import org.h2.server.web.PageParser;
+import org.h2.tools.Csv;
+import org.h2.util.IOUtils;
+import org.h2.util.StringUtils;
+
+/**
+ * JCR 2.0 / SQL-2 railroad generator.
+ */
+public class Railroads {
+
+    private Bnf bnf;
+    private HashMap<String, Object> session = new HashMap<String, Object>();
+
+    /**
+     * This method is called when executing this application from the command
+     * line.
+     *
+     * @param args the command line parameters
+     */
+    public static void main(String... args) throws Exception {
+        new Railroads().process();
+    }
+
+    private void process() throws Exception {
+        RailroadImages.main();
+        bnf = Bnf.getInstance(getReader());
+        ResultSet rs = Csv.getInstance().read(getReader(), null);
+        map("grammar", rs, true);
+        processHtml("jcr-sql2.html");
+    }
+
+    private void processHtml(String fileName) throws Exception {
+        String source = "src/tools/org/h2/jcr/";
+        String target = "docs/html/";
+        byte[] s = BuildBase.readFile(new File(source + "stylesheet.css"));
+        BuildBase.writeFile(new File(target + "stylesheet.css"), s);
+        String inFile = source + fileName;
+        String outFile = target + fileName;
+        new File(outFile).getParentFile().mkdirs();
+        FileOutputStream out = new FileOutputStream(outFile);
+        FileInputStream in = new FileInputStream(inFile);
+        byte[] bytes = IOUtils.readBytesAndClose(in, 0);
+        if (fileName.endsWith(".html")) {
+            String page = new String(bytes);
+            page = PageParser.parse(page, session);
+            bytes = page.getBytes();
+        }
+        out.write(bytes);
+        out.close();
+    }
+
+    private static Reader getReader() {
+        return new InputStreamReader(Railroads.class.getResourceAsStream("help.csv"));
+    }
+
+    private void map(String key, ResultSet rs, boolean railroads) throws Exception {
+        ArrayList<HashMap<String, String>> list = new ArrayList<HashMap<String, String>>();
+        while (rs.next()) {
+            HashMap<String, String> map = new HashMap<String, String>();
+            ResultSetMetaData meta = rs.getMetaData();
+            for (int i = 0; i < meta.getColumnCount(); i++) {
+                String k = StringUtils.toLowerEnglish(meta.getColumnLabel(i + 1));
+                String value = rs.getString(i + 1);
+                value = value.trim();
+                map.put(k, PageParser.escapeHtml(value));
+            }
+            String topic = rs.getString("TOPIC");
+            String syntax = rs.getString("SYNTAX").trim();
+            if (railroads) {
+                String railroad = bnf.getRailroadHtml(syntax);
+                map.put("railroad", railroad);
+            }
+            syntax = bnf.getSyntaxHtml(syntax);
+            map.put("syntax", syntax);
+
+            // remove newlines in the regular text
+            String text = map.get("text");
+            if (text != null) {
+                // text is enclosed in <p> .. </p> so this works.
+                text = StringUtils.replaceAll(text, "<br /><br />", "</p><p>");
+                text = StringUtils.replaceAll(text, "<br />", " ");
+                map.put("text", text);
+            }
+
+            String link = topic.toLowerCase();
+            link = StringUtils.replaceAll(link, " ", "_");
+            // link = StringUtils.replaceAll(link, "_", "");
+            link = StringUtils.replaceAll(link, "@", "_");
+            map.put("link", StringUtils.urlEncode(link));
+            list.add(map);
+        }
+        session.put(key, list);
+        int div = 3;
+        int part = (list.size() + div - 1) / div;
+        for (int i = 0, start = 0; i < div; i++, start += part) {
+            List<HashMap<String, String>> listThird = list.subList(start, Math.min(start + part, list.size()));
+            session.put(key + "-" + i, listThird);
+        }
+        rs.close();
+    }
+
+}

h2/src/tools/org/h2/jcr/help.csv

+# Copyright 2004-2009 H2 Group. Multiple-Licensed under the H2 License,
+# Version 1.0, and under the Eclipse Public License, Version 1.0
+# (http://h2database.com/html/license.html).
+# Initial Developer: H2 Group)
+
+"SECTION","TOPIC","SYNTAX","TEXT"
+"Grammar","Query","
+SELECT { * | { column [ , ... ] } }  FROM { selector [ join ... ] }
+[ WHERE constraint ] [ ORDER BY { ordering [ , ... ] } ]
+","
+"
+
+"Grammar","Column","
+{ [ selectorName . ] propertyName [ AS columnName ] } | { selectorName . * }
+","
+"
+
+"Grammar","Selector","
+nodeTypeName [ AS selectorName ]
+","
+"
+
+"Grammar","Join","
+{ INNER | { LEFT | RIGHT } OUTER } JOIN rightSelector ON
+{ selectorName . propertyName = joinSelectorName . joinPropertyName }
+    | { ISSAMENODE( selectorName , joinSelectorName [ , selectorPathName ] ) }
+    | { ISCHILDNODE( childSelectorName , parentSelectorName ) }
+    | { ISDESCENDANTNODE( descendantSelectorName , ancestorSelectorName ) }
+","
+"
+
+"Grammar","Constraint","
+andCondition [ { OR andCondition } [...] ]
+","
+"
+
+"Grammar","And Condition","
+condition [ { AND condition } [...] ]
+","
+"
+
+"Grammar","Condition","
+comparison | NOT constraint | ( constraint )
+    | [ selectorName . ] propertyName IS [ NOT ] NULL
+    | CONTAINS( { { [ selectorName . ] propertyName } | { selectorName . * } } , fulltextSearchExpression )
+    | { ISSAMENODE | ISCHILDNODE | ISDESCENDANTNODE } (  [ selectorName , ] PathName )
+","
+"
+
+"Grammar","Comparison","
+dynamicOperand { = | <> | < | <= | > | >= | LIKE } staticOperand
+","
+"
+
+"Grammar","Fulltext Search Expression","
+' anythingExceptSingleQuote ' | $ bindVariableName
+","
+"
+
+"Grammar","Static Operand","
+literal
+    | $ bindVariableName
+    | CAST ( literal AS { STRING | BINARY | DATE | LONG | DOUBLE | DECIMAL | BOOLEAN | NAME | PATH | REFERENCE | WEAKREFERENCE | URI } )
+","
+"
+
+"Grammar","Literal","
+' anythingExceptSingleQuote '
+    | "" anythingExceptDoubleQuote ""
+    | numberLiteral
+","
+"
+
+"Grammar","Number Literal","
+[ + | - ] { { number [ . number ] } | { . number } } [ E [ + | - ] expNumber [...] ] ]
+","
+"
+
+"Grammar","Number","
+0-9 [...]
+","
+"
+
+"Grammar","Dynamic Operand","
+[ selectorName . ] propertyName
+    | LENGTH( [ selectorName . ] propertyName  )
+    | { NAME | LOCALNAME | SCORE } ( [ selectorName ] )
+    | { LOWER | UPPER } ( dynamicOperand )
+","
+"
+
+"Grammar","Ordering","
+simpleName [ ASC | DESC ]
+","
+"
+
+"Grammar","Name","
+simpleName | '[' quotedName ']'
+","
+"
\ No newline at end of file

h2/src/tools/org/h2/jcr/jcr-sql2.html

+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<!--
+Copyright 2004-2009 H2 Group. Multiple-Licensed under the H2 License, Version 1.0,
+and under the Eclipse Public License, Version 1.0
+(http://h2database.com/html/license.html).
+Initial Developer: H2 Group
+-->
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+<head><meta http-equiv="Content-Type" content="text/html;charset=utf-8" /><title>
+JCR 2.0 SQL-2 Grammar
+</title><link rel="stylesheet" type="text/css" href="stylesheet.css" />
+</head><body>
+
+<h1>JCR 2.0 SQL-2 Grammar</h1>
+<!-- syntax-start
+<p class="notranslate">
+<c:forEach var="item" items="grammar">
+    <a href="#${item.link}">${item.topic}</a><br />
+</c:forEach>
+</p>
+syntax-end -->
+<!-- railroad-start -->
+<table class="notranslate index">
+    <tr>
+        <td class="index">
+            <c:forEach var="item" items="grammar-0">
+                <a href="#${item.link}" >${item.topic}</a><br />
+            </c:forEach>
+        </td><td class="index">
+            <c:forEach var="item" items="grammar-1">
+                <a href="#${item.link}" >${item.topic}</a><br />
+            </c:forEach>
+        </td><td class="index">
+            <c:forEach var="item" items="grammar-2">
+                <a href="#${item.link}" >${item.topic}</a><br />
+            </c:forEach>
+        </td>
+    </tr>
+</table>
+<!-- railroad-end -->
+
+<hr />
+<p>
+These railroad diagrams are based on the
+<a href="http://www.day.com/specs/jcr/2.0/6_Query.html#6.6.2%20JCR-SQL2%20Notation">JCR 2.0 specification</a>.
+</p><p>
+The diagrams are created with a small <a href="Create.java">Java program</a>
+and this <a href="help.csv">BNF</a>. The program uses the BNF parser / converter
+of the the <a href="http://www.h2database.com">H2 database engine</a>.
+</p><p>
+Please send feedback to the <a href="http://jackrabbit.apache.org/mailing-lists.html">Jackrabbit User List</a>.
+</p>
+
+<c:forEach var="item" items="grammar">
+<hr />
+<h3 id="${item.link}" class="notranslate">${item.topic}</h3>
+<!-- railroad-start -->
+${item.railroad}
+<!-- railroad-end -->
+<!-- syntax-start
+<pre>
+${item.syntax}
+</pre>
+syntax-end -->
+<p>${item.text}</p>
+<!--
+<p>Example:</p>
+<p class="notranslate">
+${item.example}</p>
+-->
+</c:forEach>
+
+</body></html>

h2/src/tools/org/h2/jcr/package.html

+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<!--
+Copyright 2004-2009 H2 Group. Multiple-Licensed under the H2 License, Version 1.0,
+and under the Eclipse Public License, Version 1.0
+(http://h2database.com/html/license.html).
+Initial Developer: H2 Group
+-->
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+<head><meta http-equiv="Content-Type" content="text/html;charset=utf-8" /><title>
+Javadoc package documentation
+</title></head><body style="font: 9pt/130% Tahoma, Arial, Helvetica, sans-serif; font-weight: normal;">
+
+Utility classes related to the JCR API.
+
+</body></html>
\ No newline at end of file

h2/src/tools/org/h2/jcr/stylesheet.css

+/*
+ * Copyright 2004-2009 H2 Group. Multiple-Licensed under the H2 License,
+ * Version 1.0, and under the Eclipse Public License, Version 1.0
+ * (http://h2database.com/html/license.html).
+ * Initial Developer: H2 Group
+ */
+
+td, input, select, textarea, body, code, pre, td, th {
+    font: 9pt/130% Tahoma, Arial, Helvetica, sans-serif;
+    font-weight: normal;
+}
+
+h1, h2, h3, h4, h5 {
+    font: 9pt Tahoma, Arial, Helvetica, sans-serif;
+    font-weight: bold;
+}
+
+td, input, select, textarea, body, code, pre {
+    font-size: 9pt;
+}
+
+pre {
+    background-color: #ece9d8;
+    border: 1px solid rgb(172, 168, 153);
+    padding: 4px;
+}
+
+code {
+    background-color: #ece9d8;
+    padding: 0px 2px;
+}
+
+img {
+    border: 0px;
+}
+
+body {
+    margin: 20px;
+    max-width: 800px;
+}
+
+h1 {
+    background-color: #0000bb;
+    padding: 2px 4px 2px 4px;
+    color: #fff;
+    font-size: 15pt;
+    line-height: normal;
+}
+
+h2 {
+    font-size: 13pt;
+    margin-top: 1.5em;
+}
+
+h3 {
+    font-size: 11pt;
+    margin-top: 1.5em;
+}
+
+h4 {
+    font-size: 9pt;
+    margin-top: 1.5em;
+}
+
+hr {
+    color: #CCC;
+    background-color: #CCC;
+    height: 1px;
+    border: 0px solid blue;
+}
+
+table {
+    background-color: #ffffff;
+    border-collapse: collapse;
+    border: 1px solid #aca899;
+}
+
+th {
+    text-align: left;
+    background-color: #ece9d8;
+    border: 1px solid #aca899;
+    padding: 2px;
+}
+
+td {
+    background-color: #ffffff;
+    text-align: left;
+    vertical-align: top;
+    border: 1px solid #aca899;
+    padding: 2px;
+}
+
+form {
+}
+
+ul, ol {
+    list-style-position: outside;
+    padding-left: 20px;
+}
+
+li {
+    margin-top: 2px;
+}
+
+a {
+    text-decoration: none;
+    color: #0000ff;
+}
+
+a:hover {
+    text-decoration: underline;
+}
+
+em.u {
+    text-decoration: underline;
+    font-style: normal;
+}
+
+.menu {
+    margin: 10px 10px 10px 10px;
+}
+
+table.search {
+    width: 100%;
+    border: 0px;
+}
+
+tr.search {
+    border: 0px;
+}
+
+td.search {
+    border: 0px;
+    padding: 2px 0px 2px 10px;
+}
+
+td.searchKeyword {
+    border: 0px;
+    padding: 0px 0px 0px 2px;
+}
+
+td.searchKeyword a {
+    text-decoration: none;
+    color: #000000;
+}
+
+td.searchKeyword a:hover {
+    text-decoration: underline;
+}
+
+td.searchLink {
+    border: 0px;
+    padding: 0px 0px 0px 32px;
+    text-indent: -16px;
+}
+
+td.searchLink a {
+    text-decoration: none;
+    color: #0000ff;
+}
+
+td.searchLink a:hover {
+    text-decoration: underline;
+}
+
+table.nav {
+    border: 0px;
+}
+
+tr.nav {
+    border: 0px;
+}
+
+td.nav {
+    border: 0px;
+}
+
+table.content {
+    width: 100%;
+    height: 100%;
+    border: 0px;
+}
+
+tr.content {
+    border:0px;
+}
+
+td.content {
+    border:0px;
+}
+
+.contentDiv {
+    margin:10px;
+}
+
+.content {
+    margin: 10px 10px 10px 0px;
+}
+
+.screenshot {
+    border: 1px outset #800;
+    padding: 10px;
+    margin: 10px 0px;
+}
+
+.compareFeature {
+}
+
+.compareY {
+    color: #050;
+}
+
+.compareN {
+    color: #800;
+}
+
+table.index {
+    width: 100%;
+    border: 0px;
+    padding: 0px;
+    margin: 0px;
+    border: 0px none;
+    border-collapse: collapse;
+}
+
+/*    width: 570px;
+    width: 190px;
+    */
+
+td.index {
+    width: 33%;
+    border: 0px;
+    padding: 0px;
+    margin: 0px;
+    border: 0px none;
+    border-collapse: collapse;
+    vertical-align: top;
+}
+
+.railroad {
+    border: 0px;
+    padding: 0px;
+    margin: 0px;
+    border-collapse: collapse;
+    vertical-align: top;
+}
+
+.c {
+    padding: 1px 3px;
+    margin: 0px 0px;
+    border: 2px solid;
+    -moz-border-radius: 0.4em;
+    border-radius: 0.4em;
+    background-color: #fff;
+}
+
+.ts {
+    border: 0px;
+    padding: 0px;
+    margin: 0px;
+    border-collapse: collapse;
+    vertical-align: top;
+    height: 24px;
+    background-image: url(images/div-ts.png);
+    width: 16px;
+}
+
+.ls {
+    border: 0px;
+    padding: 0px;
+    margin: 0px;
+    border-collapse: collapse;
+    vertical-align: top;
+    height: 24px;
+    background-image: url(images/div-ls.png);
+    width: 16px;
+}
+
+.ks {
+    border: 0px;
+    padding: 0px;
+    margin: 0px;
+    border-collapse: collapse;
+    vertical-align: top;
+    height: 24px;
+    background-image: url(images/div-ks.png);
+    width: 16px;
+}
+
+.te {
+    border: 0px;
+    padding: 0px;
+    margin: 0px;
+    border-collapse: collapse;
+    vertical-align: top;
+    height: 24px;
+    background-image: url(images/div-te.png);
+    width: 16px;
+}
+
+.le {
+    border: 0px;
+    padding: 0px;
+    margin: 0px;
+    border-collapse: collapse;
+    vertical-align: top;
+    height: 24px;
+    background-image: url(images/div-le.png);
+    width: 16px;
+}
+
+.ke {
+    border: 0px;
+    padding: 0px;
+    margin: 0px;
+    border-collapse: collapse;
+    vertical-align: top;
+    height: 24px;
+    background-image: url(images/div-ke.png);
+    width: 16px;
+}
+
+.d {
+    border: 0px;
+    padding: 0px;
+    margin: 0px;
+    border-collapse: collapse;
+    vertical-align: top;
+    height: 24px;
+    background-image: url(images/div-d.png);
+    background-repeat: repeat-x;
+    min-width: 16px;
+}