glyph 0.1.0 → 0.2.0

data/book/text/troubleshooting.glyph

@@ -0,0 +1,179 @@
+This chapter lists the most common error messages that can be returned when running a Glyph command. It does not aim to be an exhaustive list, especially if you =>[#extending|extended] Glyph by creating your own macros or you're embedding Ruby code using the %>[ruby] macro.
+
+tip[As a general rule, more diagnostic information is provided if Glyph is run in =>[#debug_switch|debug mode].]
+
+section[header[Generic Errors]
+
+error_table[
+ref_error[Incorrect macro syntax|
+This error is returned if the parsing of the document (or one of its included files) failed. In 99% of the cases, this means there is an extra or missing macro delimiter somewhere.
+]
+ref_error[Invalid alias: macro '_macro-name_' already exists|
+The alias name supplied to the @macro_alias@ method has already been used for another macro or alias.
+]
+ref_error[Undefined macro '_macro-name_'|
+The document contains a macro that does not exist, i.e. it is not a standard or used-defined =>[#macro_ref|Glyph macro or alias].
+]
+ref_error[An error occurred when generating _file-name_.pdf|
+Returned if Prince could not generate the PDF file or if Prince is not installed. Normally, Prince provides additional details on the specific error(s).
+]
+ref_error[Glyph cannot generate PDF. Please specify a valid tools.pdf_generator setting|
+Returned if the $>[tools.pdf_generator] has not be set to a valid PDF renderer. Currently, the only supported value for this setting is @prince@.
+]
+ref_error[The current directory is not a valid Glyph project|
+Returned if a glyph command was executed outside a valid glyph project directory.
+]
+ref_error[Invalid snippet file|
+The @snippet.yml@ file contains invalid data. Most likely, it does not evaluate to a Ruby @Hash@.
+]
+ref_error[Directory '_directory-name_' is not empty|
+Returned when executing the #>[init] in a directory that is not empty.
+]
+ref_error[File '_file-name_' already exists|
+Returned if the name of an existing file was specified as a parameter for the #>[add].
+]
+]
+] --[End Generic Errors]
+
+
+
+section[header[Command Errors]
+
+error_table[
+
+ref_error[Source file '_source-file_' does not exist|
+Returned if Glyph is running in =>[#lite_mode|lite mode] and the specified source file was not found.
+]
+
+ref_error[Source and destination file are the same|
+Returned if Glyph is running in =>[#lite_mode|lite mode] and you specified the same source and destination files.
+]
+
+ref_error[DirectoryWatcher is not available. Install it with: gem install directory_watcher|
+Returned if =>[#auto_regeneration|auto regeneration] is enabled but the @directory_watcher@ gem in not installed.
+]
+
+ref_error[Document cannot be finalized due to previous errors|
+Returned if one or more errors occurred in the document prevented finalization.
+]
+
+ref_error[Please specify a file name|
+No file name was specified for the #>[add].
+]
+
+ref_error[Output target not specified|
+Returned if no target was specified for the #>[compile] _and_ if the $>[document.output] is not set.
+]
+
+ref_error[Unknown output target '_target-name_'|
+An unsupported output target was specified for the #>[compile]. Only the following output targets are supported:
+- @html@
+- @pdf@
+]
+
+ref_error[Too few/too many arguments|
+Returned if the #>[config] was used with no arguments or more than two arguments respectively.
+]
+
+ref_error[Unknown setting '_setting-name_'|
+The name of an unknown setting was specified for the #>[config].
+]
+]
+] --[End Command Errors]
+
+
+
+section[header[Macro Errors]
+
+The following errors are displayed in the form:
+
+_message_
+-> source: _macro-source_
+-> path: _macro-path_ 
+-> value: _macro-value_
+
+Where:
+* _message_ is the error message.
+* _macro-source_ is the file or snippet where the error occurred.
+* _macro-path_ is the full path to the macro that returned the error, within the document syntax tree, e.g. @document/body/bodymatter/chapter/section/header/&@ if the error occurrent in a snippet within the header of a section in the @bodymatter@ part of the document.
+* _macro-value_ is the value of the macro (shown only if Glyph is running in =>[#debug_switch|debug mode]).
+
+error_table[
+
+ref_error[Macro '_name_' takes up to _x_ parameter(s) (_y_ given)|
+Returned if the macro was called with extra parameters.
+]
+
+ref_error[Macro '_name_' takes at least _x_ parameter(s) (_y_ given)|
+Returned if the macro was called with fewer parameters than expected.
+]
+
+ref_error[Macro '_name_' takes exactly _x_ parameter(s) (_y_ given)|
+Returned if the macro was called with a different number of parameters than.
+]
+
+ref_error[Macro not available when compiling a single file.|
+Returned by the %>[include] if used in =>[#lite_mode|lite mode].
+]
+
+ref_error[Filter macro '_extension_' not available|
+Returned by a filter macro if $>[filters.by_file_extension] is set to @true@, but the extension was not recognized.
+]
+
+ref_error[Invalid regular expression: _regexp_|
+Returned by the %>[match] macro if an invalid regular expression was supplied.
+]
+
+ref_error[Macro '_name_' takes no parameters (_x_ given)|
+Returned if the macro was called with parameters but none are requested.
+]
+
+ref_error[No highlighter installed. Please run: gem install coderay|
+Returned by the %>[highlight] macro if no highlighters are installed.
+]
+
+ref_error[CodeRay highlighter not installed. Please run: gem install coderay|
+Returned by the %>[highlight] macro if $>[highlighters.current] is set to @coderay@ but &[coderay] is not installed.
+]
+
+ref_error[UltraViolet highlighter not installed. Please run: gem install ultraviolet|
+Returned by the %>[highlight] macro if $>[highlighters.current] is set to @ultraviolet@ but &[uv] is not installed.
+]
+
+ref_error[Mutual inclusion|
+Returned if a catch-22 situation occurs with macro inclusion, for example if the body of a snippet includes a reference to the same snippet.
+]
+ref_error[Snippet '_snippet-id_' does not exist|
+Returned by the %>[snippet] if an invalid snippet was supplied.
+]
+ref_error[File '_file-name_' not found|
+Returned by the %>[include] if an invalid file was supplied.
+]
+ref_error[Filter macro '_macro-name_' not found|
+Returned by the %>[include] macro if the $>[filters.by_file_extension] is set to @true@ but the file extension of the included file is not recognized as a filter macro.
+]
+ref_error[RedCloth gem not installed. Please run: gem insall RedCloth|
+Returned by the %>[textile] if the RedCloth gem is not installed.
+]
+ref_error[No MarkDown converter installed. Please run: gem insall bluecloth|
+Returned by the %>[markdown] if no valid Markdown converter gem is installed. 
+
+Glyph checks for: BlueCloth, Maruku, Kramdown and RDiscount.
+]
+ref_error[Image/Figure not found|
+Retured by the %>[img] or the %>[fig] respectively, if the specified image file could not be found within the @images/@ folder.
+]
+ref_error[Bookmark '_bookmark-name_' already exists|
+Returned by the %>[anchor] or by the %>[header] if the anchor ID supplied as parameter has already been used in the document.
+]
+ref_error[Bookmark '_bookmark-name_' already exists|
+Returned by the %>[link] if the anchor ID supplied as parameter has not been used in the document.
+]
+ref_error[Stylesheet '_file-name_' not found|
+Returned by the %>[style] if the @.css@ or @.sass@ file supplied as parameter was not found in the @styles/@ directory.
+]
+ref_error[Haml is not installed. Please run: gem install haml|
+Returned by the %>[style] if a @.sass@ file was passed as parameter but the Haml gem is not installed.
+]
+]
+] --[End Macro Errors]

data/config.yml

@@ -2,8 +2,10 @@
   :source: 'document.glyph'
   :author: ""
   :title: ""
+  :subtitle: ""
   :filename: ""
-  :output: ""
+  :draft: false
+  :output: 'html'
   :output_targets: [:html, :pdf]
 :structure:
   :hidden:
@@ -14,9 +16,7 @@
     - :colophon
     - :promotion
   :special:
-    - :preface
     - :foreword
-    - :introduction
     - :acknowledgement
     - :prologue
     - :epilogue
@@ -55,9 +55,21 @@
     - :index
     - :lot
     - :lof
-:pdf_renderer: 'prince'
+:tools:
+  :pdf_generator: 'prince'
+:highlighters:
+  :target: 'html'
+  :current: 'coderay'
+  :coderay:
+    # See options at http://coderay.rubychan.de/doc/classes/CodeRay/Encoders/HTML.html
+    :css: :class 
+  :ultraviolet:
+    :line_numbers: false
+    :theme: 'blackboard'
 :filters:
   :by_file_extension: true
   :target: 'html'
+  :markdown:
+    :converter: 'bluecloth'
   :redcloth:
     :restrictions: []

data/glyph.gemspec

@@ -5,20 +5,24 @@
 
 Gem::Specification.new do |s|
   s.name = %q{glyph}
-  s.version = "0.1.0"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Fabio Cevasco"]
-  s.date = %q{2010-04-09}
+  s.date = %q{2010-05-09}
   s.default_executable = %q{glyph}
   s.description = %q{Glyph is a framework for structured document authoring.}
   s.email = %q{h3rald@h3rald.com}
   s.executables = ["glyph"]
   s.extra_rdoc_files = [
-    "README.textile"
+    "LICENSE.textile",
+     "README.textile"
   ]
   s.files = [
-    "README.textile",
+    "AUTHORS.textile",
+     "CHANGELOG.textile",
+     "LICENSE.textile",
+     "README.textile",
      "Rakefile",
      "VERSION",
      "bin/glyph",
@@ -31,17 +35,25 @@ Gem::Specification.new do |s|
      "book/output/html/images/glyph.png",
      "book/output/html/images/glyph.svg",
      "book/output/pdf/glyph.pdf",
+     "book/script/authors",
+     "book/script/changelog",
+     "book/script/compile.rb",
+     "book/script/license",
+     "book/script/prof",
+     "book/script/prof_results.htm",
+     "book/script/readme",
      "book/snippets.yml",
-     "book/styles/css3.css",
-     "book/styles/default.css",
-     "book/text/authoring.textile",
-     "book/text/extending.textile",
-     "book/text/getting_started.textile",
-     "book/text/introduction.textile",
-     "book/text/ref_commands.textile",
-     "book/text/ref_config.textile",
-     "book/text/ref_macros.textile",
-     "book/text/troubleshooting.textile",
+     "book/text/acknowledgement.glyph",
+     "book/text/authoring.glyph",
+     "book/text/changelog.glyph",
+     "book/text/extending.glyph",
+     "book/text/getting_started.glyph",
+     "book/text/introduction.glyph",
+     "book/text/license.glyph",
+     "book/text/ref_commands.glyph",
+     "book/text/ref_config.glyph",
+     "book/text/ref_macros.glyph",
+     "book/text/troubleshooting.glyph",
      "config.yml",
      "document.glyph",
      "glyph.gemspec",
@@ -53,6 +65,7 @@ Gem::Specification.new do |s|
      "lib/glyph/glyph_language.treetop",
      "lib/glyph/interpreter.rb",
      "lib/glyph/macro.rb",
+     "lib/glyph/macro_validators.rb",
      "lib/glyph/node.rb",
      "lib/glyph/system_extensions.rb",
      "macros/common.rb",
@@ -60,6 +73,7 @@ Gem::Specification.new do |s|
      "macros/html/block.rb",
      "macros/html/inline.rb",
      "macros/html/structure.rb",
+     "spec/files/article.glyph",
      "spec/files/container.textile",
      "spec/files/document.glyph",
      "spec/files/document_with_toc.glyph",
@@ -73,15 +87,39 @@ Gem::Specification.new do |s|
      "spec/lib/glyph_spec.rb",
      "spec/lib/interpreter_spec.rb",
      "spec/lib/macro_spec.rb",
+     "spec/lib/macro_validators_spec.rb",
      "spec/lib/node_spec.rb",
      "spec/macros/filters_spec.rb",
      "spec/macros/macros_spec.rb",
+     "spec/macros/textile_spec.rb",
      "spec/spec_helper.rb",
      "spec/tasks/generate_spec.rb",
      "spec/tasks/load_spec.rb",
      "spec/tasks/project_spec.rb",
-     "styles/css3.css",
+     "styles/coderay.css",
      "styles/default.css",
+     "styles/pagination.css",
+     "styles/ultraviolet/active4d.css",
+     "styles/ultraviolet/all_hallows_eve.css",
+     "styles/ultraviolet/amy.css",
+     "styles/ultraviolet/blackboard.css",
+     "styles/ultraviolet/brilliance_black.css",
+     "styles/ultraviolet/brilliance_dull.css",
+     "styles/ultraviolet/cobalt.css",
+     "styles/ultraviolet/dawn.css",
+     "styles/ultraviolet/eiffel.css",
+     "styles/ultraviolet/espresso_libre.css",
+     "styles/ultraviolet/idle.css",
+     "styles/ultraviolet/iplastic.css",
+     "styles/ultraviolet/lazy.css",
+     "styles/ultraviolet/mac_classic.css",
+     "styles/ultraviolet/magicwb_amiga.css",
+     "styles/ultraviolet/pastels_on_dark.css",
+     "styles/ultraviolet/slush_poppies.css",
+     "styles/ultraviolet/spacecadet.css",
+     "styles/ultraviolet/sunburst.css",
+     "styles/ultraviolet/twilight.css",
+     "styles/ultraviolet/zenburnesque.css",
      "tasks/generate.rake",
      "tasks/load.rake",
      "tasks/project.rake"
@@ -89,15 +127,17 @@ Gem::Specification.new do |s|
   s.homepage = %q{http://www.h3rald.com/glyph/}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.5}
+  s.rubygems_version = %q{1.3.6}
   s.summary = %q{Glyph -- A Ruby-powered Document Authoring Framework}
   s.test_files = [
     "spec/macros/filters_spec.rb",
+     "spec/macros/textile_spec.rb",
      "spec/macros/macros_spec.rb",
      "spec/lib/interpreter_spec.rb",
      "spec/lib/commands_spec.rb",
      "spec/lib/node_spec.rb",
      "spec/lib/macro_spec.rb",
+     "spec/lib/macro_validators_spec.rb",
      "spec/lib/config_spec.rb",
      "spec/lib/glyph_spec.rb",
      "spec/lib/document_spec.rb",
@@ -116,23 +156,44 @@ Gem::Specification.new do |s|
       s.add_runtime_dependency(%q<extlib>, [">= 0.9.12"])
       s.add_runtime_dependency(%q<treetop>, [">= 0.4.3"])
       s.add_runtime_dependency(%q<rake>, [">= 0.8.7"])
-      s.add_development_dependency(%q<rspec>, [">= 0"])
-      s.add_development_dependency(%q<yard>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, [">= 1.1.11"])
+      s.add_development_dependency(%q<yard>, [">= 1.5.4"])
+      s.add_development_dependency(%q<jeweler>, ["= 1.4.0"])
+      s.add_development_dependency(%q<directory_watcher>, [">= 1.3.2"])
+      s.add_development_dependency(%q<haml>, [">= 2.2.3"])
+      s.add_development_dependency(%q<RedCloth>, [">= 4.2.3"])
+      s.add_development_dependency(%q<bluecloth>, [">= 2.0.7"])
+      s.add_development_dependency(%q<coderay>, [">= 0.9.3"])
+      s.add_development_dependency(%q<ruby-prof>, [">= 0.8.1"])
     else
       s.add_dependency(%q<gli>, [">= 0.3.1"])
       s.add_dependency(%q<extlib>, [">= 0.9.12"])
       s.add_dependency(%q<treetop>, [">= 0.4.3"])
       s.add_dependency(%q<rake>, [">= 0.8.7"])
-      s.add_dependency(%q<rspec>, [">= 0"])
-      s.add_dependency(%q<yard>, [">= 0"])
+      s.add_dependency(%q<rspec>, [">= 1.1.11"])
+      s.add_dependency(%q<yard>, [">= 1.5.4"])
+      s.add_dependency(%q<jeweler>, ["= 1.4.0"])
+      s.add_dependency(%q<directory_watcher>, [">= 1.3.2"])
+      s.add_dependency(%q<haml>, [">= 2.2.3"])
+      s.add_dependency(%q<RedCloth>, [">= 4.2.3"])
+      s.add_dependency(%q<bluecloth>, [">= 2.0.7"])
+      s.add_dependency(%q<coderay>, [">= 0.9.3"])
+      s.add_dependency(%q<ruby-prof>, [">= 0.8.1"])
     end
   else
     s.add_dependency(%q<gli>, [">= 0.3.1"])
     s.add_dependency(%q<extlib>, [">= 0.9.12"])
     s.add_dependency(%q<treetop>, [">= 0.4.3"])
     s.add_dependency(%q<rake>, [">= 0.8.7"])
-    s.add_dependency(%q<rspec>, [">= 0"])
-    s.add_dependency(%q<yard>, [">= 0"])
+    s.add_dependency(%q<rspec>, [">= 1.1.11"])
+    s.add_dependency(%q<yard>, [">= 1.5.4"])
+    s.add_dependency(%q<jeweler>, ["= 1.4.0"])
+    s.add_dependency(%q<directory_watcher>, [">= 1.3.2"])
+    s.add_dependency(%q<haml>, [">= 2.2.3"])
+    s.add_dependency(%q<RedCloth>, [">= 4.2.3"])
+    s.add_dependency(%q<bluecloth>, [">= 2.0.7"])
+    s.add_dependency(%q<coderay>, [">= 0.9.3"])
+    s.add_dependency(%q<ruby-prof>, [">= 0.8.1"])
   end
 end
 

data/lib/glyph.rb

@@ -1,6 +1,6 @@
 # Copyright (c) 2009-2010 Fabio Cevasco
 # website: http://www.h3rald.com/glyph
-# license: BSD
+# license: MIT
 
 require 'rubygems'
 require 'pathname'
@@ -13,47 +13,76 @@ require 'rake'
 # Glyph is a Rapid Document Authoring Framework able to produce structured documents 	effortlessly.
 module Glyph
 
+	# The directory containing Glyph library files
 	LIB = Pathname(__FILE__).dirname.expand_path/'glyph'
 
+	# The directory containing the full Glyph installation
 	HOME = LIB/'../../'
 
+	# The directory containing all Glyph tests
+	SPEC_DIR = Pathname(__FILE__).dirname.expand_path/'../spec'
+
+	# The directory containing all Glyph Rake tasks
+	TASKS_DIR = Pathname(__FILE__).dirname.expand_path/'../tasks'
+
 	require LIB/'system_extensions'
 	require LIB/'config'
 	require LIB/'node'
 	require LIB/'document'
 	require LIB/'glyph_language'
+	require LIB/'macro_validators'
 	require LIB/'macro'
 	require LIB/'interpreter'
 
-	VERSION = file_load HOME/'VERSION'
-
-	SPEC_DIR = Pathname(__FILE__).dirname.expand_path/'../spec'
-
-	TASKS_DIR = Pathname(__FILE__).dirname.expand_path/'../tasks'
+	class Error < RuntimeError; end
+	class SyntaxError < Error; end
+	class MacroError < Error; end
+	class MutualInclusionError < MacroError; end
 
-	APP = Rake.application
+	# The current version of Glyph
+	VERSION = file_load(HOME/'VERSION').strip
 
+	# All the currently-loaded snippets
 	SNIPPETS = {}
 
+	# All the currently-loaded macros
 	MACROS = {}
 
-	TODOS = []
+	begin
+		unless const_defined? :MODE then
+			# Glyph's modes: debug/lite/test
+			MODE = {:debug => false, :lite => false, :test => false, :library => false} 
+		end
+	rescue
+	end
 
-	ERRORS = []
+	# The main document being generated by Glyph
+	@@document = nil
 
-	# Returns true if Glyph is running in test mode
-	def self.testing?
-		const_defined? :TEST_MODE rescue false
+	(class << self; self; end).instance_eval do
+		["test", "lite", "debug", "library"].each do |mode|
+			define_method((mode+"?").to_sym) do
+				MODE[mode.to_sym]
+			end
+			define_method((mode+"_mode=")) do |m|
+				MODE[mode.to_sym] = m
+			end
+		end
 	end
 
-	PROJECT = (Glyph.testing?) ? Glyph::SPEC_DIR/"test_project" : Pathname.new(Dir.pwd)
+	# The directory of the current Glyph project.
+	PROJECT = (Glyph.test?) ? Glyph::SPEC_DIR/"test_project" : Pathname.new(Dir.pwd)
 
+	# Glyph's configuration
 	CONFIG = Glyph::Config.new :resettable => true, :mutable => false
 
 	home_dir = Pathname.new(RUBY_PLATFORM.match(/win32|mingw/) ? ENV['HOMEPATH'] : ENV['HOME'])
-	SYSTEM_CONFIG = Glyph::Config.new(:file => HOME/'config.yml')
-	GLOBAL_CONFIG = Glyph.testing? ? Glyph::Config.new(:file => SPEC_DIR/'.glyphrc') : Glyph::Config.new(:file => home_dir/'.glyphrc')
-	PROJECT_CONFIG = Glyph::Config.new(:file => PROJECT/'config.yml')
+	SYSTEM_CONFIG = 
+		Glyph::Config.new(:file => HOME/'config.yml')
+	GLOBAL_CONFIG = 
+		Glyph.test? ? Glyph::Config.new(:file => SPEC_DIR/'.glyphrc') : Glyph::Config.new(:file => home_dir/'.glyphrc')
+	PROJECT_CONFIG = 
+		Glyph::Config.new(:file => PROJECT/'config.yml', :resettable => true) rescue Glyph::Config.new(:resettable => true, :mutable => true)
 
 	# Loads all Rake tasks
 	def self.setup
@@ -62,34 +91,72 @@ module Glyph
 		end	
 	end
 
+	# Used to access @@document 
+	def self.document
+		@@document
+	end
+
+	# Used to set @@document 
+	def self.document=(document)
+		@@document = document
+	end
+
+	# Returns the value of a configuration setting
+	def self.[](setting)
+		Glyph::CONFIG.get(setting)
+	end
+
 	# Overrides a configuration setting
-	# @param setting [String, Symbol] the configuration setting to change
+	# @param [String, Symbol] setting the configuration setting to change
 	# @param value the new value
-	def self.config_override(setting, value)
+	def self.[]=(setting, value)
 		PROJECT_CONFIG.set setting, value
-		reset_config
+		self.config_refresh
 	end
 
-	# Resets Glyph configuration
-	def self.reset_config
+	# Restores Glyph configuration (keeping all overrides and project settings)
+	def self.config_refresh
 		CONFIG.merge!(SYSTEM_CONFIG.merge(GLOBAL_CONFIG.merge(PROJECT_CONFIG)))
 	end
 
+	# Resets Glyph configuration (removing all overrides and project settings)
+	def self.config_reset
+		Glyph::CONFIG.reset
+		Glyph::PROJECT_CONFIG.reset
+		self.config_refresh
+	end
+
 	# Returns true if the PROJECT constant is set to a valid Glyph project directory
 	def self.project?
-		children = ["styles", "text", "output", "snippets.yml", "config.yml", "document.glyph"].sort
+		children = ["text", "output", "snippets.yml", "config.yml", "document.glyph"].sort
 		actual_children = PROJECT.children.map{|c| c.basename.to_s}.sort 
 		(actual_children & children) == children
 	end
 
-	# Enables a Rake task
-	# @param task the task to enable
+	# Resets Glyph completely, i.e.:
+	# * Re-enables all Glyph Rake tasks
+	# * Resets the configuration to system defaults
+	# * Clears macros and snippets
+	def self.reset
+		self.enable_all
+		self.config_reset
+		MACROS.clear
+		SNIPPETS.clear
+	end
+
+	# Reenables all Glyph Rake tasks
+	def self.enable_all
+		Rake::Task.tasks.each {|t| t.reenable }
+	end
+
+	# Reenables a Rake task
+	# @param [Symbol, String] task the task to enable
 	def self.enable(task)
 		Rake::Task[task].reenable
 	end
 
 	# Reenables and runs a Rake task
-	# @param task the task to enable
+	# @param [Symbol, String] task the task to run
 	# @param *args the task arguments
 	def self.run!(task, *args)
 		Rake::Task[task].reenable
@@ -97,32 +164,98 @@ module Glyph
 	end
 
 	# Runs a Rake task
-	# @param task the task to enable
+	# @param [Symbol, String] task the task to run
 	# @param *args the task arguments
 	def self.run(task, *args)
 		Rake::Task[task].invoke *args
 	end
 
 	# Defines a new macro
-	# @param name [Symbol, String] the name of the macro
+	# @param [Symbol, String] name the name of the macro
 	def self.macro(name, &block)
-		MACROS[name] = block
+		MACROS[name.to_sym] = block
 	end
 
 	# Defines an alias for an existing macro
-	# @param [Hash] pair the single-key hash defining the alias
+	# @param [Hash] text the single-key hash defining the alias
 	# @example
 	# 	{:old_name => :new_name}
 	def self.macro_alias(pair)
 		name = pair.keys[0].to_sym
 		found = MACROS[name]
 		if found then
-			warning "Invalid alias: macro '#{name}' already exists."
+			self.warning "Invalid alias: macro '#{name}' already exists."
 			return
 		end
 		MACROS[name] = MACROS[pair.values[0].to_sym]
 	end
-	
+
+	# Compiles a single Glyph file
+	# @param [String] src the full or relative path to the source file
+	# @param [String] out the full or relative path to the output file
+	def self.compile(src, out=nil)
+		pwd = Dir.pwd
+		Dir.chdir Pathname.new(src).parent.to_s
+		begin
+			require 'glyph/commands'
+			self[:quiet] = true
+			self.library_mode = true
+			GLI.run ["compile", src.to_s, out].compact	
+		rescue Exception => e
+			raise 
+		ensure
+			Dir.chdir pwd
+			self.library_mode = false
+			self.lite_mode = false
+			self[:quiet] = false
+		end
+	end
+
+	# Converts a text containing Glyph markup language into the current Glyph output target.
+	#
+	# *Note* Only 'html' is supported as output target for now. 
+	# @param [String] text the text to convert
+	# @return [String] the converted text
+	# @example
+	# 	require 'glyph'
+	# 	Glyph.filter "section[header[Test]\nA Test section...]"
+	def self.filter(text)
+		self.lite_mode = true
+		self.enable_all
+		result = ""
+		begin
+			self[:quiet] = true
+			self.library_mode = true
+			self.run 'load:all'
+			result = Interpreter.new(text).document.output
+		rescue Exception => e
+			raise 
+		ensure
+			self.lite_mode = false
+			self.library_mode = false
+			self[:quiet] = false
+		end
+		result
+	end
+
+	# Prints a message
+	# @param [String] message the message to print
+	def self.info(message)
+		puts "#{message}" unless Glyph[:quiet]
+	end
+
+	# Prints a warning
+	# @param [String] message the message to print
+	def self.warning(message)
+		puts "--> warning: #{message}" unless Glyph[:quiet]
+	end
+
+	# Prints an error
+	# @param [String] message the message to print
+	def self.error(message)
+		puts "==> error: #{message}" unless Glyph[:quiet]
+	end
+
 end
 
 Glyph.setup