Added .pull command

hintjens · hintjens · commit ccfae8ce1536 · 2011-03-24T20:53:47.000+01:00
diff --git a/README.md b/README.md
@@ -2,31 +2,39 @@
 <center>
 <img src="https://github.com/imatix/gitdown/raw/master/images/README_1.png" alt="1">
 </center>
+    /----------------------------------------------------------\+\
+    |/---------------------------------------------------------/||
+    ||      /--+ +------+ +------\ /----\/+ +\  +\  +\ /------\ ||
+    ||      \-\| \--\/--/ |+----\| |/---/|| ||  ||  || |/----\| ||
+    ||        ||    ||    ||    || ||    || ||  ||  || ||    || ||
+    ||  +---\ ||    ||    ||    || ||    || ||  ||  || ||    || ||
+    ||  \--\| ||    ||    \/    || ||    || ||  ||  || ||    || ||
+    ||     || ||    ||    /-----/| |\----/| |\--/\--/| ||    || ||
+    ||     || \/    \/    +------/ \------/ \--------/ +/    \+ ||
+    |\-----/|+--------------------------------------------------/|
+    \-------/+---------------------------------------------------/
+[/diagram]
 
 <A name="toc1-17" title="Welcome To Gitdown" />
 Welcome To Gitdown
 ==================
 
 Gitdown is a simple tool for writing documentation hosted on a github repository.  It uses [ditaa][] to convert ascii diagrams into images, and produces [markdown][] documents that can be uploaded to your repository along with code.  I made Gitdown so that we could write technical white papers and user guides as plain text (including diagrams) and publish them with a single "git push" command.  Gitdown is a simpler version of the tool we use to maintain the [ØMQ][zeromq] [Guide][zguide].
 
-Gitdown is written and maintained by Pieter Hintjens.  Please use the issue [tracker][] for all comments and errata.  This document was published on Thursday February, 2011 at 12:07:19, and generated by the magic of Gitdown from README.txt.
+Gitdown is written and maintained by Pieter Hintjens.  Please use the issue [tracker][] for all comments and errata.  This document was published on Thursday March, 2011 at 20:11:14, and generated by the magic of Gitdown from README.txt.
 
-This is version 2010.10.11 of Gitdown.  Changelog:
+This is version 2011.03.24 of Gitdown. Changelog:
 
+* 2010.03.24: added .pull command to include chunks from other files.
 * 2010.10.11: don't do symbol substitution in code blocks.
 * 2010.10.09: added .toc token to generate table of contents.
 
-<A name="toc2-30" title="Contents" />
+<A name="toc2-31" title="Contents" />
 Contents
 --------
 
-&emsp;<a href="#toc2-36">License</a>
-&emsp;<a href="#toc2-45">Installation and Use</a>
-&emsp;<a href="#toc2-70">How it Works</a>
-&emsp;<a href="#toc2-125">Gitdown Syntax Summary</a>
-&emsp;<a href="#toc2-182">Markdown Syntax Summary</a>
 
-<A name="toc2-36" title="License" />
+<A name="toc2-37" title="License" />
 License
 -------
 
@@ -35,7 +43,7 @@ Copyright (c) 1996-2011 iMatix Corporation
 
 This is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
 
-<A name="toc2-45" title="Installation and Use" />
+<A name="toc2-46" title="Installation and Use" />
 Installation and Use
 --------------------
 
@@ -60,7 +68,7 @@ To use Gitdown, edit a text document much like this README.txt.  Then:
 
 The images directory holds images for all documents in the current directory.  You can write documents anywhere on the git tree but if they are not at the root you must tell Gitdown how to create a full image path by setting the SUBDIR symbol (see below).
 
-<A name="toc2-70" title="How it Works" />
+<A name="toc2-71" title="How it Works" />
 How it Works
 ------------
 
@@ -71,6 +79,44 @@ The Gitdown workflow is:
 <center>
 <img src="https://github.com/imatix/gitdown/raw/master/images/README_2.png" alt="2">
 </center>
+    +-------------------+
+    | me.txt            |
+    +-------------------+
+    |   Text file in    +---> Saved in git as source
+    |   Gitdown format  |
+    +---------+---------+
+              |
+              |
+              +----------------------------+
+              |                            |
+              v                            v
+    +---------+---------+        +---------+---------+
+    | me.md             |        | images.html       |
+    +-------------------+        +-------------------+
+    |  Markdown output  |        |   Temporary HTML  |
+    |               cFDA|        |   to feed Ditaa   |
+    +---------+---------+        +---------+---------+
+              |                            |
+              |                            |
+              |                            v
+              |                  +---------+---------+
+              :                  |                   |
+          References             |      Ditaa        |
+              |                  |                {o}|
+              |                  +---------+---------+
+              |                            |
+              |                            |
+              |                            v
+              |                  +---------+---------+
+              |                  | images/me_nnn.png |
+              +----------------->+-------------------+
+                                 |    Image files    |
+                                 |               cFDA|
+                                 +-------------------+
+
+
+                 Figure # - Gitdown workflow
+[/diagram]
 
 1. You edit a text file that contains text and diagrams in a single document.
 2. You process this document with Gitdown to give a Markdown document plus a number of images in an images subdirectory.
@@ -79,7 +125,7 @@ The Gitdown workflow is:
 
 This README acts as an example.
 
-<A name="toc2-125" title="Gitdown Syntax Summary" />
+<A name="toc2-126" title="Gitdown Syntax Summary" />
 Gitdown Syntax Summary
 ---------------------
 
@@ -92,6 +138,7 @@ Gitdown is a pre-processor that adds these syntax elements on top of Markdown:
     .set name=value             Sets Gitdown symbol
     .sub oldval=newval          Replaces oldval by newval in every line
     .toc [top]                  Insert table of contents
+    .pull srcfile@tag[,opts]    Pull a chunk of text from sourcefile
     .end                        Everything past this is ignored
 
     $\(xxx)                     Value of variable, anywhere in text
@@ -124,6 +171,8 @@ Gitdown is a pre-processor that adds these syntax elements on top of Markdown:
 
 The top argument for .toc tells it the top header level in the text. Lower levels are shown horizontally.  E.g. this file has level 2 headers in the text and uses `.toc 1` to get these laid-out on a single row.
 
+The opts argument for .pull can be: 'code' to indicate the results should be indented 4 spaces. An opts of 'left' removes any left margin. A chunk of text is identified by '@tag' anywhere in the line before the chunk, and any other tag signalling the end. '@end' can be used to close any chunk. Tag names must be alphanumeric.
+
 These symbols have special meaning:
 
 * GIT defines the root HTTP URL of the git repository.
@@ -136,7 +185,7 @@ These symbols are predefined by gitdown for you:
 * SELF specifies the input file name without extension.
 * OUTPUT specifies the current output file name,
 
-<A name="toc2-182" title="Markdown Syntax Summary" />
+<A name="toc2-186" title="Markdown Syntax Summary" />
 Markdown Syntax Summary
 -----------------------
 
diff --git a/README.txt b/README.txt
@@ -21,8 +21,9 @@ Gitdown is a simple tool for writing documentation hosted on a github repository
 
 Gitdown is written and maintained by Pieter Hintjens.  Please use the issue [tracker][] for all comments and errata.  This document was published on &date("dddd mmmm, yyyy") at &time(), and generated by the magic of Gitdown from $(INPUT).
 
-This is version 2010.10.11 of Gitdown.  Changelog:
+This is version 2011.03.24 of Gitdown. Changelog:
 
+* 2010.03.24: added .pull command to include chunks from other files.
 * 2010.10.11: don't do symbol substitution in code blocks.
 * 2010.10.09: added .toc token to generate table of contents.
 
@@ -129,6 +130,7 @@ Gitdown is a pre-processor that adds these syntax elements on top of Markdown:
     .set name=value             Sets Gitdown symbol
     .sub oldval=newval          Replaces oldval by newval in every line
     .toc [top]                  Insert table of contents
+    .pull srcfile@tag[,opts]    Pull a chunk of text from sourcefile
     .end                        Everything past this is ignored
 
     $\(xxx)                     Value of variable, anywhere in text
@@ -161,6 +163,8 @@ Gitdown is a pre-processor that adds these syntax elements on top of Markdown:
 
 The top argument for .toc tells it the top header level in the text. Lower levels are shown horizontally.  E.g. this file has level 2 headers in the text and uses `.toc 1` to get these laid-out on a single row.
 
+The opts argument for .pull can be: 'code' to indicate the results should be indented 4 spaces. An opts of 'left' removes any left margin. A chunk of text is identified by '@tag' anywhere in the line before the chunk, and any other tag signalling the end. '@end' can be used to close any chunk. Tag names must be alphanumeric.
+
 These symbols have special meaning:
 
 * GIT defines the root HTTP URL of the git repository.
diff --git a/bin/gitdown b/bin/gitdown
@@ -3,7 +3,7 @@
 #
 #   See README.txt for details.
 #
-#   Copyright (c) 1996-2010 iMatix Corporation
+#   Copyright (c) 1996-2011 iMatix Corporation
 #
 #   This is free software; you can redistribute it and/or modify it under the
 #   terms of the GNU General Public License as published by the Free Software
@@ -28,7 +28,7 @@ push(@INC, $path);
 #   Uses the Perl SFL modules from htmlpp
 require 'sflcvdp.pl';                   #   SFL date picture formatting
 
-$version = "2010.10.09";
+$version = "2011.03.24";
 
 #   Parse and validate provided filename
 die "Syntax: gitdoc textfilename\n"
@@ -65,9 +65,8 @@ $symbols {"PREBRANCH"} = "raw";
 $symbols {"BRANCH"} = "master";
 
 $imgpath = "";
-$line = 0;
-while ($line < @input) {
-    $_ = $input [$line++];
+
+foreach (@input) {
     if (/^\./) {
         #   Process directive
         if (/^\.set\s+(\w+)=(.*)\s*/) {
@@ -120,6 +119,25 @@ while ($line < @input) {
         elsif (/^\.\-/) {
             #   Comment, ignore
         }
+        elsif (/^\.pull (.*)(@[a-zA-Z0-9]+)(,(.*)\s*)?/) {
+            $source = $1;
+            $tag = $2;
+            $opts = $4;
+            die "Can't read $source: $!"
+                unless open (SOURCE, $source);
+            while (<SOURCE>) {
+                if (/$tag/) {
+                    while (<SOURCE>) {
+                        last if /@[a-zA-Z0-9]+/;
+                        chop;
+                        $_ = "    $_" if ($opts eq "code");
+                        s/^    // if ($opts eq "left");
+                        writeln ($_);
+                    }
+                }
+            }
+            close (SOURCE);
+        }
         elsif (/^\.end/) {
             writeln ("(More coming soon...)");
             $EOD = 1;       #   Stop output here
