glyph 0.1.0

data/book/text/extending.textile

@@ -0,0 +1,148 @@
+Glyph was created wih extensibility in mind. You can freely extend &[glang] by creating or overriding macros, to do whatever you like. Macro definitions are written in pure Ruby code and placed in @.rb@ files within the @/lib/macros@ folder of your project.
+
+section[header[Anatomy of a Macro]
+
+This is the source code of a fairly simple macro used to format a note :
+
+<notextile>
+code[=
+macro :note do
+  %{<div class="#{@name}"><span class="note-title">#{@name.to_s.capitalize}</span>#{@value}
+
+    </div>}
+end 
+=]
+</notextile>
+
+The @macro@ method takes a single Symbol or String parameter, corresponding to the name of the macro. In this case, the entire block (or _body_ of the macro) is a String corresponding to what we want the macro to evaluate to: a @<div>@ tag containing a note. 
+
+The body of the macro is evaluated in the context of the =>[http://yardoc.org/docs/h3rald-glyph/Glyph/Macro|Glyph::Macro] class, therefore its instance variables (like codeph[@name] or codeph[@value]) can be used directly.
+
+box[Why using codeph[@name] instead of just "note"?|
+For the @note@ macro, it absolutely makes no difference. However, by using codeph[@name] it is possible to re-use the same code for the @tip@, @important@ and @caution@ macros as well, which are in fact only aliases of the @note@ macro:
+
+@macro_alias :important => :note@
+@macro_alias :tip => :note@
+@macro_alias :caution => :note@
+] --[End box]
+
+The following table lists all the instance variables that can be used inside macros:
+
+table[
+  tr[
+    th[Variable]
+    th[Description]
+  ]
+  tr[
+    td[codeph[@node]]
+    td[A =>[http://yardoc.org/docs/h3rald-glyph/Node|Node] containing information about the macro, within the document syntax tree. Useful for accessing parent and child macros, and the current =>[http://yardoc.org/docs/h3rald-glyph/Glyph/Document|document]. Normally, macro nodes contain the following keys:
+- @:name@, the name of the macro
+- @:value@, the value (i.e. the contents, within the delimiters) of the macro
+- @:source@, a String identifying the source of the macro (a file, a snippet, etc.) 
+- @:document@, the parsed document tree
+
+Note that the first three keys can also be accessed via instance variables.]
+  ]
+  tr[
+    td[codeph[@name]]
+    td[The name of the macro]
+  ]
+  tr[
+    td[codeph[@value]]
+    td[The full contents (including parameters and nested macros) within the macro delimiters.]
+  ]
+  tr[
+    td[codeph[@source]]
+    td[A String identifying the source of the macro (a file, a snippet, etc.) ]
+  ]
+  tr[
+    td[codeph[@params]]
+    td[The parameters passed to the macro. In other words, the value of the macro split by pipes (@|@).]
+  ]
+] --[End Table]
+
+]
+
+section[header[Bookmarks and Headers]
+
+The =>[http://yardoc.org/docs/h3rald-glyph/Glyph/Macro|Glyph::Macro] class also includes a few methods to check and store bookmarks and headers. Consider for example the following source code for the @anchor@ macro:
+
+<notextile>
+code[=
+macro :anchor do 
+  ident, title = @params
+  macro_error "Bookmark '#{ident}' already exists" if bookmark? ident
+  bookmark :id => ident, :title => title
+  %{<a id="#{ident}">#{title}</a>}
+end
+=] </notextile>
+
+The @bookmark?@ method can be used to check the existance of a particular ID within the whole document, while the @bookmark@ method is used to store bookmark IDs and titles. In a similar way, you can use @header?@ and @header@ methods to check the existance of headers within the documents or store new ones.
+
+]
+
+section[header[Using Placeholders]
+
+Sometimes you may need to access some data that will not be available until the entire document has been fully parsed and analyzed. For example, in order to be able to validate internal links, it is necessary to know in advance if the bookmark ID referenced in the link exists or not, either before (that's easy) or even _after_ the location of the link. 
+
+Here's the source code of the @link@ macro:
+
+<notextile>
+code[=
+macro :link do
+  href, title = @params
+  if href.match /^#/ then
+    anchor = href.gsub(/^#/, '').to_sym
+    bmk = bookmark? anchor
+    if bmk then
+      title ||= bmk[:title]
+    else
+      plac = placeholder do |document|
+        macro_error "Bookmark '#{anchor}' does not exist" unless document.bookmarks[anchor] 
+        document.bookmarks[anchor][:title]
+      end
+      title ||= plac
+    end
+  end
+  title ||= href
+  %{<a href="#{href}">#{title}</a>}
+end
+=] </notextile>
+
+If there's already a bookmark stored in the current document, then it is possible to retrieve its title and use it as link text. Otherwise, it is necessary to wait until the entire document has been fully processed and then check if the bookmark exists. To do so, use the @placeholder@ method. When called, this method returns an unique placeholder, which is then substituted with the value of the block, right before the document is finalized.
+
+Within the @placeholder@ block, the @document@ parameter is, by all means, the fully analyzed document.
+]
+
+section[header[Interpreting Glyph Code]
+
+What if you need to evaluate some Glyph code _within_ a macro? Say for example you want to transform a parameter in a link, and you want to make sure that link gets validated exactly like the others, in this case, you can use the @interpret@ method, as follows:
+
+<notextile>
+code[=
+macro :fmi do
+  topic, href = @params
+  link = placeholder do |document| 
+    interpret "link[#{href}]"
+  end
+  %{<span class="fmi">for more information on #{topic}, see #{link}</span>}
+end
+=] </notextile>
+
+When the @interpreter@ method is called, the following happens:
+# A new Glyph document is created from the String passed to the method.
+# The bookmarks, headers and placeholders are passed from the main document to the new one. Because they are stored in Arrays or Hashes, they are passed by reference, so for example any new bookmark stored in the new document will also become available in the main document.
+# Any macro included in the String is evaluated, and the resulting text is returned by the method. Note that this new document does not get finalized: in other words, placeholders will be left as they are, and they'll eventually be replaced when _the main document_ is finalized.
+
+]
+
+section[header[Further Reading]
+
+For more examples on how to create more complex macros, have a look at the =>[http://github.com/h3rald/glyph/tree/master/macros/|source code] of the existing ones.
+
+To gain a deeper understanding on how macros are executed, have a look at the following Glyph classes:
+* =>[http://yardoc.org/docs/h3rald-glyph/Glyph/Macro|Glyph::Macro]
+* =>[http://yardoc.org/docs/h3rald-glyph/Glyph/Interpreter|Glyph::Interpreter]
+* =>[http://yardoc.org/docs/h3rald-glyph/Glyph/Document|Glyph::Document]
+* =>[http://yardoc.org/docs/h3rald-glyph/Glyph/Node|Node]
+]

data/book/text/getting_started.textile

@@ -0,0 +1,152 @@
+section[header[Creating your first Glyph Project]
+
+To install Glyph, simply run @gem install glyph@, like with any other Ruby gem. Then, create a new directory and initialize a new Glyph project, like so:
+
+@mkdir@ _==test_document==_
+
+@cd@ _==test_document==_
+
+@glyph init@
+
+That's it. You just created a new Glyph project in the @test_document@ directory.
+
+box[Glyph's dependencies|
+Glyph requires the following gems:
+- extlib
+- gli
+- treetop
+- rake
+
+Additionally, some Glyph macros may require additional gems, such as:
+- RedCloth (_textile_ macro)
+- Maruku _or_ Kramdown _or_ BlueCloth (_markdown_ macro)
+- Haml (if you want to load .sass files with the _style_ macro)
+]
+
+Every Glyph project is comprised of the following directories:
+* @images/@ -- used to store the image files used in your document.
+* @lib/@ -- used to store your custom Glyph macros and Rake tasks.
+* @output/@ -- used to store your generated output files.
+* @styles/@ -- used to store your stylesheets.
+* @text/*@ -- used to store your source text files.
+
+Additionally, the following files are also created at top level:
+* @config.yml@ -- containing your =>[#cfg|Project Configuration].
+* @document.glyph@ -- containing your =>[#struct|Document Structure]
+* @snippets.yml@ -- containing your text snippets. todo[Link to Snippets section]
+
+]
+
+section[header[Document Structure|struct]
+
+Every Glyph project contains a @document.glyph@ file that is typically used to define the document structure. The default @document.glyph@
+generated automatically when creating a new project is the following:
+
+code[=
+document[
+  head[style[default.css]]
+  body[
+    titlepage[
+      title[]
+      author[]
+      pubdate[]
+    ]
+    frontmatter[
+      toc[]
+      preface[header[Preface]
+        @[preface.textile]
+      ]
+    ]
+    bodymatter[  
+      chapter[header[Chapter #1]
+        @[chapter_1.textile]
+      ]
+      chapter[header[Chapter #2]
+        @[chapter_2.textile]
+      ]
+    ]
+    backmatter[
+      appendix[header[Appendix A]
+        @[appendix_a.textile]
+      ]
+    ]
+  ]
+]=]
+
+Even without knowing anything about &[glang], you can easily figure out that this file defines a document with a Table of Contents, a Preface and some Chapters. @frontmatter\[\]@, @preface\[\]@, @chapter\[\]@, etc. are all Glyph _macros_ used to define -- in this case -- some structural elements. In practice, this means that if you plan to generate an HTML document, they'll be converted into @<div>@ tags.
+
+Be aware that other macros, on the other hand, are used to do something completely different, e.g.:
+* @toc\[\]@ generates the document's Table of Contents
+* codeph[=@\[\]=] or its alias @include\[\]@ is used to copy the contents of another file stored anywhere in the @/text@ directory.
+
+Let's now analyze this @document.glyph@ more in detail.
+* The @document\[\]@ macro wraps every other macro. This is necessary to create the initial @<html>@ tag.
+* Similarly, @head\[\]@ and @body\[\]@ are used to generate the respective HTML tags. Actually, @head\[\]@ already sets some metadata for you, by default (author and copyright).
+* Within @head\[\]@, the @style\[\]@ macro is used to load the @default.css@ stylesheet, which is included by default the @/styles@ directory of every Glyph project.
+* Immediately after the @body\[\]@ macro, the @titlepage\[\]@ macro is used to define (guess...) the first page of your document. @title\[\]@, @author\[\]@  and @pubdate\[\]@ insert the title of the document, its author and the publication date (retrieved from the project's =>[#cfg|configuration settings]).
+* Then, the @frontmatter\[\]@, @bodymatter\[\]@ and @backmatter\[\]@ macros are used to further divide the portions of your document according to the rules of =>[http://en.wikipedia.org/wiki/Book_design|book design]. They are not mandatory, but they can be used, for example, to number your appendixes with letters instead of numbers and similar.
+* @preface\[\]@, @chapter\[\]@, @appendix\[\]@ are just a way to wrap content in @<div>@ tags, from an HTML point of view, but they are also necessary to nest the content of your document and generate the Table of Contents automatically, together with the @header\[\]@ macro.
+
+]
+
+section[header[Project Configuration|cfg]
+
+Glyph stores configuration settings in the following YAML files:
+# Your _Project Configuration_ is stored in the @config.yml@ file, included in each Glyph Project.
+# Your _Global Configuration_ is stored in a @.glyphrc@ file in your $HOME (or ==%HOMEPATH%== on Windows) directory (not created by default).
+# The _System Configuration_ is stored in the source directory of Glyph itself.
+
+When compiling, Glyph loads all these configuration files and merges them according to the following rules:
+* A setting configured in the _Project Configuration_ overrides the same setting in both Global and System configuration.
+* A setting configured in the _Global Configuration_ overrides the same setting in the _System Configuration_
+
+Typically, you should use the _Project Configuration_ for all project-specific settings and the _Global Configuration_ for settings affecting all your projects (for example, you may want to set 'document.author' in the Global Configuration instead of setting it in the Project Configuration of all your Glyph projects). The _System Configuration_ is best left untouched.
+
+Instead of editing your configuration settings directly, you can use the @glyph config@ command, as follows:
+
+@glyph config@ _setting_ _\[value\]_
+
+If no _value_ is specified, glyph just prints the value of the configuration setting, so typing @glyph config document.author@ right after creating a project (assuming you didn't set this in the Global Configuration) will print nothing, because this setting is blank by default.
+
+To change the value of a configuration setting, specify a value right after the setting, like this:
+
+@glyph config document.author "John Smith"@
+
+In this way, the document author will be set to _John Smith_ for the current project. To save this setting globally, add a @-g@ option, like this:
+
+@glyph config -g document.author "John Smith"@
+
+box[Regarding configuration values and data types...|
+Glyph attempts to "guess" the data type of a configuration values by evaluation (@Kernel#instance_eval@) if the value:
+- is wrapped in quotes (@"@ or @'@) &rarr; String
+- starts with a colon (@:@) &rarr; Symbol
+- is wrapped in square brackets (@\[@ and @\]@) &rarr; Array
+- is wrapped in curly brackets (@\{@ and @\}@) &rarr; Hash
+- is _true_ or _false_ &rarr; Boolean
+- If the value is _nil_ &rarr; NilClass
+
+Note that this guessing is far from being foolproof: If you type something like _{:test, 2}_, for example, you'll get an error. 
+]
+
+There are plenty of configuration settings that can be modified, but most of them are best if left alone (and in the System Configuration file). For a complete reference, see =>[#cfg_ref]. Normally, you may just want to change the following ones:
+
+table[
+	tr[
+		th[Setting]
+		th[Description]
+	]
+	tr[
+		td[*document.author*]
+		td[The author of the document]
+	]
+	tr[
+		td[*document.title*]
+		td[The title of the document]
+	]
+	tr[
+		td[*document.filename*]
+		td[The document file name]
+	]
+]
+
+]

data/book/text/introduction.textile

@@ -0,0 +1,88 @@
+Glyph is a _Rapid Document Authoring Framework_. 
+
+Think of it like a sort of =>[http://www.rubyonrails.org|Ruby on Rails] but for creating text documents instead of web sites. With Glyph, you can manage your documents tidily in _projects_ that can be used to generate deliverables in different formats such as HTML or PDF (through &[prince]).
+
+section[header[Main Features]
+
+Glyph uses a =>[#macros_nutshell|simple 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.
+* Call macros from other macros (including snippets), carefully avoiding mutual calls.
+* Include text files in other text files.
+* Include the contents of configuration settings (author, title) in the document.
+* Filter input explicitly or implicitly, based on file extensions when including files. 
+* Manage comments and todo items.
+]
+
+section[header[Installation]
+
+@gem install glyph@ -- simple, as always.
+
+]
+
+section[header[Essential Glyph commands]
+
+Glyph is 100% command line. Its interface resambles =>[http://git-scm.com/|Git's] for its simplicity and power (thanks to the =>[http://github.com/davetron5000/gli|Gli] 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 -f pdf@ -- to compile the current document into HTML and then transform it into PDF using &[prince].
+
+]
+
+section[header[Glyph macros in a nutshell|macros_nutshell]
+
+Format your documents using Textile or Markdown, and use Glyph Macros to do everything else:
+
+**Glyph Source:**
+
+code[=
+section[header[Something about Glyph]
+You can use Glyph macros in conjunction
+ with _Textile_ or _Markdown_ to
+produce HTML files effortlessly.
+  section[header[What about PDFs?|pdf]
+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].
+  ]   
+]
+=]
+
+**HTML Output:**
+
+<notextile>
+code[=
+<div class="section">
+  <h2 id="h_10">Something about Glyph</h2>
+  <p>You can use Glyph macros in conjunction with 
+     <em>Textile</em> or <em>Markdown</em> to
+     produce HTML files effortlessly.</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>
+  </div>
+</div>
+=]</notextile>
+]
+
+section[header[Resources]
+
+* Home Page: =>[http://www.h3rald.com/glyph/]
+* Repository: =>[http://www.github.com/h3rald/glyph/]
+* Bug Tracking: =>[http://www.github.com/h3rald/glyph/issues]
+* Book (PDF): =>[http://github.com/h3rald/glyph/raw/master/book/output/pdf/glyph.pdf]
+* Reference Documentation: =>[http://yardoc.org/docs/h3rald-glyph/]
+* User Group: =>[http://groups.google.com/group/glyph-framework]
+]

data/book/text/ref_commands.textile

@@ -0,0 +1,74 @@
+Glyph's command-line interface has been built using the =>[http://github.com/davetron5000/gli|gli] (Git-like interface) gem. Therefore, Glyph commands are all written like this:
+
+@glyph@ _global-options_ command _options_ _parameters_
+
+Where:
+* _global-options_ and _options_ are in the form: @-n@ _value_ or @--name=@\._value_, e.g. @-f pdf@ or @--format=pdf@
+* _parameters_ are separated by whitespaces, and can be wrapped in quotes.
+
+section[header[Global Options]
+
+section[header[@-d@, @--debug@]
+If specified, the command is executed in debug mode and additional diagnostic information is printed on the screen.
+]
+]
+
+section[header[@add@]
+Creates a new text file in the @text/@ folder.
+
+example[glyph add introduction.textile]
+
+parameters[
+-p[file-name|The name (or relative path) of the new file to be created.]
+]
+] --[End add]
+
+section[header[@compile@]
+Compiles a Glyph document into an output file. If no options are specified, the @document.glyph@ file is used as source to produce a standalone HTML file.
+
+example[glyph compile -f pdf]
+
+options[
+-o[source|
+The source file to compile. 
+default[document.glyph]
+]
+-o[format|
+The format of the output file.
+default[html]
+values[html, pdf]
+]
+]
+] --[End compile]
+
+section[header[@config@]
+Gets or sets a configuration setting in the project or global configuration file (\.fmi[configuration files|#cfg]).
+
+examples[
+glyph config document.filename
+glyph config -g document.author "Fabio Cevasco"
+]
+
+options[
+-o[global|
+If specified, the global configuration file is processed instead of the project file.
+default[false]
+]
+]
+parameters[
+-p[setting|The name of a valid =>[#cfg_ref|configuration setting].]
+-p[value|The new value of the configuration setting.]
+]
+] --[End config]
+
+section[header[@init@]
+Creates a new Glyph project in the current directory (if empty).
+
+example[glyph init]
+] --[End init]
+
+section[header[@todo@|c_todo]
+Prints all the todo items saved using the %>[todo].
+
+example[glyph todo]
+] --[End todo]