glyph 0.2.0 → 0.3.0

data/book/resources/document_generation.txt

@@ -0,0 +1,34 @@
+participant generate_document
+participant Interpreter
+participant Parser
+participant Document
+participant SyntaxNode
+participant Macro
+
+
+generate_document->Interpreter: new
+Interpreter->Parser: new
+generate_document->Interpreter: parse
+Interpreter->Parser: parse
+Parser-->Interpreter: tree (SyntaxNode)
+Interpreter->Document: new
+generate_document->Interpreter: process
+Interpreter->Document: analyze
+loop Processing
+ Document->SyntaxNode: evaluate
+ alt if macro node
+  SyntaxNode->Macro: expand
+ end
+end
+Document-->Interpreter: :analized
+generate_document->Interpreter: postprocess
+Interpreter->Document: finalize
+loop Post-processing
+ note over Document
+  Replace all escape sequences
+  and placeholders in the
+  final text output
+ end note
+end
+Document-->Interpreter: :finalized
+Interpreter-->generate_document: document

data/book/snippets.yml

@@ -10,3 +10,9 @@
 :only_after_declaration: "can only be used _after_ its declaration"
 :coderay: "=>[http://coderay.rubychan.de/|Coderay]"
 :uv: "=>[http://ultraviolet.rubyforge.org/|Ultraviolet]"
+:yardoc: "http://yardoc.org/docs/h3rald-glyph"
+:unsafe: "This macro cannot be used in =>[#modes|safe mode]."
+:bin_params: "-p[0|The first expression to test]-p[1|The second expression to test]"
+:img_file: "The name of the image file (relative to the code[images/] folder)."
+:img_attrs: "Any attribute supported by the =>[http://www.w3schools.com/tags/tag_IMG.asp|img tag]."
+:opt: "em[(optional)]"

data/book/text/changelog.glyph

@@ -1,54 +1,65 @@
 %[=
-macro :issue do
-	exact_parameters 2
-	ident, desc = @params
-	encode %{
-		tr[
-			td[\=>[http://github.com/h3rald/glyph/issues/closed#issue/#{ident}\|##{ident}]]
-			td[textile[#{desc}]]
-		]
-	}
-end
-
 macro :features do
 	verb = (@name == :features) ? "Implemented" : "Fixed"
-	total = @node.children.length
-	encode %{
-		section[header[#{total} #{@name.to_s.capitalize} #{verb}]
+	total = @node.children[0].children.length
+	interpret %{
+		section[
+			@title[#{total} #{@name.to_s.capitalize} #{verb}]
 			table[
 				tr[
 					th[ID]
 					th[Description]
 				]
-				#@value
+				#{@node.value}
 			]
 		]
 	}
 end
 
-macro :release do
-	exact_parameters 3
-	number, date, contents = @params
-	interpret %{
-		section[header[v#{number} – #{date}]
-			#{decode contents}
-		]
-	}
-end
-
-
 macro_alias :bugs => :features
-
-=]--[
-	?[%[lite?]|*[=
-			%:[%>|"#@value macro"]
-			%:[#>|"#@value command"]
-		=]
+=]
+rw:[release|
+	section[
+		@title[v{{0}} – {{1}}]
+		{{2}}
+	]
+]
+rw:[issue|
+	tr[
+		td[\.=>[http://github.com/h3rald/glyph/issues/closed#issue/{{0}}|#{{0}}]]
+		td[txt[{{1}}]]
+	]
+]
+?[%[lite?]|
+	%:[%>|"#{value} macro"]
+	%:[#>|"#{value} command"]
+	%:[$>|"#{value} setting"]
+]
+release[0.3.0|June 13th 2010|
+	features[
+		issue[39|A new #>[outline] is available to display the document outline.]
+		issue[110|It is now possible to use Glyph language to produce arbitrary XML code.]
+		issue[111|System settings are now stored within a @system.*@ namespace and cannot be changed via the %>[config:] or the #>[config].]
+		issue[116|It is now possible to use named attributes within Glyph macros.]
+		issue[119|#[new_parser]A new parser was implemented from scratch to improve performance. Treetop gem no longer required.]
+		issue[121|Some macros have been removed in favor of XML fallback, others have been updated.]
+		issue[123|The SyntaxNode class has been specialized to differentiate between macros, attributes, parameters, text and escapes.]
+		issue[124|Implemented new %>[article] and %>[book].]
+		issue[126|A new %>[rewrite:] has been implemented to create simple macros using just Glyph code.]
+		issue[127|A new %>[alias] has been implemented to create macro aliases.]
+		issue[128|A blacklist for XML tags has been exposed via the $>[language.options.xml_blacklist].]
+		issue[129|The %>[include] can now be used in lite mode, it can evaluate ruby files and requires relative paths.]
+		issue[130|A new "safe mode" has been implemented to explicitly forbid certain potentially unsafe macros.]
+	]
+	bugs[
+		issue[109|Performance has been dramatically improved by implementing a parser from scratch (see =>[#new_parser|#119])]
+		issue[122|Macro encoding/decoding no longer necessary due to the new parser (see =>[#new_parser|#119])]
+		issue[125|Warning messages have been streamlined.]
 	]
 ]
 release[0.2.0|May 9th 2010|
 	features[
-		issue[62|A new %>[highlight] is available to highlight source code (CodeRay or UltraViolet requireed).]
+		issue[62|A new %>[highlight] is available to highlight source code (CodeRay or UltraViolet required).]
 		issue[76|It is now possible to use Glyph programmatically via the new @Glyph#filter@ and @Glyph#compile@ methods.]
 		issue[87|It is now possible to define snippets inside a Glyph source file using the %>[snippet:].]	
 		issue[88|It is now possible to change configuration settings inside a Glyph source file using the %>[config:] (Jabbslad).]	
@@ -68,7 +79,7 @@ release[0.2.0|May 9th 2010|
 		issue[101|Additional tests have been developed to improve Textile support. There should no longer be errors when using textile block elements inside Glyph macros.]
 		issue[103|Fixed a bug that caused test failures when deleting the test project directory.]
 		issue[104|Nested Glyph macros calling @Macro#interpret@ no longer ignore escape delimiters.]
-		issue[107|Added the possibility to encode (using the %>[encode]) and decode (using the %>[decode]) macros so that they can be interpreted later.]
+		issue[107|Added the possibility to encode (using the @encode@ macro) and decode (using the @decode@ macro) macros so that they can be interpreted later.]
 	]
 ]
 release[0.1.0|April 8th 2010|

data/book/text/compiling/compiling.glyph

@@ -0,0 +1,23 @@
+section[
+	@title[Compiling a project]
+	@id[compile]
+	p[By default, a Glyph project can be "compiled" into an HTML document. Additionally, Glyph can also be used to produce PDF documents through &[prince], and in future releases more output targets will be supported.]
+	section[
+		@title[HTML output]
+		p[To compile a Glyph project to an HTML document, use the #>[compile] within your Glyph project folder. Glyph parses the code[document.glyph] file (and all included files and snippets); if no errors are found, Glyph creates an HTML document in the code[/output/html] folder.] 
+		p[The name of the HTML file can be set in the configuration (\.$>[document.filename]).]
+	]
+	section[
+		@title[PDF Output]
+		p[To generate a PDF document, you must specify code[pdf] as format, like this:]
+		p[code[= glyph compile -f pdf =]]
+		p[The command above will attempt to compile the project into an HTML document and then call Prince to generate a PDF document from it. In order for this to work, you must download and install &[prince]. It's not open source, but the free version is fully functional, and it just adds a small logo on the first page.]
+		note[Glyph v\.%[Glyph::VERSION] has been successfully tested with Prince v7.0, and the PDF version of this very book was generated with it.]
+	]
+	section[
+		@title[Auto Regeneration]
+		@id[auto_regeneration]
+		txt[You can also call the #>[compile] with a @--auto@ switch. If you do so, your project will be recompiled automatically every time any source file is changed.]
+		note[Auto regeneration requires the =>[http://rubygems.org/gems/directory_watcher|directory_watcher] gem to be installed.]
+	]
+]

data/book/text/compiling/lite_mode.glyph

@@ -0,0 +1,23 @@
+section[
+	@title[Compiling single Glyph files]
+	@id[lite_mode]
+	p[Glyph's primary goal is to author complex documents like books or manuals. In order to do so, a Glyph project is required to keep everything organized and automated via a set of predefined conventions, exactly like Ruby on Rails or other similar frameworks do.]
+	p[If you want to write a one-page article or a short draft, however, creating and managing Glyph projects can be an unnecessary burden. Luckily, you don't have to: you can use Glyph to compile single files containing Glyph code, by adding one parameter (or two if you want to specify a custom destination file) to the #>[compile], like this:]
+	p[code[glyph compile source.glyph destination.htm]]
+	p[This command will process a file called code[source.glyph] and produce an HTML file called code[destination.htm].]
+	section[
+		@title[Limitations]
+		@id[lite_limitations]
+		&:[only_defined_through|can only be defined inside the source file, using the]
+		txt[
+&:[referenced_with_path|must be referenced with their absolute path, or a path relative to the current directory]
+This sort of "lite" mode comes with a few minor limitations: 
+* Snippets &[only_defined_through] %>[snippet:].
+* Project configuration settings &[only_defined_through] %>[config:].
+* Custom macros &[only_defined_through] %>[macro:].
+* Images &[referenced_with_path], and will not be copied anywhere when the output file is generated.
+* Stylesheets &[referenced_with_path], or the name of an existing Glyph =>[#default_stylesheets|system stylesheet].
+* The files included through the %>[include] &[referenced_with_path].
+		]
+	]
+]

data/book/text/compiling/programmatic_usage.glyph

@@ -0,0 +1,77 @@
+section[
+	@title[Using Glyph programmatically]
+	txt[
+Besides using Glyph from the command line, you can also use it straight from your code. Glyph's public =>[http://yardoc.org/docs/glyph/Glyph|API] is simple and can be used to:
+* Retrieve and update configuration settings (using @Glyph\[\]@ and @Glyph\[\]=@)
+* Filter text to HTML (using @Glyph#filter@)
+* Compile Glyph source files into HTML or PDF files (using @Glyph#compile@)
+
+That's pretty much it. Of course, both the @filter@ and @compile@ method cause Glyph to run in =>[#lite_mode|_lite_ mode], so the same =>[#lite_limitations|limitations] apply. 
+	]
+	tip[
+		txt[
+For an example on how to use Glyph programmatically (specifically in conjunction with the =>[http://nanoc.stoneship.org/|nanoc] static site generator), see =>[http://github.com/h3rald/h3rald|h3rald.com source code], in particular:
+* =>[http://github.com/h3rald/h3rald/blob/master/lib/glyph-data.rb|lib/glyph-data.rb] -- updating configuration settings.
+* =>[http://github.com/h3rald/h3rald/blob/master/lib/glyph-filter.rb|lib/glyph-data.rb] -- using the @Glyph#filter@ method.
+* =>[http://github.com/h3rald/h3rald/blob/master/Rules|Rules] -- using the @Glyph#compile@ method to generate PDF files.
+		]
+	]
+	section[
+		@title[Modes]
+		@id[modes]
+		p[It is possible to specify some flags (or "modes") to make Glyph behave slightly different than normal, as shown in the following table (by default, none of these is used).]
+		table[
+			tr[
+				th[Name]
+				th[Writer Method]
+				th[Reader Method]
+				th[Description]
+			]
+			tr[
+				td[Test Mode]
+				td[code[Glyph.test_mode=]]
+				td[code[Glyph.test?]]
+				td[Used internally by the code[rake spec] task to run Glyph's specs.]
+			]
+			tr[
+				td[Library Mode]
+				td[code[Glyph.library_mode=]]
+				td[code[Glyph.library?]]
+				td[If enabled, the #>[compile] command will raise exceptions instead of printing errors on the screen. Enabled by the code[Glyph.compile] command.]
+			]
+			tr[
+				td[Debug Mode]
+				td[code[Glyph.debug_mode=]]
+				td[code[Glyph.debug?]]
+				td[If enabled, additional diagnostic information (such as backtraces or macro values) will be displayed. Enabled by specifying the =>[#debug_switch|debug switch] when running a Glyph command.]
+			]
+			tr[
+				td[Lite Mode]
+				td[code[Glyph.lite_mode=]]
+				td[code[Glyph.lite?]]
+				td[
+					txt[
+Used to compile =>[#lite_mode|single files]. Enabled by:
+* The @Glyph.compile@ and @Glyph.filter@ methods.
+* The #>[compile], if at least one parameter is supplied.
+					]
+				]
+			]
+			tr[
+				td[Safe Mode]
+				td[code[Glyph.safe_mode=]]
+				td[code[Glyph.safe?]]
+				td[
+					txt[
+If enabled, the following macros cannot be used and will return an error:
+* %>[ruby]
+* %>[macro:]
+* %>[include]
+* %>[rewrite:]
+* %>[config:]
+					]
+				]
+			]
+		]
+	]
+]

data/book/text/extending/bookmarks_headers.glyph

@@ -0,0 +1,21 @@
+section[
+	@title[Bookmarks and Headers]
+	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]:
+	]
+
+	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>}
+end
+	=] 
+
+	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/further_reading.glyph

@@ -0,0 +1,13 @@
+section[
+	@title[Further Reading]
+	txt[
+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:
+* class[Glyph::Parser]
+* class[Glyph::SyntaxNode]
+* class[Glyph::Interpreter]
+* class[Glyph::Document]
+* class[Glyph::Macro]
+	]
+]

data/book/text/extending/internals.glyph

@@ -0,0 +1,79 @@
+section[
+	@title[A quick look at Glyph's internals]
+	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[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|
+fmi[something\|#test]
+...
+section[
+  @title[Test 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|
+{:name=>:"--"}
+  {:name=>:fmi, :escape=>false}
+    {:name=>:"0"}
+      {:value=>"something"}
+    {:name=>:"1"}
+      {:value=>"#test"}
+  {:value=>"\\n"}
+  {:value=>"\\\\[", :escaped=>true}
+  {:value=>"..."}
+  {:value=>"\\\\]", :escaped=>true}
+  {:value=>"\\n"}
+  {:name=>:section, :escape=>false}
+    {:name=>:"0"}
+      {:value=>"\\n\\t"}
+      {:value=>"\\n\\t"}
+      {:value=>"\\n"}
+      {:value=>"\\\\[", :escaped=>true}
+      {:value=>"..."}
+      {:value=>"\\\\]", :escaped=>true}
+      {:value=>"\\\n"}
+    {:name=>:title, :escape=>false}
+      {: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|
+<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|
+<span class="fmi">for more information on something, see <a href="#test">Test Section</a></span>
+[...]
+<div class="section">
+<h2 id="test">Test Section</h2>
+[...]
+
+</div>
+	=]
+	]
+]

data/book/text/extending/interpreting.glyph

@@ -0,0 +1,51 @@
+section[
+	@title[Interpreting Glyph Code]
+	@id[interpreting]
+
+	txt[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:]
+
+	highlight[=ruby|
+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
+	=] 
+
+	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.
+# 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]
+		@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[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[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:]:]
+		highlight[=html|
+rewrite:[issue\|
+  tr[
+    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[]
+			code[{{]em[parameter_number] or em[attribute_name]code[}}]]
+	]
+]