Comments; added a license text file

.gitignore

@@ -1,3 +1,4 @@
 .DS_Store
 doc
 *.tmproj
+dompdf

include/class.scblock.php

@@ -7,10 +7,9 @@
 
 class ScBlock
 {
-    // ========================================================================
-    // Private properties
-    // [All below are grouped under "Private properties"]
-    // ========================================================================
+    /* ======================================================================
+     * Private properties
+     * ====================================================================== */
 
     var $_data;
     var $valid = FALSE;
@@ -116,12 +115,13 @@ class ScBlock
 
     // ========================================================================
     // Constructor
-    // [All below are grouped under "Constructor"]
     // ========================================================================
 
     /*
      * Constructor: ScBlock()
      * Yes.
+     * 
+     * [In group "Constructor"]
      */
 
     function ScBlock($str)
@@ -226,7 +226,12 @@ function parseTag($tags)
         $valid_tags = array_keys($Sc->Options['tags']);
         foreach ($tag_list as $tag)
         {
-            preg_match('~^(?:in )?group(?:ed(?: under)?)? (?:")?(.*?)(?:")?$~i',
+            // Match:
+            // - [In [the]] group X
+            // - [[filed] under [the]] group X
+            // - Group[ed [under]] X
+            // - Group X
+            preg_match('~^(?:in (?:the )?|(?:(?:filed )?under (?:the )?))?group(?:ed(?: under)?)? (?:")?(.*?)(?:")?$~i',
               $tag, $m);
             if (count($m) > 0)
             {

include/class.scproject.php

@@ -34,47 +34,70 @@ class ScProject
     /*
      * Property: $name
      * The name of the project.
+     * 
+     * Description:
+     *   This is private property. To retrieve the name, use `getName()`.
+     *   The name of the block is gathered from the block
+     *   content and therefore should not be set by hand.
+     * 
+     * [Grouped under "Private properties"]
      */
 
     var $name;
 
     /*
-     * Group: Temporary properties
-     */
-
-    /*
-     * Property: $_ancestry
+     * Property: $__ancestry
      * Temporary property.
      * 
-     * Used by [[register()]].
+     * Description:
+     *   This is a temporary property used by [[register()]].
+     * 
+     * [Grouped under "Private properties"]
      */
 
     var $__ancestry = array();
 
-    /*
-     * Property: $data
-     * Storage for all blocks associated with the project.
-     *
+    /* Property: $data['blocks']
+     * All the blocks.
+     * 
+     * Description:
+     *   This is an array of [[ScBlock]]s. It lists all the blocks in
+     *   the project.
+     * 
+     *   This is a read-only property. To add blocks, use [[register()]].
+     * 
      * Sample data:
-     *   
-     *     $data = array
-     *     (
-     *       'blocks' => array( ScBlock, ScBlock, ScBlock, ... ),
-     *       'tree'   => array( ScBlock, ScBlock, ScBlock, ... ),
-     *       'home'   => ScBlock
-     *     );
+     *     array( ScBlock, ScBlock, ScBlock, ... )
+     * 
+     * [Read-only, grouped under "Data properties"]
+     */
+
+    /* Property: $data['home']
+     * The home page.
      * 
      * Description:
-     *   This is an associative array with the following keys below.
-     *
-     *   blocks   - Array of [[ScBlock]]s. The list of blocks.
-     *   home     - [[ScBlock]] instance. the main root block (i.e., home page)
-     *   tree     - Array of [[ScBlock]]s. The list of "root" blocks
+     *   This is an [[ScBlock]] instance reference to the main root node,
+     *   the home page.
      * 
-     * Usage:
-     *   - To add blocks, use [[register()]].
+     *   This is a read-only property. To add blocks, use [[register()]].
+     * 
+     * [Read-only, grouped under "Data properties"]
      */
 
+    /* Property: $data['tree']
+     * The list of second-level blocks.
+     * 
+     * Description:
+     *   This lists all blocks that are children of the home page. Synonymous
+     *   to `$data['home']->getChildren()`.
+     * 
+     *   This is a read-only property. To add blocks, use [[register()]].
+     * 
+     * Sample data:
+     *     array( ScBlock, ScBlock, ScBlock, ... )
+     * 
+     * [Read-only, grouped under "Data properties"]
+     */
     var $data = array
     (
         'blocks' => array(),
@@ -98,6 +121,8 @@ class ScProject
      * 
      * References:
      *   This is called on startup via [[Scribe::Scribe()]].
+     * 
+     * [Grouped under "Constructor"]
      */
 
     function ScProject(&$Sc)

include/class.scribe.php

@@ -5,23 +5,57 @@
 class Scribe
 {
     var $Project;
+    /*
+     * Property: $Readers
+     * Key/value pairs of file reader drivers.
+     * 
+     * Description:
+     *   Uhm
+     * 
+     * [Read-only]
+     */
     var $Readers = array();
+
+    /*
+     * Property: $Outputs
+     * Key/value pairs of output drivers.
+     * 
+     * Description:
+     *   - To register an output driver to use,
+     *     use [[loadOutputDriver()]].
+     * 
+     * [Read-only]
+     */
     var $Outputs = array();
 
     /* Property: $Options['type_keywords']
      * Yay
+     * 
+     * [Grouped under "Options"]
      */
+
     /* Property: $Options['block_types']
      * Yay
+     * 
+     * [Grouped under "Options"]
      */
+
     /* Property: $Options['file_specs']
      * Yay
+     * 
+     * [Grouped under "Options"]
      */
+
     /* Property: $Options['valid_tags']
      * Yay
+     * 
+     * [Grouped under "Options"]
      */
+
     /* Property: $Options['tags']
      * Auto-set
+     * 
+     * [Grouped under "Options"]
      */
     var $Options = array
     (
@@ -126,7 +160,7 @@ function Scribe()
 
         $this->Project = new ScProject($this);
         $this->Readers['default'] = new DefaultReader($this);
-        $this->Outputs['html']    = new HtmlOutput($this);
+        $this->loadOutputDriver('html');
 
         // Initialize $Options['tags']
         $this->Options['tags'] = array();
@@ -136,6 +170,32 @@ function Scribe()
             { $this->Options['tags'][strtolower($k)] = strtolower($v); }
     }
 
+    /*
+     * Function: loadOutputDriver()
+     * Loads an output driver.
+     *
+     * Usage:
+     *     $this->loadOutput($driver[, $use])
+     *
+     * Returns:
+     *   TRUE on success, FALSE on failure.
+     */
+
+    function loadOutputDriver($driver, $use = TRUE)
+    {
+        // TODO: BP: This should make sure $driver is sanitized
+        require_once SCRIBE_PATH . DS . 'include' . DS . "output.$driver.php";
+        $classname = "{$driver}Output";
+
+        if (!class_exists($classname))
+            { return FALSE; }
+
+        if ($use)
+            { $this->Outputs[$driver] = new $classname($this); }
+
+        return TRUE;
+    }
+
     /*
      * Function: findConfigFile()
      * Tries to find the configuration file.

mit-license.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2009, Rico Sta. Cruz.
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

ss

@@ -2,4 +2,4 @@
 
 # Change this, and put this file in ~/bin or somewhere.
 SCRIBE_PATH=~/Projects/scribe/src
-php $SCRIBE_PATH/scribe.php $@
+php -f $SCRIBE_PATH/scribe.php -- $@