Working on a literate generator similar to Docco.

resources/main/test.groovy

@@ -3,28 +3,36 @@ import org.parboiled.Parboiled
 import org.parboiled.parserunners.ReportingParseRunner
 import org.parboiled.parserunners.RecoveringParseRunner
 
-parser = Parboiled.createParser(JLPPegParser.class)
+makeParser = {
-parseRunner = new RecoveringParseRunner(parser.SourceFile())
+    println "Making the standard parser."
+    println "---------------------------"
 
+    parser = Parboiled.createParser(JLPPegParser.class)
+    parseRunner = new ReportingParseRunner(parser.SourceFile())
+}
+
+makeExperimentalParser = {
+    println "Making the experimental parser."
+    println "-------------------------------"
+
+    parser = Parboiled.createParser(com.jdblabs.jlp.experimental.JLPPegParser.class)
+    parseRunner = new ReportingParseRunner(parser.SourceFile())
+}
 
 simpleTest = {
-    "Parsing the simple test into 'result'.\n" +
+    println "Parsing the simple test into 'result'."
-    "--------------------------------------\n"
+    println "--------------------------------------"
 
     testLine = """%% This the first test line.
     %% Second Line
-    %% Third Line
+    %% Third Line \n\n Fifth line \n\n %% Seventh line \n\n
-    Fourth line
+    %% @author Eigth Line
+    %% @Example Ninth Line
+    %%    Markdown lines (tenth line)
+    %%    Still markdown (eleventh line)
+    Twelfth line is a code line"""
 
-    %% Sixth line
+    simpleResult = parseRunner.run(testLine)
-    %% @author Seventh Line
-    %% @Example Eigth Line
-    %%    Markdown lines (ninth line)
-    %%    Still markdown (tenth line)
-    Eleventh line is a code line
-    """
-
-    parseRunner.run(testLine)
 }
 
 vbsTest = {

resources/main/vbs_db_records.hrl

@@ -1,8 +1,7 @@
 % vbs_db_records.erl
 %% @author Jonathan Bernard <jdb@jdb-labs.com>
-%% #copyright 2010-2011 JDB Labs Inc.
+%% @copyright 2010-2011 JDB Labs Inc.
 
-%% @doc
 %%  The VBS database API is centered around the data records:
 %% 
 %%  * Tables are named after the records. ``vbs_adult`` records are stored in 
@@ -15,30 +14,30 @@
 %% #Record Definitions
 %% Here are the record definitions:
 
-%% @doc Information about an adult in the VBS system. 
+%% @api Information about an adult in the VBS system. 
 %% @org records/vbs_adult
 -record(vbs_adult, {
 
-    %% @doc A unique number. This is the record's primary identification and
+    %% @api A unique number. This is the record's primary identification and
     %%  the table's primary key
     %% @org records/vbs_adult/id
     id,
 
-    %% @doc A unique full name.
+    %% @api A unique full name.
     %% @example "John Smith", "Fae Alice McDonald"
     %% @org records/vbs_adult/name
     name,
 
-    %% @doc The adult's age (optional).
+    %% @api The adult's age (optional).
     %% @org records/vbs_adult/age
     age = 0,
 
-    %% @doc A list of phone numbers (strings). 
+    %% @api A list of phone numbers (strings). 
     %% @example ["512-555-1155", "123-456-7890"]
     %% @org records/vbs_adult/phone_numbers
     phone_numbers,
 
-    %% @doc The adult's address (optional). There is not pre-defined format,
+    %% @api The adult's address (optional). There is not pre-defined format,
     %%      this is a string that can be formatted s desired (linebreaks are ok,
     %%      for example).
     %% @example
@@ -48,28 +47,28 @@
     %% @org records/vbs_adult/address 
     address = "",
 
-    %% @doc The adult's email address as a string.
+    %% @api The adult's email address as a string.
     %% @example "john_smith@mailco.com"
     %% @org records/vbs_adult/email 
     email = ""}).
 
-%% @doc An entry recording a person's attendance.
+%% @api An entry recording a person's attendance.
 %% @org records/vbs_attendance
 -record(vbs_attendance, {
 
-    %% @doc A unique number. This is the record's primary identification and the
+    %% @api A unique number. This is the record's primary identification and the
     %%  table's primary key.
     %% @org records/vbs_attendance/id
     id,
 
-    %% @doc The id of person who attended. This is a foreign key onto either the
+    %% @api The id of person who attended. This is a foreign key onto either the
     %%  [`vbs_worker`](jlp://records/vbs_worker) or
     %%  [`vbs_child`](jlp://records/vbs_child) table, depending on the value of
     %%  the [`person_type`](jlp://records/vbs_attendance/person_type) field.
     %% @org records/vbs_attendance/person_id
     person_id,
 
-    %% @doc The type of person who attended. This determines which table the
+    %% @api The type of person who attended. This determines which table the
     %%  [`person_id`](jlp://records/vbs_attendance/person_id) links on. The
     %%  possible values and the corresponding link tables are:
     %%
@@ -81,23 +80,23 @@
     %% @org records/vbs_attendance/person_type
     person_type,
 
-    %% @doc The date of attendance, stored as {Year, Month, Day}.
+    %% @api The date of attendance, stored as {Year, Month, Day}.
     %% @example {2011, 6, 14}
     %% @org records/vbs_attendance/date 
     date = {1900, 1, 1},
 
-    %% @doc A timestamp taken when the person was signed in, stored  as
+    %% @api A timestamp taken when the person was signed in, stored  as
     %%  {Hour, Minute, Second}
     %% @example {5, 22, 13}
     %% @org records/vbs_attendance/sign_in 
     sign_in = false,        % {hour, minute, second}
 
-    %% @doc A timestamp taken when the person is signed out, stored as
+    %% @api A timestamp taken when the person is signed out, stored as
     %% {Hour, Minute, Second}
     %% @org records/vbs_attendance/sign_out 
     sign_out = false,       % {hour, minute, second}
 
-    %% @doc A list of {Key, Value} pairs that can be used to store additional
+    %% @api A list of {Key, Value} pairs that can be used to store additional
     %%  information. This is intended to allow callers to store optional data,
     %%  or client-specific data, without having to alter the database schema.
     %%  When working with `vbs_attendance` records, a caller should ignore
@@ -105,196 +104,196 @@
     %% @org records/vbs_attendance/ext_data 
     ext_data = [],
 
-    %% @doc Any comments for the day about this person.
+    %% @api Any comments for the day about this person.
     %% @org records/vbs_attendance/comments 
     comments = ""}).
 
-%% @doc Information about a child in the VBS program.
+%% @api Information about a child in the VBS program.
 %% @org records/vbs_child
 -record(vbs_child, {
 
-    %% @doc A unique number. This is the record's primary identification and the
+    %% @api A unique number. This is the record's primary identification and the
     %%  table's primary key.
     %% @org records/vbs_child/id
     id,
 
-    %% @doc The id of the crew to which this child has been assigned. This is a
+    %% @api The id of the crew to which this child has been assigned. This is a
     %%  foreign key linking to a [`vbs_crew.id`](jlp://records/vbs_crew/id).
     %% @org records/vbs_child/crew_id
     crew_id,
 
-    %% @doc The child's full name.
+    %% @api The child's full name.
     %% @example "Mary Scott", "Gregory Brown"
     %% @org records/vbs_child/name
     name, 
 
-    %% @doc The child's date of birth, stored as {Year, Month, Day}
+    %% @api The child's date of birth, stored as {Year, Month, Day}
     %% @example {1998, 12, 22}
     %% @org records/vbs_child/date_of_birth
     date_of_birth,
 
-    %% @doc The child's gender, either `male` or `female`
+    %% @api The child's gender, either `male` or `female`
     %% @org records/vbs_child/gender
     gender, 
 
-    %% @doc The child's grade level in school.
+    %% @api The child's grade level in school.
     %% @org records/vbs_child/grade
     grade,
 
-    %% @doc A list of ids representing the child's legal guardians. These link
+    %% @api A list of ids representing the child's legal guardians. These link
     %%  the child record to adult records by the
     %%  [`vbs_adult.id`](jlp://records/vbs_adult/id)
     %% @example [4, 5]
     %% @org records/vbs_child/guardian_ids
     guardian_ids,
 
-    %% @doc A list of ids, similar to `guardian_ids`, but representing the
+    %% @api A list of ids, similar to `guardian_ids`, but representing the
     %%  adults that are allowed to pick the children up. These link the child
     %%  record to adult records by
     %%  ['vbs_adult.id`](jlp://records/vbs_adult/id).
     %% @org records/vbs_child/pickup_ids
     pickup_ids,
 
-    %% @doc A list of ids, similar to `guardian_ids` and `pickup_ids`, but
+    %% @api A list of ids, similar to `guardian_ids` and `pickup_ids`, but
     %%  representing adults that should be contacted if there is an emergency
     %%  involving this child (injury, for example). These link the child record
     %%  to adult records by [`vbs_adult.id`](jlp://records/vbs_adult/id).
     %% @org records/vbs_child/emerency_ids
     emerency_ids,
 
-    %% @doc The child's home church, usually used if they are not a member of
+    %% @api The child's home church, usually used if they are not a member of
     %%  the hosting church.
     %% @org records/vbs_child/home_church
     home_church,
 
-    %% @doc If this child is a visitor, this is used to track who invited them,
+    %% @api If this child is a visitor, this is used to track who invited them,
     %%  or who brought them.
     %% @org records/vbs_child/visitor_of
     visitor_of,
 
-    %% @doc Answers the question: Is this child a visitor? Valid values are
+    %% @api Answers the question: Is this child a visitor? Valid values are
     %%  `true` and `false`.
     %% @org records/vbs_child/is_visitor
     is_visitor,
 
-    %% @doc The date the child registered, stored as {Year, Month, Day}
+    %% @api The date the child registered, stored as {Year, Month, Day}
     %% @org records/vbs_child/registration_date
     registration_date,
 
-    %% @doc The child's shirt size, stored as a string.
+    %% @api The child's shirt size, stored as a string.
     %% @org records/vbs_child/shirt_size
     shirt_size,
 
-    %% @doc Any special needs this child has that should be accomodated.
+    %% @api Any special needs this child has that should be accomodated.
     %% @org records/vbs_child/special_needs
     special_needs,
 
-    %% @doc Any known allergies this child has.
+    %% @api Any known allergies this child has.
     %% @org records/vbs_child/allergies
     allergies,
 
-    %% @doc Additional comments about this child.
+    %% @api Additional comments about this child.
     %% @org records/vbs_child/comments
     comments}).
 
-%% @doc Information about a crew in the VBS system.
+%% @api Information about a crew in the VBS system.
 %% @org records/vbs_crew
 -record(vbs_crew, {
 
-    %% @doc A unique number. This is the record's primary identification and the
+    %% @api A unique number. This is the record's primary identification and the
     %%  table's primary key.
     %% @org records/vbs_crew/id
     id,     % primary key
 
-    %% @doc The crew number.
+    %% @api The crew number.
     %% @org records/vbs_crew/number
     number,
 
-    %% @doc The crew type. This is a foreign key on
+    %% @api The crew type. This is a foreign key on
     %%  [`vbs_crew_type.id`](jlp://records/vbs_crew_type/id).
     %% @org records/vbs_crew/crew_type_id
     crew_type_id, % foreign key onto crew_type
 
-    %% @doc The name of the crew, stored as a string.
+    %% @api The name of the crew, stored as a string.
     %% @org records/vbs_crew/name
     name,
 
-    %% @doc Any comments about the crew.
+    %% @api Any comments about the crew.
     %% @org records/vbs_crew/comments 
     comments = ""}).
 
-%% @doc Information about a crew type. Crew types are often used when a VBS
+%% @api Information about a crew type. Crew types are often used when a VBS
 %%  program has seperate activities set up for different types of children
 %%  (usually based on age). For example, having two type: Elementary and Pre-K
 %%  is common when there is a seperate set of activities for smaller children.
 %% @org records/vbs_crew_type
 -record(vbs_crew_type, {
 
-    %% @doc A unique number. This is the record's primary identification and the
+    %% @api A unique number. This is the record's primary identification and the
     %%  table's primary key.
     %% @org records/vbs_crew_type/id
     id,
 
-    %% @doc The displayed name of the crew type.
+    %% @api The displayed name of the crew type.
     %% @org records/vbs_crew_type/name
     name}).
    
-%% @doc The id counter records are used to keep track of the next valid id for a
+%% @api The id counter records are used to keep track of the next valid id for a
 %%  specific purpose. This is how the unique id fields in other records is
 %%  implmented. 
 %% @org records/vbs_id_counter
 -record(vbs_id_counter, {
 
-    %% @doc A name for the counter. This is the primary key for the table and
+    %% @api A name for the counter. This is the primary key for the table and
     %%  must be unique.
     %% @example `vbs_adult_id`
     %% @org records/vbs_id_counter/name
     name,
 
-    %% @doc The next value for this counter.
+    %% @api The next value for this counter.
     %% @org records/vbs_id_counter/next_value 
     next_value = 0}).
 
-%% @doc Information about workers involved in the VBS program.
+%% @api Information about workers involved in the VBS program.
 %% @org records/vbs_worker
 -record(vbs_worker, {
 
-    %% @doc A unique number. This is the record's primary identification and the
+    %% @api A unique number. This is the record's primary identification and the
     %%  table's primary key.
     %% @org records/vbs_worker/id
     id,
 
-    %% @doc Links this worker record to a [`vbs_adult`](jlp://records/vbs_adult)
+    %% @api Links this worker record to a [`vbs_adult`](jlp://records/vbs_adult)
     %% @org records/vbs_worker/adult_id
     adult_id, % foreign key on adult
 
-    %% @doc The crew this worker is assigned to. This is a link to
+    %% @api The crew this worker is assigned to. This is a link to
     %%  [`vbs_crew.id`](jlp://records/vbs_crew/id). The most common way to deal
     %%  with workers who are not assigned to a particular crew is to create a
     %%  special administrative crew and assign all these workers to that crew.
     %% @org records/vbs_worker/crew_id 
     crew_id = 0,
 
-    %% @doc
+    %% @api
     %% @org records/vbs_worker/worker_type_id
     worker_type_id,      % foreign key on worker_type
 
-    %% @doc
+    %% @api
     %% @org records/vbs_worker/shirt_size
     shirt_size,
 
-    %% @doc
+    %% @api
     %% @org records/vbs_worker/ext_data 
     ext_data = []}).
 
-%% @doc
+%% @api
 %% @org records/vbs_worker_type
 -record(vbs_worker_type, {
 
-    %% @doc
+    %% @api
     %% @org records/vbs_worker_type/id
     id,
 
-    %% @doc
+    %% @api
     %% @org records/vbs_worker_type/name
     name}).

src/main/com/jdblabs/jlp/experimental/DeadSimple.java

@@ -0,0 +1,23 @@
+package com.jdblabs.jlp.experimental;
+
+import org.parboiled.Action;
+import org.parboiled.BaseParser;
+import org.parboiled.Context;
+import org.parboiled.Rule;
+import org.parboiled.annotations.*;
+
+@BuildParseTree
+public class DeadSimple extends BaseParser {
+
+    public Rule S() {
+        return OneOrMore(FirstOf(Line(), EmptyLine()).skipNode()); }
+
+    public Rule Line() {
+        return Sequence(OneOrMore(NOT_EOL).skipNode(), EOL); }
+
+    public Rule EmptyLine() {
+        return EOL; }
+
+    public Rule EOL = Ch('\n');
+    public Rule NOT_EOL = Sequence(TestNot(EOL), ANY);
+}

src/main/com/jdblabs/jlp/experimental/JLPBaseGenerator.groovy

@@ -0,0 +1,37 @@
+package com.jdblabs.jlp.experimental
+
+import com.jdblabs.jlp.experimental.ast.*
+import java.util.List
+import java.util.Map
+
+public abstract class JLPBaseGenerator {
+
+    protected Map docState
+
+    protected JLPBaseGenerator() {
+        docState = [orgs:           [:],        // stores `@org` references
+                    codeTrees:      [:],        // stores code ASTs for
+                    currentDocId:   false ] }   // store the current docid
+
+    protected Map<String, String> generate(Map<String, SourceFile> sources) {
+        Map result = [:]
+        sources.each { sourceId, sourceAST ->
+
+            // set up the current generator state for this source
+            docState.currentDocId = sourceId
+            docState.codeTrees[sourceId] = sourceAST.codeAST
+
+            // generate the doc for this source
+            result[sourceId] = emit(sourceAST) }
+
+        // return our results
+        return result }
+
+    protected abstract String emit(SourceFile sourceFile)
+    protected abstract String emit(Block block)
+    protected abstract String emit(DocBlock docBlock)
+    protected abstract String emit(CodeBlock codeBlock)
+    protected abstract String emit(DocText docText)
+    protected abstract String emit(Directive directive)
+
+}

src/main/com/jdblabs/jlp/experimental/JLPPegParser.java

@@ -22,13 +22,67 @@ public class JLPPegParser extends BaseParser<Object> {
      */
     public Rule SourceFile() {
         return Sequence(
+            // At the start of processing a new SourceFile, we need to set up
+            // our internal state. 
+
+            // Clear the line count.
             clearLineCount(),
+
+            // Add the top-level SourceFile AST node.
             push(new SourceFile()),
 
+            // A SourceFile is made up of one or more Blocks
             OneOrMore(Sequence(
-                FirstOf(Block(), DocBlock(), CodeBlock()),
+                // All of these options result in one new Block pushed onto the
+                // stack.
+                FirstOf(
 
-                addBlock((ASTNode) pop())))); }
+                    // Match a whole Block. This pushes a Block on the stack.
+                    Block(),    
+
+                    // A standalone DocBlock. We will create an empty CodeBlock
+                    // to pair with it, then push a new Block onto the stack
+                    // made from the DocBlock and the empty CodeBlock
+                    Sequence(
+                        // 1. We need to remember the line number to create the
+                        // Block
+                        push(curLineNum),
+
+                        // 2. Match the DocBlock.
+                        DocBlock(),
+
+                        // 3. Create the empty CodeBlock.
+                        push(new CodeBlock(curLineNum)),
+
+                        // 4. Create the Block and push it onto the stack.
+                        push(new Block((CodeBlock) pop(), (DocBlock) pop(),
+                            popAsInt()))),
+
+                    // A standalone CodeBlock. Similar to the standalone
+                    // DocBlock, we will create an empty DocBlock to pair with
+                    // the CodeBlock to make a Block, which is pushed onto the
+                    // stack:
+                    //
+                    // *Note: With the way the parser is currently written,
+                    //        this will only match a CodeBlock that occurs
+                    //        before any DocBlock.*
+                    Sequence(
+                        // 1. Remember the line number for the Block.
+                        push(curLineNum),
+
+                        // 2. Create the empty DocBlock.
+                        push(new DocBlock(curLineNum)),
+
+                        // 3. Match the CodeBlock
+                        CodeBlock(),
+
+                        // 4. Create the Block and push it onto the stack
+                        push(new Block((CodeBlock) pop(), (DocBlock) pop(),
+                            popAsInt())))),
+
+                // pop the Block created by one of the above options and add it
+                // to the SourceFile
+                addBlockToSourceFile((Block) pop())))); }
 
     /**
      * Parses the rule:
@@ -71,7 +125,7 @@ public class JLPPegParser extends BaseParser<Object> {
 
     /**
      * Parses the rule:
-     *  Directive = DocLineStart AT (LongDirective / ShortFirective)
+     *  Directive = DocLineStart AT (LongDirective / ShortDirective)
      *
      * Pushes a Directive node on the stack.
      */
@@ -82,7 +136,7 @@ public class JLPPegParser extends BaseParser<Object> {
     /**
      * Parses the rule:
      *  LongDirective =
-     *      (AUTHOR_DIR / DOC_DIR / EXAMPLE_DIR) RemainingLine DocText?
+     *      (API_DIR / EXAMPLE_DIR) RemainingLine DocText?
      *
      * Pushes a Directive node onto the stack.
      */
@@ -90,7 +144,7 @@ public class JLPPegParser extends BaseParser<Object> {
         return Sequence(
             push(curLineNum),
 
-            FirstOf(AUTHOR_DIR, DOC_DIR, EXAMPLE_DIR),  push(match()),
+            FirstOf(API_DIR, EXAMPLE_DIR),  push(match()),
             RemainingLine(),                            push(match()),
 
             Optional(Sequence(
@@ -102,14 +156,14 @@ public class JLPPegParser extends BaseParser<Object> {
 
     /**
      * Parses the rule:
-     *  ShortDirective = (ORG_DIR / COPYRIGHT_DIR) RemainingLine
+     *  ShortDirective = (AUTHOR_DIR / ORG_DIR / COPYRIGHT_DIR) RemainingLine
      *
      * Pushes a Directive node onto the stack.
      */
     Rule ShortDirective() {
         return Sequence(
             push(curLineNum),
-            FirstOf(ORG_DIR, COPYRIGHT_DIR), push(match()),
+            FirstOf(AUTHOR_DIR, ORG_DIR, COPYRIGHT_DIR), push(match()),
             RemainingLine(),
             
             push(new Directive(match().trim(), popAsString(), popAsInt()))); }
@@ -127,27 +181,28 @@ public class JLPPegParser extends BaseParser<Object> {
                 DocLineStart(), TestNot(AT), RemainingLine(),
                 addToDocText(match())))); }
 
-    @SuppressSubnodes
     Rule DocLineStart() {
         return Sequence(
             ZeroOrMore(SPACE), DOC_LINE_START, Optional(SPACE)); }
 
-    @SuppressSubnodes
+    Rule NonEmptyLine() {
+        return Sequence(OneOrMore(NOT_EOL), FirstOf(EOL, EOI)); }
+
     Rule RemainingLine() {
         return FirstOf(
             Sequence(ZeroOrMore(NOT_EOL), EOL, incLineCount()),
             Sequence(OneOrMore(NOT_EOL), EOI, incLineCount())); }
 
-    Rule AT         = Ch('@');
+    Rule AT         = Ch('@').label("AT");
-    Rule EOL        = OneOrMore(AnyOf("\r\n"));
+    Rule EOL        = FirstOf(String("\r\n"), Ch('\n'), Ch('\r')).label("EOL");
-    Rule NOT_EOL    = Sequence(TestNot(EOL), ANY);
+    Rule NOT_EOL    = Sequence(TestNot(EOL), ANY).label("NOT_EOL");
-    Rule SPACE      = AnyOf(" \t");
+    Rule SPACE      = AnyOf(" \t").label("SPACE");
-    Rule DOC_LINE_START = String("%%");
+    Rule DOC_LINE_START = String("%%").label("DOC_LINE_START");
 
     // directive terminals
     Rule AUTHOR_DIR     = IgnoreCase("author");
     Rule COPYRIGHT_DIR  = IgnoreCase("copyright");
-    Rule DOC_DIR        = IgnoreCase("doc");
+    Rule API_DIR        = IgnoreCase("api");
     Rule EXAMPLE_DIR    = IgnoreCase("example");
     Rule ORG_DIR        = IgnoreCase("org");
 
@@ -159,7 +214,7 @@ public class JLPPegParser extends BaseParser<Object> {
 
     boolean incLineCount() { curLineNum++; return true; }
 
-    boolean addBlock(ASTNode block) {
+    boolean addBlockToSourceFile(Block block) {
         SourceFile sourceFile = (SourceFile) pop();
         sourceFile.blocks.add(block);
         return push(sourceFile); }

src/main/com/jdblabs/jlp/experimental/LiterateMarkdownGenerator.groovy

@@ -0,0 +1,171 @@
+package com.jdblabs.jlp.experimental
+
+import com.jdblabs.jlp.experimental.ast.*
+import com.jdblabs.jlp.experimental.ast.Directive.DirectiveType
+
+import org.pegdown.Extensions
+import org.pegdown.PegDownProcessor
+
+import java.util.List
+
+public class LiterateMarkdownGenerator extends JLPBaseGenerator {
+
+    protected PegDownProcessor pegdown
+
+    protected LiterateMarkdownGenerator() {
+        super()
+
+        pegdown = new PegDownProcessor(
+            Extensions.TABLES & Extensions.DEFINITIONS) }
+
+    protected static Map<String, String> generateDocuments(
+    Map<String, SourceFile> sources) {
+        LiterateMarkdownGenerator inst = new LiterateMarkdownGenerator()
+        return inst.generate(sources) }
+
+    protected String emit(SourceFile sourceFile) {
+        StringBuilder sb = new StringBuilder()
+
+
+        // Create the HTML file head
+        sb.append(
+"""<!DOCTYPE html>
+<html>
+    <head>
+        <title>${docState.currentDocId}</title>
+        <meta http-equiv="content-type" content="text/html; charset=UTF-8">
+        <!-- <link rel="syltesheet" media="all" href=""/> -->
+    </head>
+    <body>
+        <div id="container">
+            <table cellpadding="0" cellspacing="0">
+                <thead><tr>
+                    <th class="doc"><h1>${docState.currentDocId}</h1></th>
+                    <th class="code"/>
+                </tr></thead>
+                <tbody>""")
+
+        // Emit the document to Markdown
+        sourceFile.blocks.each { block -> sb.append(emit(block)) }
+
+        // Create the HTML file foot
+        sb.append(
+"""                </tbody>
+            </table>
+        </div>
+    </body>
+</html>""")
+
+        return sb.toString() }
+
+    protected String emit(Block block) {
+        StringBuilder sb = new StringBuilder()
+
+        // Look for an `@org` directive in the `Block`
+        Directive orgDir = block.docBlock.directives.find {
+            it.type == DirectiveType.Org }
+
+        // Create the `tr` that will hold the `Block`
+        if (orgDir) { sb.append("\n<tr id='${orgDir.value}'>") }
+        else        { sb.append("<tr>") }
+
+        // Create the `td` for the documentation.
+        sb.append('\n<td class="doc">')
+        sb.append(emit(block.docBlock))
+        sb.append('</td>')
+
+        // Create the `td` for the `CodeBlock`
+        sb.append('\n<td class="code">')
+        sb.append(emit(block.codeBlock))
+        sb.append('</td>')
+
+        // Close the table row.
+        sb.append('</tr>') }
+
+    protected String emit(DocBlock docBlock) {
+        // Create a queue for the doc block elements, we are going to 
+        // sort them by type and line number
+        List emitQueue 
+
+        // Later we will need a string builder to hold our result.
+        StringBuilder sb
+
+        // Add all the directives
+        emitQueue = docBlock.directives.collect { directive ->
+            def queueItem = [lineNumber: directive.lineNumber, value: directive]
+            switch(directive.type) {
+                case DirectiveType.Api:         queueItem.priority = 12; break
+                case DirectiveType.Author:      queueItem.priority = 10; break
+                case DirectiveType.Copyright:   queueItem.priority = 11; break
+                case DirectiveType.Example:     queueItem.priority = 50; break
+                case DirectiveType.Org:
+                    docState.orgs[directive.value] = directive
+                    queueItem.priority = 0
+                    break }
+            
+            return queueItem }
+
+        // Add all the doc text blocks
+        emitQueue.addAll(docBlock.docTexts.collect { docText ->
+            [lineNumber: docText.lineNumber, priority: 50, value: docText] })
+                        
+
+        println emitQueue
+        println "----------"
+
+        // Sort the emit queue by priority, then line number.
+        emitQueue.sort(
+            {i1, i2 -> i1.priority != i2.priority ?
+                        i1.priority - i2.priority :
+                        i1.line - i2.line} as Comparator)
+    
+        // Finally, we want to treat the whole block as one markdown chunk, so
+        // we will concatenate the values in the emit queue and then process
+        // the whole block once
+        sb = new StringBuilder()
+        emitQueue.each { queueItem -> sb.append(emit(queueItem.value)) } 
+
+        return pegdown.markdownToHtml(sb.toString())
+    }
+
+    protected String emit(CodeBlock codeBlock) {
+        def codeLines
+
+        // Collect the lines into an array.
+        codeLines = codeBlock.lines.collect { lineNumber, line ->
+            [lineNumber, line] }
+
+        // Sort by line number.
+        codeLines.sort({ i1, i2 -> i1[0] - i2[0] } as Comparator)
+
+        codeLines = codeLines.collect { arr -> arr[1] }
+
+        // write out the lines in a <pre><code> block
+        return "<pre><code>${codeLines.join('')}</code></pre>" }
+
+    protected String emit(DocText docText) { return docText.value }
+
+    protected String emit(Directive directive) {
+        switch(directive.type) {
+
+            // An `@api` directive is immediately processed and wrapped in a
+            // div (we need to process this now because Markdown does not
+            // process input inside HTML elements).
+            case DirectiveType.Api:
+                return "<div class='api'>" +
+                    pegdown.markdownToHtml(directive.value) + "</div>\n"
+
+            // An `@author` directive is turned into a definition list.
+            case DirectiveType.Author:
+                return "Author\n:   ${directive.value}\n"
+
+            case DirectiveType.Copyright:
+                return "&copy; ${directive.value}\n"
+
+            // An `@example` directive is returned as is
+            case DirectiveType.Example: return directive.value
+
+            // An `@org` directive is ignored.
+            case DirectiveType.Org: return "" }
+    }
+}

src/main/com/jdblabs/jlp/experimental/ast/Directive.groovy

@@ -3,9 +3,9 @@ package com.jdblabs.jlp.experimental.ast
 public class Directive extends ASTNode {
 
     public static enum DirectiveType {
+        Api,
         Author,
         Copyright,
-        Doc,
         Example,
         Org;
         

src/main/com/jdblabs/jlp/experimental/ast/DocText.groovy

@@ -4,7 +4,9 @@ public class DocText extends ASTNode {
 
     public String value
 
-    public DocText(int lineNumber) { super(lineNumber) }
+    public DocText(int lineNumber) {
+        super(lineNumber)
+        value = "" }
 
     public String toString() { value }
 }

src/main/com/jdblabs/jlp/experimental/ast/SourceFile.groovy

@@ -3,4 +3,6 @@ package com.jdblabs.jlp.experimental.ast
 public class SourceFile {
     public List<ASTNode> blocks = []
     public def codeAST
+
+    public String id
 }