glyph 0.2.0 → 0.3.0

data/book/text/extending/macro_def.glyph

@@ -0,0 +1,64 @@
+section[
+	@title[Defining Macros]
+	@id[macro_def]
+	txt[
+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.
+
+		box[Alternative Ways to Define Macros|
+You can also define macros:
+* inside your document, using the %>[macro:].
+* Using the %>[include] specifying the path to an @.rb@ file containing macro definitions stored in the @lib/@ directory (useful especially when =>[#lite_mode|compiling single Glyph files]).
+		]
+
+This is the source code of a fairly simple macro used to format a note:
+	]
+	highlight[=ruby|
+macro :note do
+  %{<div class="#{@name}"><span class="note-title">#{@name.to_s.capitalize}</span>
+		#{@value}
+
+    </div>}
+end
+	=]
+	txt[
+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 class[Glyph::Macro] class, therefore its instance variables (like code[@name] or code[@value]) can be used directly.
+
+		box[Why using code[@name] instead of just "note"?|
+For the @note@ macro, it absolutely makes no difference. However, by using code[@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.
+		]
+
+The following table lists all the instance variables that can be used inside macros:
+	]
+	table[
+  	tr[
+    	th[Variable]
+    	th[Description]
+ 		]
+  	tr[
+    	td[code[@node]]
+    	td[
+				txt[
+A class[Glyph::MacroNode] containing information about the macro. Useful for accessing parent and child macros, and the current class[Glyph::Document]. Normally, instances of the code[MacroNode] class contain the following keys:
+* @:name@, the name of the macro.
+* @:source@, a @String@ identifying the source of the macro (a file, a snippet, etc.) 
+* @:value@, the value of the macro (populated after the document has been parsed and analyzed).
+* @:escape@, whether the macro is a =>[#esc_quot|quoting macro] or not.
+* @:document@, the instance of code[Document] the macro is contained in (populated after the document has been parsed and analyzed).
+
+Note that the first two keys can also be accessed via instance variables.
+				]
+			]
+  	]
+  	tr[
+    	td[code[@name]]
+    	td[The name of the macro.]
+  	]
+  	tr[
+    td[code[@source]]
+    td[A code[String] identifying the source of the macro (a file, a snippet, etc.).]
+  	]
+	]
+]
+

data/book/text/extending/params_attrs.glyph

@@ -0,0 +1,70 @@
+section[
+	@title[Parameters and Attributes]
+	txt[
+Perhaps the most common things to do in a macro definition is accessing parameters and attributes. When doing so, it is important to consider whether we want to retrieve the _raw value_ of and attribute or parameter or its _expanded value_. The difference between the two will become clearer in the following sections and also in the =>[#interpreting] section.
+	]
+	section[
+		@title[Accessing Expanded Values]
+		@id[expanded_values]
+		txt[
+Normally, you just want to get the value of an attribute or parameter and use it in the macro. This means, in other words, its _expanded_ value, i.e. the value resulting from the expansion of the macros (if any) within the attribute or parameter.
+		]
+		txt[
+To access expanded values, use the following methods:
+* @parameter@ (or @param@): Returns the expanded value of the parameter specified by number. Other parameters are not expanded.
+* @value@: Returns the expanded value of the first parameter (i.e. like @parameter(0)@).
+* @attribute@ (or @attr@): Returns the expanded value of the attribute specified by name. Other attributes are not expanded.
+* @parameters@ (or @params@):  Returns an array of expanded parameters.
+* @attributes@ (or @attrs@):  Returns a hash of expanded attributes.
+ 
+		]
+		
+	]
+	section[
+		@title[Accessing Raw Values]
+		p[While accessing expanded values is simple and immediate, in some cases it may not produce the desired results. Consider the following macro definition:]
+		highlight[=ruby|
+macro :nest_section do
+  interpret %{section[
+    @title[A]
+    section[
+      @title[B]
+      #{value}
+    ]
+  ]}
+end
+		=]
+		p[And suppose to use it as follows:]
+		highlight[=ruby|
+nest_section[
+  section[
+    @title[Inner Section]
+    ...
+  ]
+]
+		=]
+		p[It produces the following HTML code:]
+		highlight[=html|
+<div class="section">
+  <h2 id="h_2">A</h2>
+  <div class="section">
+    <h3 id="h_3">B</h3>
+    <div class="section">
+      <h2 id="h_1">Inner Section</h2>
+...
+    </div>
+  </div>
+</div>
+		=]
+		p[Everything is fine em[except] for the header level: the heading "Inner Section" is of level 2, but it should be level 4!]
+		p[This happens because the inner section is evaluated em[before] the code[nest_section] macro: after all, we ask for it ourselves when we call the code[value] method inside the macro definition. When the value is expanded, there are no outer sections em[yet].]
+		p[To avoid this unwanted behavior, we can use the code[raw_value] method instead, that returns the first parameter converted back to a Glyph code string.]
+		tip[To be on the safe side, always use code[raw_*] methods when interpreting.]
+		txt[
+To access raw values, use the following methods:
+* @raw_parameter@ (or @raw_param@): Returns the raw parameter value of the parameter specified by number.
+* @raw_value@: Returns the first raw parameter value (i.e. like @raw_parameter(0)@).
+* @raw_attribute@ (or @raw_attr@): Returns the attribute value of the attribute specified by name.
+		]
+	]
+]

data/book/text/extending/placeholders.glyph

@@ -0,0 +1,34 @@
+section[
+	@title[Using Placeholders]
+	txt[
+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 link. 
+
+Here's the source code of the %>[link]:
+	]
+	highlight[=ruby|
+macro :link do
+  href, title = @params
+  if href.match /^#/ then
+    anc = href.gsub(/^#/, '').to_sym
+    bmk = bookmark? anc
+    if bmk then
+      title \|\|= bmk[:title]
+    else
+      plac = placeholder do \|document\|
+        macro_error "Bookmark '#{anc}' does not exist" unless document.bookmarks[anc] 
+        document.bookmarks[anc][:title]
+      end
+      title \|\|= plac
+    end
+  end
+  title \|\|= href
+  %{<a href="#{href}">#{title}</a>}
+end
+	=]
+	txt[
+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.
+	]
+]
+

data/book/text/extending/validators.glyph

@@ -0,0 +1,16 @@
+section[
+	@title[Using Validators]
+	p[If you need to make sure that a macro is used properly, consider using =>[&[yardoc]/Glyph/Macro/Validators|validators]. These methods can be used anywhere within the macro code to check whether certain conditions are met or not. Some default validators are provided to check the number of parameters of a macro, and they are actually used in some system macros.]
+	p[If you want to create your own validators, you can call the generic code[validate] method which takes the message to display in case of error, a Hash of options and a block containing the validation to perform.]
+	box[Validating macro placement|
+		txt[
+You can, of course, create your own validators to check whether a macro is used within another. While this may seem a good idea to enforce constraints into the way documents are created, it has one major drawback: if you define a macro with such validation, you're effectively limiting its usage, so for example you won't be able to use within snippets or other custom macros.
+
+Suppose, for example, that the %>[box] is only allowed within a @section@ macro. This means that, for example:
+* the macro cannot be used within @chapter@ or @appendix@ macros.
+* the macro cannot be used in snippets
+
+Even if you consider all the possibilities within the scope of the default macros provided with Glyph, this would also make the @box@ macro unusable within custom macros.
+		]
+	]
+]

data/book/text/getting_started/configuration.glyph

@@ -0,0 +1,49 @@
+section[
+	@title[Project Configuration]
+	@id[cfg]
+
+	textile[
+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 code[$HOME] (or ==\.code[%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 the $>[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 #>[config], as follows:
+
+@glyph config@ _setting_ _\[value\]_
+
+If no _value_ is specified, glyph 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"@
+
+	tip[It is also possible to change configuration settings inside your document, using the %>[config:].]
+
+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 value by evaluation (@Kernel#instance_eval@) if the value:
+* is wrapped in quotes (@"@ or @'@) → @String@
+* starts with a colon (@:@) → @Symbol@
+* is wrapped in square brackets (@\[@ and @\]@) → @Array@
+* is wrapped in curly brackets (@{@ and @}@) → @Hash@
+* is _true_ or _false_ → @Boolean@
+* is _nil_ → @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]. For everyday use, you may just want to change the settings defined in the =>[#cfg_document] namespace.
+	] --[End textile]
+]

data/book/text/getting_started/create_project.glyph

@@ -0,0 +1,41 @@
+section[
+	@title[Creating your first Glyph Project]
+
+	textile[
+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
+* rake
+
+Additionally, some Glyph macros may require additional gems, such as:
+* RedCloth (\.%>[textile])
+* BlueCloth _or_ RDiscount _or_ Maruku _or_ Kramdown (\.%>[markdown])
+* Haml (if you want to load .sass files with the %>[style])
+* CodeRay _or_ UltraViolet (\.%>[highlight])
+* directory_watcher (to use auto-regeneration with the #>[compile])
+	]
+
+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 the =>[#struct|structure] of your document.
+* @snippets.yml@ -- containing your text =>[#incl|snippets].
+	]
+]

data/book/text/getting_started/structure.glyph

@@ -0,0 +1,55 @@
+section[
+	@title[Document Structure]
+	@id[struct]
+
+	p[Every Glyph project contains a code[document.glyph] file that is typically used to define the document structure. The default code[document.glyph] generated automatically when creating a new project is the following:]
+
+	highlight[=html|
+book[
+  @frontmatter[
+    toc[]
+    preface[
+      @title[Preface]
+      todo[Write the preface]
+      include[preface]
+    ]
+  ]
+  @bodymatter[  
+    chapter[ 
+      @title[Chapter 1]
+      todo[Write chapter 1]
+      include[chapter_1]
+    ]
+    chapter[
+      @title[Chapter 2]
+      todo[Write chapter 2]
+      include[chapter_2]
+    ]
+  ]
+  @backmatter[
+    appendix[
+      @title[Appendix A]
+      todo[Write appendix A]
+      include[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 some Chapters and an Appendix.
+
+As you can see, Glyph wraps portions of text within square brackets preceded by an identifier. These identifiers are used for em[\.=>[#macro_intro|macros]] and em[\.=>[#attribute_intro|attributes]]. The only syntactic difference between macros and attributes is that attributes are preceded by a code[@]. 
+
+For now, think about a macro as something that performs a certain action and -- generally -- produces some text output or manipulation of the text inside it. In this way, it becomes easy to understand that the @chapter@ macro creates a chapter and the %>[include] includes an external file, for example.
+Attributes "belong" to the macro they're in, so in this case the %>[book] has the following attributes:
+*  code[@frontmatter]
+*  code[@bodymatter]
+*  code[@backmatter]
+
+More specifically, in this @document.glyph@ file:
+* The %>[book] wraps every other macro and is used to create the document header and default title page.
+* Then, the code[@frontmatter], code[@bodymatter], and code[@backmatter] attributes are used to 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 through code[@title] attributes.
+	]
+]

data/book/text/introduction.glyph

@@ -1,13 +1,12 @@
---[
 &:[prince|=>[http://www.princexml.com/|Prince]]
+Glyph is a _Rapid Document Authoring Framework_. 
 
-]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 &[prince]).
 
-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[
+@title[Main Features]
 
-section[header[Main Features]
-
-Glyph uses a simple macro system to perform a wide variety of advanced tasks:
+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.
@@ -20,20 +19,23 @@ Glyph uses a simple macro system to perform a wide variety of advanced tasks:
 * 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 in other text files.
+* 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 when including files. 
+* 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.
 
 ]
 
-section[header[Installation]
+section[
+@title[Installation]
 
 @gem install glyph@ -- simple, as always.
 
 ]
 
-section[header[Essential Glyph commands]
+section[
+@title[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: 
 
@@ -43,21 +45,33 @@ Glyph is 100% command line. Its interface resambles =>[http://git-scm.com/|Git's
 * @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 &[prince].
 * @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.
 
 ]
 
-section[header[Glyph macros in a nutshell|macros_nutshell]
+section[
+@title[Glyph macros in a nutshell]
+@id[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
+codeblock[=
+section[
+  @title[Something about Glyph]
+  txt[
+You can use Glyph macros in conjunction 
+with _Textile_ or _Markdown_ to
 produce HTML files effortlessly.
-  section[header[What about PDFs?\|pdf]
+  ]
+  p[
+Alternatively, you can just use em[Glyph itself]
+to generate HTML tags.
+  ]
+  section[
+    @title[What about PDFs?]
+    @id[pdf]
 Once you have a single, well-formatted HTML 
 file, converting it to PDF is
 extremely easy with a 3rd-party 
@@ -68,24 +82,33 @@ renderer like =>[http://www.princexml.com\|Prince].
 
 **HTML Output:**
 
-code[=
+codeblock[=
 <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>
+  <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>
+   <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.
+   </p>
   </div>
 </div>
 =]
 ]
 
-section[header[Resources]
+section[
+@title[Resources]
 
 * Home Page: =>[http://www.h3rald.com/glyph/]
 * Repository: =>[http://www.github.com/h3rald/glyph/]
@@ -93,6 +116,6 @@ section[header[Resources]
 * Development Wiki =>[http://wiki.github.com/h3rald/glyph]
 * RubyGem Download =>[http://www.rubygems.org/gems/glyph]
 * Book (PDF): =>[http://github.com/h3rald/glyph/raw/\.%[Glyph::VERSION.strip]/book/output/pdf/glyph.pdf]
-* Reference Documentation: =>[http://yardoc.org/docs/glyph/]
+* Reference Documentation: =>[http://yardoc.org/docs/h3rald-glyph/]
 * User Group: =>[http://groups.google.com/group/glyph-framework]
 ]