glyph 0.3.0 → 0.4.0

data/.gitignore

@@ -0,0 +1,7 @@
+.DS_Store
+thumbs.db
+.rvmrc*
+.bundle
+Gemfile.lock
+book/output
+book/output/*

data/AUTHORS.textile

@@ -1,8 +1,9 @@
-Glyph was designed and developed by <a href="http://www.h3rald.com">Fabio Cevasco</a> (h3rald).
-
-Special thanks to the following individuals who contributed to Glyph by reporting and fixing issues and/or proposing and implementing new features:
-* <a href="http://www.jabbslad.com">Jamie Atkinson</a> (Jabbslad)
-* <a href="http://koraktor.github.com">Sebastian Staudt</a> (koraktor)
-
-
+<p>Glyph was designed and developed by <a href="http://www.h3rald.com">Fabio Cevasco</a> (h3rald).</p>
+<p>Special thanks to the following individuals who contributed to Glyph by reporting and fixing issues and/or proposing and implementing new features:</p>
+<ul>
+	<li><a href="http://www.jabbslad.com">Jamie Atkinson</a> (Jabbslad)</li>
+	<li><a href="http://koraktor.github.com">Sebastian Staudt</a> (koraktor)</li>
+	<li><a href="http://balcone.eveel.ru">Dmitry A. Ustalov</a> (eveel)</li>
+	<li><a href="http://www.stuartellis.eu">Stuart Ellis</a> (stuartellis)</li>
+</ul>
     

data/CHANGELOG.textile

@@ -4,9 +4,90 @@
 
 
 	<div class="section">
-<h2 id="h_1">v0.3.0 &ndash; June 13th 2010</h2>
+<h2 id="h_1">v0.4.0 &ndash; September 3th 2010</h2>
 <div class="section">
-<h3 id="h_2">27 Features Implemented</h3>
+<h3 id="h_2">13 Features Implemented</h3>
+<table><tr><th>ID</th>
+					<th>Description</th></tr>
+				
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/40">#40</a></td>
+		<td><p>A new stats command can be used to display statistics about project files, snippets, macros, bookmarks and links.</p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/73">#73</a></td>
+		<td><p>It is now possible to validate online <span class="caps">HTTP</span> links.</p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/112">#112</a></td>
+		<td><p>It is now possible to use <em>wkhtmltopdf</em> instead of Prince to generate <span class="caps">PDF</span> files from <span class="caps">HTML</span> files.</p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/114">#114</a></td>
+		<td><p>It is now possible to generate documents comprised of multiple files (topics).</p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/115">#115</a></td>
+		<td><p>It is now possible to define layouts (used when generating multi-file outputs) using Glyph macros.</p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/120">#120</a></td>
+		<td><p>It is now possible to compile your project to a single HTML5 file (<code>html5</code> output) or multiple files (<code>web5</code> output)</p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/135">#135</a></td>
+		<td><p>Stylesheets can now be linked and imported as well as embedded.</p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/138">#138</a></td>
+		<td><p><code>web</code> and <code>web5</code> output formats inherit <code>html</code> macros.</p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/142">#142</a></td>
+		<td><p>A new navigation macro can be used in <code>web</code> and <code>web5</code> outputs to navigate through topics.</p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/143">#143</a></td>
+		<td><p>A topic-based <span class="caps">TOC</span> is generated when compiling to <code>web</code> or <code>web5</code></p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/144">#144</a></td>
+		<td><p>Two new validators are now available to check whether a macro has (or doesn&#8217;t have) a certain ancestor: <code>within</code> and <code>not_within</code>.</p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/147">#147</a></td>
+		<td><p>The default stylesheets provided by Glyph are now compatible with HTML5 outputs (html5 and web5).</p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/148">#148</a></td>
+		<td><p>It is now possible to create custom tasks and commands to extend Glyph functionality.</p></td></tr></table>
+
+</div>
+	
+	
+		<div class="section">
+<h3 id="h_3">7 Bugs Fixed</h3>
+<table><tr><th>ID</th>
+					<th>Description</th></tr>
+				
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/133">#133</a></td>
+		<td><p>Added <span class="caps">HTML</span> charset to Glyph documents (utf-8).</p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/136">#136</a></td>
+		<td><p>Moved utility functions to separate <code>Glyph::Utils</code> module.</p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/139">#139</a></td>
+		<td><p>Heavily restructured Glyph configuration.</p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/140">#140</a></td>
+		<td><p>Added <code>Glyph::Macro::Helpers</code> module to avoid code duplication in macros for different output formats.</p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/141">#141</a></td>
+		<td><p>Prevented non-rb files to be loaded as macros.</p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/145">#145</a></td>
+		<td><p>Dotfiles are now ignored by init command.</p></td></tr>
+		
+	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/167">#167</a></td>
+		<td><p>Fixed <span class="caps">PDF</span> book download links.</p></td></tr></table>
+
+</div>
+
+</div>
+
+	<div class="section">
+<h2 id="h_4">v0.3.0 &ndash; June 13th 2010</h2>
+<div class="section">
+<h3 id="h_5">13 Features Implemented</h3>
 <table><tr><th>ID</th>
 					<th>Description</th></tr>
 				
@@ -42,7 +123,7 @@
 		<td><p>A new alias macro has been implemented to create macro aliases.</p></td></tr>
 		
 	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/128">#128</a></td>
-		<td><p>A blacklist for <span class="caps">XML</span> tags has been exposed via the language.options.xml_blacklist setting.</p></td></tr>
+		<td><p>A blacklist for <span class="caps">XML</span> tags has been exposed via the <code>language.options.xml_blacklist</code> setting.</p></td></tr>
 		
 	<tr><td><a href="http://github.com/h3rald/glyph/issues/closed#issue/129">#129</a></td>
 		<td><p>The include macro can now be used in lite mode, it can evaluate ruby files and requires relative paths.</p></td></tr>
@@ -54,7 +135,7 @@
 	
 	
 		<div class="section">
-<h3 id="h_3">7 Bugs Fixed</h3>
+<h3 id="h_6">3 Bugs Fixed</h3>
 <table><tr><th>ID</th>
 					<th>Description</th></tr>
 				
@@ -73,9 +154,9 @@
 </div>
 
 	<div class="section">
-<h2 id="h_4">v0.2.0 &ndash; May 9th 2010</h2>
+<h2 id="h_7">v0.2.0 &ndash; May 9th 2010</h2>
 <div class="section">
-<h3 id="h_5">23 Features Implemented</h3>
+<h3 id="h_8">11 Features Implemented</h3>
 <table><tr><th>ID</th>
 					<th>Description</th></tr>
 				
@@ -117,7 +198,7 @@
 	
 	
 		<div class="section">
-<h3 id="h_6">17 Bugs Fixed</h3>
+<h3 id="h_9">8 Bugs Fixed</h3>
 <table><tr><th>ID</th>
 					<th>Description</th></tr>
 				
@@ -151,7 +232,7 @@
 </div>
 
 	<div class="section">
-<h2 id="h_7">v0.1.0 &ndash; April 8th 2010</h2>
+<h2 id="h_10">v0.1.0 &ndash; April 8th 2010</h2>
 Initial release.
 
 </div>

data/LICENSE.textile

@@ -1,5 +1,4 @@
-Copyright (c) 2010 **Fabio Cevasco**, <a href="http://www.h3rald.com">http://www.h3rald.com</a>  
-
+<p>Copyright &copy; 2010 <strong>Fabio Cevasco</strong>, <a href="http://www.h3rald.com">http://www.h3rald.com</a></p> 
 
 <div class="code">
 <pre>

data/README.textile

@@ -1,58 +1,27 @@
-
 Glyph is a _Rapid Document Authoring Framework_. 
 
-With Glyph, you can manage your documents tidily in _projects_ and generate deliverables in different formats such as HTML or PDF (through <a href="http://www.princexml.com/">Prince</a>).
-
-<div class="section">
+With Glyph, creating and maintaining any kind of document becomes as easy as... _programming_. Glyph enables you to minimize text duplication, focus on content rather than presentation, manage references seamlessly and automate tedious tasks through a simple but effective macro language, specifically geared towards customization and extensibility.
+	
+	<div class="section">
 <h2 id="h_1">Main Features</h2>
-Glyph comes with its very own macro system to perform a wide variety of advanced tasks:
-* Generate block-level HTML tags not commonly managed by lightweight markups, like @head@, @body@, @div@ and @table@.
-* Create and validate internal and external links.
-* Include and validate images and figures.
-* Automatically determine header levels based on the document structure.
-* Automatically generate a Table of Contents based on the document structure.
-* Store common snippets of text in a single YAML file and use them anywhere in your document, as many times as you need.
-* Store configuration settings in a YAML file and use them anywhere in your document, as many times as you need.
-* Evaluate Ruby code within your document.
-* Include content only if certain conditions are satisfied.
-* Define macros, snippets and configuration settings directly within your document.
-* Highlight source code.
-* Call macros from other macros (including snippets), avoiding mutual calls.
-* Include text files within other text files.
-* Include the value of any configuration setting (like author, title) in the document.
-* Filter input explicitly or implicitly (based on file extensions). 
-* Manage draft comments and todo items.
-* Provide a simple, less-verbose syntax to write XML code.
-
-</div>
-
 <div class="section">
-<h2 id="h_2">Installation</h2>
-@gem install glyph@ -- simple, as always.
-
-</div>
-
-<div class="section">
-<h2 id="h_3">Essential Glyph commands</h2>
+<h3 id="h_2">Command Line Interface</h3>
 Glyph is 100% command line. Its interface resambles <a href="http://git-scm.com/">Git's</a> for its simplicity and power (thanks to the <a href="http://github.com/davetron5000/gli">gli</a> gem). Here are some example commands: 
 
 * @glyph init@ -- to initialize a new Glyph project in the current (empty) directory.
 * @glyph add introduction.textile@ -- to create a new file called _introduction.textile_.
 * @glyph compile@ -- to compile the current document into a single HTML file.
 * @glyph compile --auto@ -- to keep recompiling the current document every time a file is changed.
-* @glyph compile -f pdf@ -- to compile the current document into HTML and then transform it into PDF using <a href="http://www.princexml.com/">Prince</a>.
+* @glyph compile -f pdf@ -- to compile the current document into HTML and then transform it into PDF.
 * @glyph compile readme.glyph@ -- to compile a _readme.glyph_ located in the current directory into a single HTML file.
 * @glyph outline -l 2@ -- Display the document outline, up to second-level headers.
+* @glyph stats@ -- Display project statistics.
 
 </div>
-
-<div class="section">
-<h2 id="macros_nutshell">Glyph macros in a nutshell</h2>
-Format your documents using Textile or Markdown, and use Glyph Macros to do everything else:
-
-**Glyph Source:**
-
-
+		<div class="section">
+<h3 id="h_3">Minimalist Syntax</h3>
+Glyph syntax rules can be explained using Glyph itself:
+			
 <div class="code">
 <pre>
 <code>
@@ -63,26 +32,24 @@ You can use Glyph macros in conjunction
 with _Textile_ or _Markdown_ to
 produce HTML files effortlessly.
   ]
-  p[
-Alternatively, you can just use em[Glyph itself]
-to generate HTML tags.
-  ]
+  p[Alternatively, you can just use em[Glyph itself] to generate HTML tags.]
   section[
     @title[What about PDFs?]
     @id[pdf]
+    p[
 Once you have a single, well-formatted HTML 
 file, converting it to PDF is
-extremely easy with a 3rd-party 
-renderer like =>[http://www.princexml.com|Prince].
+extremely easy with a free 3rd-party 
+renderer like =>[http://www.princexml.com|Prince] 
+or =>[http://code.google.com/p/wkhtmltopdf/|wkhtmltopdf].
+    ]
   ]   
 ]
 </code>
 </pre>
 </div>
-
-**HTML Output:**
-
-
+The Glyph code above corresponds to the following HTML code:
+				
 <div class="code">
 <pre>
 <code>
@@ -93,17 +60,18 @@ renderer like =>[http://www.princexml.com|Prince].
     <em>Textile</em> or <em>Markdown</em> to
     produce HTML files effortlessly.
   </p>
+  <p>
+    Alternatively, you can just use <em>Glyph itself</em>
+    to generate HTML tags.
+  </p>
   <div class="section">
    <h3 id="pdf">What about PDFs?</h3>
    <p>
      Once you have a single, well-formatted HTML 
      file, converting it to PDF is
-     extremely easy with a 3rd-party renderer 
-     like <a href="http://www.princexml.com">Prince</a>.
-   </p>
-   <p>
-     Alternatively, you can just use <em>Glyph itself</em>
-     to generate HTML tags.
+     extremely easy with a free 3rd-party renderer 
+     like <a href="http://www.princexml.com">Prince</a> 
+     or <a href="http://code.google.com/p/wkhtmltopdf/\">wkhtmltopdf</a>.
    </p>
   </div>
 </div>
@@ -112,16 +80,76 @@ renderer like =>[http://www.princexml.com|Prince].
 </div>
 
 </div>
+		<div class="section">
+<h3 id="h_4">Content Reuse</h3>
+Finding yourself repeating the same sentence over an over? Glyph allows you to create snippets. Within snippets. Within other snippets (and so on, for a long long time...) as long as you don't define a snippet by defining itself, which would be kinda nasty (and Glyph would complain!):
+			
+<div class="code">
+<pre>
+<code>
+snippet:[entities|snippets and macros]
+snippet:[custom_definitions|
+	p[Glyph allows you to define your own &[entities].]
+]
+&[custom_definitions]
+</code>
+</pre>
+</div>
+		...which results in:
+			
+<div class="code">
+<pre>
+<code>
+<p>Glyph allows you to define your own snippets and macros.</p>
+</code>
+</pre>
+</div>
+		If yourself dreaming about _parametric_ snippets, just create your own macros (see the <a href="http://github.com/h3rald/glyph/blob/master/book/text/changelog.glyph">source</a> of Glyph's changelog, just to have an idea).
 
-<div class="section">
-<h2 id="h_5">Resources</h2>
+</div>
+		<div class="section">
+<h3 id="h_5">Automation of Common Tasks</h3>
+If you're writing a book, you shouldn't have to worry about pagination, headers, footers, table of contents, section numbering or similar. Glyph understands you, and will take care of everything for you (with a little help from CSS3, sometimes).
+
+</div>
+		<div class="section">
+<h3 id="h_6">Reference Validation</h3>
+Feel free to add plenty of links, snippets, bookmarks, ... if Glyph doesn't find something, it will definitely complain. Broken references are a thing on the past, and you don't need to worry about it.
+
+</div>
+		<div class="section">
+<h3 id="h_7">Extreme Extensibility</h3>
+* You miss a <code>!!!</code> macro to format really, _really_ important things? Create it. In under 3 seconds, in Ruby or Glyph itself. And yes, you can use special characters, too.
+* You want your own, very special special @glyph create --everything@ command to create all _you_ need in a Glyph project? You can do it. Using your own Rake tasks, too.
+* You want Glyph to output ODF files? You can do it, and you'll be able to run @glyph generate -f odf@. This would probably require a little more time, but it's trivial, from a technical point of view.
+
+</div>
+		<div class="section">
+<h3 id="h_8">Convention over Configuration</h3>
+Put your text files in @/text@, your images in @/images@, add custom macros in a @macro@ folder within your @/lib@ folder... you get the picture: Glyph has its special places.
+
+Nonetheless, you also have 1 (_one_) configuration file to customize to your heart's content (with smart defaults).
+
+</div>	
+		<div class="section">
+<h3 id="h_9">Free and Open Source</h3>
+Glyph is 100% Open Source Software, developed using the Ruby Programming Language and licensed under the very permissive terms of the <a href="http://www.opensource.org/licenses/mit-license.php">MIT License</a>.
+
+If you have Ruby installed, just run @gem install glyph@. That's all it takes.
+
+</div>
+
+</div>
+	<div class="section">
+<h2 id="h_10">Resources</h2>
 * Home Page: <a href="http://www.h3rald.com/glyph/">http://www.h3rald.com/glyph/</a>
 * Repository: <a href="http://www.github.com/h3rald/glyph/">http://www.github.com/h3rald/glyph/</a>
 * Bug Tracking: <a href="http://www.github.com/h3rald/glyph/issues">http://www.github.com/h3rald/glyph/issues</a>
 * Development Wiki <a href="http://wiki.github.com/h3rald/glyph">http://wiki.github.com/h3rald/glyph</a>
 * RubyGem Download <a href="http://www.rubygems.org/gems/glyph">http://www.rubygems.org/gems/glyph</a>
-* Book (PDF): <a href="http://github.com/h3rald/glyph/raw/0.2.0/book/output/pdf/glyph.pdf">http://github.com/h3rald/glyph/raw/0.2.0/book/output/pdf/glyph.pdf</a>
-* Reference Documentation: <a href="http://yardoc.org/docs/h3rald-glyph/">http://yardoc.org/docs/h3rald-glyph/</a>
+* Book (PDF): <a href="http://github.com/downloads/h3rald/glyph/glyph.pdf">http://github.com/downloads/h3rald/glyph/glyph.pdf</a>
+* Book (Web): <a href="http://www.h3rald.com/glyph/book/">http://www.h3rald.com/glyph/book/</a>
+* Reference Documentation: <a href="http://rubydoc.info/gems/glyph/">http://rubydoc.info/gems/glyph/</a>
 * User Group: <a href="http://groups.google.com/group/glyph-framework">http://groups.google.com/group/glyph-framework</a>
 
 </div>

data/Rakefile

@@ -1,8 +1,9 @@
 #!/usr/bin/env ruby
-$: << File.expand_path(File.dirname(__FILE__) + '/lib')
+lib = File.expand_path(File.dirname(__FILE__) + '/lib')
+$: << lib
 require 'rubygems'
 require 'rake/clean'
-require 'glyph'
+require "#{lib}/glyph.rb"
 
 task :default => :spec
 
@@ -27,16 +28,17 @@ begin
 		s.email = "h3rald@h3rald.com"
 		s.homepage = "http://www.h3rald.com/glyph/"
 		s.authors = ["Fabio Cevasco"]
-		s.files.include "styles/**/*"
-		s.files.include "book/**/*"
-		s.add_dependency 'gli', '>= 0.3.1' # Command line interface
-		s.add_dependency 'extlib', '>= 0.9.12' # Extension methods
+		s.files.exclude 'book/output/web/**/*'
+		s.files.exclude 'book/output/web5/**/*'
+		s.files.exclude 'book/output/html5/**/*'
+		s.add_dependency 'gli', '>= 1.1.1' # Command line interface
+		s.add_dependency 'extlib', '>= 0.9.15' # Extension methods
 		s.add_dependency 'rake', '>= 0.8.7' # Glyph rasks
-		s.add_development_dependency 'rspec', '>= 1.1.11' # Test suite
-		s.add_development_dependency 'yard', '>= 1.5.4' # Documentation suite
+		s.add_development_dependency 'rspec', '>= 1.3.0' # Test suite
+		s.add_development_dependency 'yard', '>= 0.6.0' # Documentation suite
 		s.add_development_dependency 'jeweler', '1.4.0' # Gem management
 		s.add_development_dependency 'directory_watcher', ">= 1.3.2" # Auto-regeneration
-		s.add_development_dependency 'haml', ">= 3.0.6" # Sass filter
+		s.add_development_dependency 'haml', ">= 3.0.15" # Sass filter
 		s.add_development_dependency 'RedCloth', ">= 4.2.3" # Textile filter
 		s.add_development_dependency 'bluecloth', ">= 2.0.7" # Markdown filter
 		s.add_development_dependency 'coderay', ">= 0.9.3" # Syntax Highlighting
@@ -47,7 +49,7 @@ rescue LoadError
 end
 
 begin
-	require 'spec/rake/spectask'
+	require "spec/rake/spectask"
 	Spec::Rake::SpecTask.new('spec') do |t|
 		t.spec_files = FileList['spec/**/*_spec.rb']
 		t.spec_opts = ["--color"]

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

data/benchmark.rb

@@ -66,7 +66,7 @@ Benchmark.bm(30) do |x|
 	sep
 	puts " => Macro Set: XML"
 	reset_glyph
-	Glyph['language.set'] = 'xml'
+	Glyph['options.macro_set'] = 'xml'
 	Glyph.run! 'load:all'
 	rep(x, "HTML text") { macro_exec html }
 end

data/book/config.yml

@@ -1,11 +1,25 @@
 --- 
 :document: 
   :output: html
-  :title: Glyph
   :subtitle: Rapid Document Authoring Framework
   :author: Fabio Cevasco
-  :revision: "v0.3.0"
-  :filename: glyph
   :draft: true
-:filters:
+  :revision: v0.4.0
+  :filename: glyph
+  :title: Glyph
+  :styles: link
+:output: 
+  :h3rald: 
+    :multifile: true
+    :extension: '.html'
+    :filter_target: 'html'
+    :base: '/glyph/book/'
+    :macro_dirs: ['html']
+    :layout_dirs: ['web']
+    :layouts: 
+      :topic: bookpage
+      :index: bookindex
+  :pdf: 
+    :generator: prince
+:filters: 
   :highlighter: ultraviolet