glyph 0.4.2 → 0.5.0

data/book/text/config/document.glyph

@@ -3,6 +3,9 @@ The following configuration settings are related to the current Glyph document.
 config_table[
 	ref_config[document.author|
 The author of the document.
+	]
+	ref_config[document.cover|
+The image used as the document cover (used only for e-book generation).
 	]
 	ref_config[document.draft|
 If set to @true@, the document is considered a draft, so =>[#m_draftcomment|draft comments] and =>[#m_todo|todo items] will be displayed.
@@ -24,7 +27,7 @@ The main source file to compile. It can be also be overridden by calling the #>[
 How to process stylesheets. It can be set to one of the following values:
 * @embed@ -- Embed stylesheets within the document.
 * @link@ -- Link stylesheets.
-* @import@ -- Import stylesheets using the code[@import] CSS directive. 
+* @import@ -- Import stylesheets using the code[@import] CSS directive.
 	]
 	ref_config[document.subtitle|
 The subtitle of the document, displayed using the %>[subtitle].
@@ -32,4 +35,7 @@ The subtitle of the document, displayed using the %>[subtitle].
 	ref_config[document.title|
 The title of the document, displayed using the %>[title].
 	]
+	ref_config[document.isbn|
+The ISBN of the document, for e-book generation.
+	]
 ]

data/book/text/config/options.glyph

@@ -2,7 +2,7 @@ The following configuration settings are used to enable or disable specific Glyp
 
 config_table[
 	ref_config[options.filters_by_file_extension|
-If set to @true@, a filter macro is applied to included files, based on their extensions (\.fmi[including files|#incl]).  
+If set to @true@, a filter macro is applied to included files, based on their extensions (\/fmi[including files|#incl]).
 	]
 	ref_config[options.macro_set|
 Determines which macro set will be loaded. It can be set to:
@@ -11,10 +11,10 @@ Determines which macro set will be loaded. It can be set to:
 * core -- Loads core macros only.
 	]
 	ref_config[options.safe_mode|
-Enables Safe Mode (\.fmi[Glyph modes|#modes]).
+Enables Safe Mode (\/fmi[Glyph modes|#modes]).
 	]
 	ref_config[options.url_validation|
-If set to _true_, every external link will be validated (see =>[#links]). 
+If set to _true_, every external link will be validated (see =>[#links]).
 	]
 	ref_config[options.xml_blacklist|
 The XML tags listed here cannot be generated using Glyph code.
@@ -22,4 +22,6 @@ The XML tags listed here cannot be generated using Glyph code.
 	ref_config[options.xml_fallback|
 If set to true, any unknown macro name will considered an XML element (see =>[#other_elements]).
 	]
+	ref_config[options.ebook.converter|
+The full path name of the ebook-convert command. Defaults to /usr/bin/ebook-convert.]
 ]

data/book/text/config/output.glyph

@@ -5,10 +5,13 @@ If set to _true_, the document will be rendered in multiple files, according to
 The extension to use for the output file(s).
 ]
 &:[o_filter_target|
-The output target for filters. It can be set to @html@ (for RedCloth and MarkDown) or @latex@ (RedCloth-only). 
+The output target for filters. It can be set to @html@ (for RedCloth and MarkDown) or @latex@ (RedCloth-only).
 ]
-&:[o_macro_dirs|
-The directories from which macros will be loaded (both in Glyph's home and the current project directory).
+&:[o_through|
+The intermediate format from which a PDF file is generated. It can be set to @html@ or @html5@.
+]
+&:[o_macro_reps|
+The name of the representation file from which macro representation will be loaded.
 ]
 &:[o_layout_dirs|
 The directories from which layout macros will be loaded (both in Glyph's home and the current project directory).
@@ -22,18 +25,48 @@ The name of the layout to use to render the document index file.
 &:[o_base|
 The directory to use as root for all link paths.
 ]
+&:[o_calibre|
+An array of options to configure Calibre. See the =>[http://calibre-ebook.com/user_manual/cli/ebook-convert-3.html|full list].
+]
 These settings are used to configure output-specific options.
 
 
+section[
+	@title[output.epub.*]
+	config_table[
+		out_cfg[epub.extension]
+		out_cfg[epub.filter_target]
+		ref_config[output.epub.generator|
+The external program used to generate EPUB files. It must be set to @calibre@.
+		]
+    out_cfg[epub.calibre]
+		out_cfg[epub.macro_reps]
+		out_cfg[epub.multifile]
+	]
+]
+section[
+	@title[output.mobi.*]
+	config_table[
+		out_cfg[mobi.extension]
+		out_cfg[mobi.filter_target]
+		ref_config[output.mobi.generator|
+The external program used to generate MOBI files. It must be set to @calibre@.
+		]
+    out_cfg[mobi.calibre]
+		out_cfg[mobi.macro_reps]
+		out_cfg[mobi.multifile]
+	]
+]
 section[
 	@title[output.pdf.*]
 	config_table[
 		out_cfg[pdf.extension]
 		out_cfg[pdf.filter_target]
+    out_cfg[pdf.through]
 		ref_config[output.pdf.generator|
 The external program used to generate PDF files. It can be set to @prince@ or @wkhtmltopdf@.
 		]
-		out_cfg[pdf.macro_dirs]
+		out_cfg[pdf.macro_reps]
 		out_cfg[pdf.multifile]
 	]
 ]
@@ -42,7 +75,7 @@ section[
 	config_table[
 		out_cfg[html.extension]
 		out_cfg[html.filter_target]
-		out_cfg[html.macro_dirs]
+		out_cfg[html.macro_reps]
 		out_cfg[html.multifile]
 	]
 ]
@@ -51,7 +84,7 @@ section[
 	config_table[
 		out_cfg[html5.extension]
 		out_cfg[html5.filter_target]
-		out_cfg[html5.macro_dirs]
+		out_cfg[html5.macro_reps]
 		out_cfg[html5.multifile]
 	]
 ]
@@ -64,7 +97,7 @@ section[
 		out_cfg[web.layout_dirs]
 		out_cfg[web.layouts.index]
 		out_cfg[web.layouts.topic]
-		out_cfg[web.macro_dirs]
+		out_cfg[web.macro_reps]
 		out_cfg[web.multifile]
 	]
 ]
@@ -77,7 +110,7 @@ section[
 		out_cfg[web5.layout_dirs]
 		out_cfg[web5.layouts.index]
 		out_cfg[web5.layouts.topic]
-		out_cfg[web5.macro_dirs]
+		out_cfg[web5.macro_reps]
 		out_cfg[web5.multifile]
 	]
 ]

data/book/text/extending/bookmarks_headers.glyph

@@ -1,16 +1,18 @@
-	txt[
-The =>[&[yardoc]/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]:
-	]
+  txt[
+The =>[&[rubydoc]/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]:
+  ]
 
-	highlight[=ruby|
+  highlight[=ruby|
 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>}
+  min_parameters 1
+  max_parameters 2
+  bookmark :id => param(0), :title => param(1), :file => @source_file
+  @data[:id] = param 0
+  @data[:title] = param 1
+  render
 end
-	=] 
+  =] 
 
-	txt[
+  txt[
 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.
-	]
+  ]

data/book/text/extending/command.glyph

@@ -29,7 +29,7 @@ That's it. If you try to run @glyph help@ within your project directory, notice
 	highlight[html|
 $ glyph help
 =====================================
-Glyph v\.%[Glyph::VERSION]
+Glyph v\/%[Glyph::VERSION]
 =====================================
 usage: glyph command \[options\]
 

data/book/text/extending/commands_tasks.glyph

@@ -9,9 +9,9 @@ section[
 	txt[
 Before creating custom Glyph commands and tasks, you should have a basic understanding on how they work, and which commands -- or better, which tasks -- are already available.
 
-The following diagram outlines the relationships between commands and tasks:
+The following diagram outlines the relationships between the default commands and some tasks:
 	]
-	figure[glyph/commands_tasks.png|Glyph default commands and tasks]
+	figure[glyph/commands_tasks.png|Some of Glyph default commands and tasks]
 	txt[
 As you can see:
 * All commands call at at least one task.

data/book/text/extending/internals.glyph

@@ -1,15 +1,15 @@
-	p[If you plan on extending Glyph, knowing how it works inside helps. It is not mandatory by any means, but it definitely helps, especially when creating complex macros.]
-	p[What happens behind the scenes when you call code[glyph compile]? Glyph's code is parsed, analyzed and then translated into text, and here's how:]
-	figure[glyph/document_generation.png|A sequence diagram for document generation]
-	txt[From the diagram, it is possible to divide the document generation process into three phases:
+  p[If you plan on extending Glyph, knowing how it works inside helps. It is not mandatory by any means, but it definitely helps, especially when creating complex macros.]
+  p[What happens behind the scenes when you call code[glyph compile]? Glyph's code is parsed, analyzed and then translated into text, and here's how:]
+  figure[glyph/document_generation.png|A sequence diagram for document generation]
+  txt[From the diagram, it is possible to divide the document generation process into three phases:
 * The _Parsing Phase_ starts when a chunk of Glyph code is passed (by the code[generate:document] Rake task, for example) to a class[Glyph::Interpreter]. The interpreter initializes a class[Glyph::Parser] that parses the code and returns an _Abstract Syntax Tree_ (AST) of class[Glyph::SyntaxNode] objects.
 * The _Analysis Phase_ (Processing) starts when the interpreter method calls the @analyze@ method, instantiating a new class[Glyph::Document]. The @Glyph::Document@ object evaluates the AST expanding all macro nodesth (that's when macros are executed) and generates string.
 * The _Finalization Phase_ (Post-Processing) starts when the interpreter calls the @finalyze@ method, causing the @Glyph::Document@ object to perform a series of finalizations on the string obtained after analysis, i.e. it replaces escape sequences and placeholders.
-	]
-	section[
-		@title[Example: A short note]
-		p[As an example, consider the following Glyph code:]
-		highlight[=html|
+  ]
+  section[
+    @title[Example: A short note]
+    p[As an example, consider the following Glyph code:]
+    highlight[=html|
 fmi[something\|#test]
 ...
 section[
@@ -17,9 +17,9 @@ section[
   @id[test]
 ...
 ]
-		=]
-		p[This simple snippet uses the %>[fmi] to link to a section later on in the document. When parsed, the produced AST is the following:]
-		highlight[=ruby|
+    =]
+    p[This simple snippet uses the %>[fmi] to link to a section later on in the document. When parsed, the produced AST is the following:]
+    highlight[=ruby|
 {:name=>:"--"}
   {:name=>:fmi, :escape=>false}
     {:name=>:"0"}
@@ -44,27 +44,27 @@ section[
       {:value=>"Test Section"}
     {:name=>:id, :escape=>false}
       {:value=>"test"}
-		=]
-		p[This output is produced by calling the code[inspect] method on the AST. Each class[Glyph::SyntaxNode] object in the tree is basically an ordinary Glyph Hash with a parent and 0 or more chidren, so the code snippets above shows how the syntax nodes are nested.]
-		p[The AST contains information about macro, parameter and attribute names, and escaping, and raw text values (the nodes without a code[:name] key), but nothing more.]
-		p[When the AST is analyzed, the resulting textual output is the following:]
-		highlight[=html|
+    =]
+    p[This output is produced by calling the code[inspect] method on the AST. Each class[Glyph::SyntaxNode] object in the tree is basically an ordinary Glyph Hash with a parent and 0 or more chidren, so the code snippets above shows how the syntax nodes are nested.]
+    p[The AST contains information about macro, parameter and attribute names, and escaping, and raw text values (the nodes without a code[:name] key), but nothing more.]
+    p[When the AST is analyzed, the resulting textual output is the following:]
+    highlight[=html|
 <span class="fmi">for more information on something, see ‡‡‡‡‡PLACEHOLDER ¤ 1‡‡‡‡‡
 </span>
-\\\\\.[...\\\\\.]
+\\\\\/[...\\\\\/]
 <div class="section">
 <h2 id="test">Test Section</h2>
-\\\\\.[...\\\\\.]
+\\\\\/[...\\\\\/]
 
 </div>
-		=]
-		p[This looks almost perfect, except that:]
-		ul[
-			li[There's a nasty placeholder instead of a link: this is due to the fact that when the link is processed, there is no code[#text] anchor in the document, but there may be one afterwards (and there will be).]
-			li[There are some escaped brackets.]
-		]
-		p[Finally, when the document is finalized, placeholders and escape sequences are removed and the final result is the following:]
-		highlight[=html|
+    =]
+    p[This looks almost perfect, except that:]
+    ul[
+      li[There's a nasty placeholder instead of a link: this is due to the fact that when the link is processed, there is no code[#text] anchor in the document, but there may be one afterwards (and there will be).]
+      li[There are some escaped brackets.]
+    ]
+    p[Finally, when the document is finalized, placeholders and escape sequences are removed and the final result is the following:]
+    highlight[=html|
 <span class="fmi">for more information on something, 
   see <a href="#test">Test Section</a></span>
 [...]
@@ -73,5 +73,5 @@ section[
 [...]
 
 </div>
-	=]
-	]
+  =]
+  ]

data/book/text/extending/interpreting.glyph

@@ -14,34 +14,73 @@ end
 	txt[
 When the @interpret@ 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 and 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.
+# Document-specific objects (bookmarks, headers, snippet, fragments, placeholders, etc.) are passed from the main document to the new one. Because they are stored in arrays and 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[
-		@title[Rewriting]
+  §[
+    @title[Dispatching]
+    txt[
+=>[#composition] can be useful to remove nesting, but you can also use it to create your own macro _dispatchers_. What is a macro dispatcher? The easies way to understand this is by looking at the source code of one of them, the %>[s]:
+    ]
+    highlight[=ruby|
+macro :s do
+	dispatch do \|node\|
+		forbidden = [:each, :each_line, :each_byte, :upto, :intern, :to_sym, :to_f]
+		meth = node[:name]
+		infer_type = lambda do \|str\|
+      # Code omitted...
+		end
+		macro_error "Macro 's/#{meth}' takes at least one parameter" unless node.params.length > 0
+		macro_error "String method '#{meth}' is not supported" if meth.in?(forbidden) \|\| meth.to_s.match(/\!$/)
+		str = node.param(0).evaluate(node, :params => true)
+		begin
+			if node.param(1) then
+				meth_params = node.params[1..node.params.length-1].map do \|p\| 
+          infer_type.call(p.evaluate(node, :params => true))
+        end
+				str.send(meth, *meth_params).to_s
+			else
+				str.send(meth).to_s
+			end
+		rescue Exception => e
+      # Code omittted
+		end
+	end
+end
+    =]
+    txt[
+See the @dispatch@ method at the very beginning? This method takes a block with a @node@ parameter, corresponding to the MacroNode of the macro which is being composed with @s@. So, for example, if you write code[=s/sub[my string\|/my/\|your]=] the node of a macro called @sub@ will be passed to the block. Of course there's no @sub@ macro defined in Glyph, but it doesn't matter: its name will be interpreted as the name of a method of the Ruby String class in this case, so no worries.
+
+Got it? Tricky, but damn useful to create your own "dynamic" macros.
+    ]
+
+  ]
+
+	§[
+		@title[Defining macros using Glyph]
 		@id[rewriting]
-		p[While the code[interpret] method is useful to evaluate Glyph code in a macro while performing other actions (storing a bookmark, checking for the presence of an anchor, etc.), in some cases it may not be necessary. If you simply want your macro to be converted into existing Glyph macro without performing any action excepting parameter substitution, you can just use the %>[rewrite:] within youy Glyph document]
+		p[While the code[interpret] method is useful to evaluate Glyph code in a macro while performing other actions (storing a bookmark, checking for the presence of an anchor, etc.), in some cases it may not be necessary. If you simply want your macro to be converted into existing Glyph macro without performing any action excepting parameter substitution, you can just use the %>[define:] within your Glyph document]
 		p[Consider the following macro definition:]
 		highlight[=ruby|
 macro :issue do
   interpret %{
     tr[
-      td[\.=>[http://github.com/h3rald/glyph/issues/closed#issue/#{param[0]}\|##{param(0)}]]
+      td[\/=>[http://github.com/h3rald/glyph/issues/closed#issue/#{param[0]}\|##{param(0)}]]
       td[txt[#{param(1)}]]
     ]
   }
 end
 		=]
-		p[The code[issue] macro is only rewriting existing Glyph code around the two parameters provided. In this case, it is possible to do exactly the same thing using the %>[rewrite:]:]
+		p[The code[issue] macro is only rewriting existing Glyph code around the two parameters provided. In this case, it is possible to do exactly the same thing using the %>[define:] (aliased by @def:@):]
 		highlight[=html|
-rewrite:[issue\|
+define:[issue\|
   tr[
-    td[\.=>[http://github.com/h3rald/glyph/issues/closed#issue/{{0}}\|#{{0}}]]
+    td[\/=>[http://github.com/h3rald/glyph/issues/closed#issue/{{0}}\|#{{0}}]]
     td[txt[{{1}}]]
   ]
 ]
 		=]
-		p[Within the %>[rewrite:], it is possible to use a special syntax to call the code[raw_attr] or code[raw_param] methods: br[]
+		p[Within the %>[define:], it is possible to use a special syntax to call the code[raw_attr] or code[raw_param] methods: br[]
 			code[{{]em[parameter_number] or em[attribute_name]code[}}]]
 	]

data/book/text/extending/macro_def.glyph

@@ -1,42 +1,42 @@
-	txt[
+  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|
+    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|
+  ]
+  highlight[=ruby|
 macro :note do
   %{<div class="#{@name}"><span class="note-title">#{@name.to_s.capitalize}</span>
-		#{@value}
+    #{@value}
 
     </div>}
 end
-	=]
-	txt[
+  =]
+  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"?|
+    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[
+  ]
+  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.) 
@@ -45,15 +45,63 @@ A class[Glyph::MacroNode] containing information about the macro. Useful for acc
 * @: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.).]
-  	]
-	]
+        ]
+      ]
+    ]
+    tr[
+      td[code[@name]]
+      td[The name of the macro.]
+    ]
+    tr[
+      td[code[@source_name]]
+      td[A code[String] identifying the source of the macro (a file, a snippet, etc.).]
+    ]
+    tr[
+      td[code[@source_topic]]
+      td[A code[String] identifying the source topic of the macro.]
+    ]
+    tr[
+      td[code[@source_file]]
+      td[A code[String] identifying the source file of the macro.]
+    ]
+  ]
+  §[
+    @title[Representations]
+    txt[
+There's a small problem with the code used to define the @note@ macro in the previous section: what if I want to format notes using HTML5 instead of HTML, or another output format?
+
+Glyph supports different output formats, therefore macros must be format-independent! In fact, this is the actual source of the @note@ macro:
+    ]
+    highlight[=ruby|
+macro :note do
+  @data[:name] = @name
+  @data[:text] = value
+  render
+end
+    =]
+    txt[
+The HTML representation of the note macro is defined in the @macros/reps/html.rb@ file as follows:
+    ]
+    highlight[=ruby|
+rep :note do \|data\|
+	css_class = data[:name].to_s.match(/[a-z0-9_-]/i) ? data[:name] : "note"
+	%{<div class="#{css_class}">
+<span class="note-title">#{data[:name].to_s.capitalize}</span>#{data[:text]}
+
+</div>}
+end
+    =]
+    txt[
+The HTML5 representation of the note macro, on the other hand, is defined in the @macros/reps/html5.rb@ file as follows:
+    ]
+    highlight[=ruby|
+rep :note do \|data\|
+	css_class = data[:name].to_s.match(/[a-z0-9_-]/i) ? data[:name] : "note"
+	%{<aside class="#{css_class}">
+<span class="note-title">#{data[:name].to_s.capitalize}</span>#{data[:text]}
+
+</aside>}
+end
+    =]
+Note the different tags used to render the note. 
+  ]