glyph 0.4.2 → 0.5.0

data/book/text/stats/snippets.glyph

@@ -1,38 +1,38 @@
 stats_for[
-	@title[all snippets]
-	@object[all snippets]
-	@command[--snippets]
-	@example[
+  @title[all snippets]
+  @object[all snippets]
+  @command[--snippets]
+  @example[
 ===== Snippets
 -- Total Snippets: 21
 -- Total Used Snippets: 21
 -- Total Unused Snippets: 0
 -- Snippets:
-     bin_params             called_on_files        coderay                filter_by_ext          gcode                  
-     glang                  htmlcode               img_attrs              img_file               macros                 
-     markups                only_after_declaration only_defined_through   opt                    prince                 
-     referenced_with_path   sq_esc                 unsafe                 uv                     wkhtml                 
-     yardoc                 
+     bin_params             called_on_files        coderay                filter_by_ext
+     glang                  htmlcode               img_attrs              img_file    
+     markups                only_after_declaration only_defined_through   opt        
+     referenced_with_path   sq_esc                 unsafe                 uv        
+     rubydoc                 
 -- Used Snippets:
-     bin_params             called_on_files        coderay                filter_by_ext          gcode                  
-     glang                  htmlcode               img_attrs              img_file               macros                 
-     markups                only_after_declaration only_defined_through   opt                    prince                 
-     referenced_with_path   sq_esc                 unsafe                 uv                     wkhtml                 
-     yardoc                 
-	]
-	@remarks[
+     bin_params             called_on_files        coderay                filter_by_ext
+     glang                  htmlcode               img_attrs              img_file    
+     markups                only_after_declaration only_defined_through   opt        
+     referenced_with_path   sq_esc                 unsafe                 uv        
+     rubydoc                 
+  ]
+  @remarks[
 * Information on snippet usage and definitions is available only when displaying statistics for a single snippet.
-	]
+  ]
 ]
 stats_for[
-	@title[a single snippet]
-	@object[a single snippet (e.g. code[yardoc])]
-	@command[--snippet=yardoc]
-	@example[
-===== Snippet 'yardoc'
+  @title[a single snippet]
+  @object[a single snippet (e.g. code[rubydoc])]
+  @command[--snippet=rubydoc]
+  @example[
+===== Snippet 'rubydoc'
 -- Definition:
 -------------------
-http://yardoc.org/docs/h3rald-glyph
+http://rubydoc.info/gems/glyph
 -------------------
 -- Total Used Instances: 18
 -- Usage Details:
@@ -43,8 +43,8 @@ http://yardoc.org/docs/h3rald-glyph
    - text/extending/validators.glyph (1)
    - text/macros/macros_core.glyph (2)
    - text/stats/macros.glyph (1)
-	]
-	@remarks[
+  ]
+  @remarks[
 * Nested snippets appear as within the file containing the top-level snippet.
-	]
+  ]
 ]

data/book/text/stats/stats.glyph

@@ -1,25 +1,24 @@
-rewrite:[stats_for|
-	section[
-		@title[Displaying stats about {{title}}]
-		txt[To display statistics about {{object}}, execute code[glyph stats {{command}}]. Glyph displays something like this:]
-		highlight[=html|
+def:[stats_for|
+  section[
+    @title[Displaying stats about {{title}}]
+    txt[To display statistics about {{object}}, execute code[glyph stats {{command}}]. Glyph displays something like this:]
+    highlight[=html|
 {{example}}
-		=]
-		section[
-			@title[Remarks]
-			txt[
+    =]
+    section[
+      @title[Remarks]
+      txt[
 {{remarks}}
-			]
-		]
-	]
+      ]
+    ]
+  ]
 ]
 p[Glyph includes a #>[stats] that can be used to display useful statistics about your Glyph project. If you try running Glyph's command help, you'll see that this command can take quite a few options:
 ]
 highlight[html|
 $ glyph help stats
-=====================================
-Glyph v\.%[Glyph::VERSION]
-=====================================
+Glyph v0.5.0
+
 stats \[options\] 
     Display statistics
 

data/book/text/text_editing/attribute_intro.glyph

@@ -1,22 +1,22 @@
-	txt[
+  txt[
 Although a macro can take any number of parameters, they are often no more than two or three, for readibility reasons: parameters have no name, but their position within a macro is significant.
 
 If you have something like this:
-	]
+  ]
 
-	highlight[=html|custom_image[test.png\|50%\|50%\|Test Image]=]
-	txt[
+  highlight[=html|custom_image[test.png\|50%\|50%\|Test Image]=]
+  txt[
 it may still be easy enough to understand what each parameter is used for, but:
 * you can easily forget that the third parameter is the image width
 * if you don't want to resize the image, you still have to pass _empty parameters_ to the macro, like this: code[=custom_image[test2.png\|\|\|Test Image]=]
 
 To avoid these situations, some macros which would normally take three or four parameters take optional attributes instead, so you can write:
-	]
-	highlight[=html|
+  ]
+  highlight[=html|
 image[test.png
   @width[50%]
   @alt[Test Image]
   @height[50%]
 ]=]
-	p[More verbose, of course, but definitely more readable. In this way, if you won't want to scale an image, you can safely omit the code[@width] and code[@height] attributes.]
-	note[Like parameters, attributes can contain other macros, too.]
+  p[More verbose, of course, but definitely more readable. In this way, if you won't want to scale an image, you can safely omit the code[@width] and code[@height] attributes.]
+  note[Like parameters, attributes can contain other macros, too.]

data/book/text/text_editing/code.glyph

@@ -1,9 +1,9 @@
-	txt[
+  txt[
 If you're a programmer, chances are that you're going to include some source code in your articles and books. Glyph offers two ways to format code blocks effortlessly: the %>[codeblock], which simply wraps text into @<pre>@ and @<code>@ tags, or the %>[highlight]. The last one requires either &[coderay] or &[uv], but it provides syntax highlighting for the most common programming languages.
 
 Cosider the following piece of ruby code:
-	]
-	highlight[=mediawiki|
+  ]
+  highlight[=mediawiki|
 def find_child(&block)
   children.each do \|c\|
     c.descend do \|node, level\|
@@ -12,22 +12,22 @@ def find_child(&block)
   end
   nil
 end
-	=]
-	p[It can be wrapped in a highlight macro, like so:]
-	highlight[=mediawiki|
+  =]
+  p[It can be wrapped in a highlight macro, like so:]
+  highlight[=mediawiki|
 highlight[\=ruby\|
   def find_child(&block)
-    children.each do \\\.\|c\\\.\|
-      c.descend do \\\.\|node, level\\\.\|
+    children.each do \\\/\|c\\\/\|
+      c.descend do \\\/\|node, level\\\/\|
         return node if block.call(node)
       end
     end
     nil
   end
 \=]
-	=]
-	p[...to produce the following, using the $[filters.highlighter] highlighter:]
-	highlight[=ruby|
+  =]
+  p[...to produce the following, using the $[filters.highlighter] highlighter:]
+  highlight[=ruby|
 def find_child(&block)
   children.each do \|c\|
     c.descend do \|node, level\|
@@ -36,11 +36,11 @@ def find_child(&block)
   end
   nil
 end
-	=]
-	box[Some Remarks|
-		txt[
+  =]
+  box[Some Remarks|
+    txt[
 * Highlighters require some configuration. For more information on relevant configuration settings, see the =>[#cfg_filters|filters.*] configuration settings.
 * If you're using the %>[highlight] together within the %>[textile], you must wrap the macro call within @<notextile>@ tags.
 * You must always escape pipes (@\|@) with the code or the highlight macro.
-		]
-	]
+    ]
+  ]

data/book/text/text_editing/conditionals.glyph

@@ -1,4 +1,4 @@
-	txt[
+  txt[
 Sometimes you may want text to be included in a document only if certain conditions are satisfied. For example, you may want to display a disclaimer section only if the document is a draft (see the $>[document.draft]), or use a particular stylesheet only if when you generate a PDF document.
 
 To do so, you can use the %>[condition] (aliased by @?@), and a set of additional macros that can be used as conditional operators i.e.:
@@ -6,16 +6,15 @@ To do so, you can use the %>[condition] (aliased by @?@), and a set of additiona
 * %>[not]
 * %>[and]
 * %>[or]
-* %>[match]
 
 Consider the following code:
-	]
-	highlight[=html|
+  ]
+  highlight[=html|
 ?[$[document.draft]\|
 This is a first draft of the Glyph Book\|
 This is the official version of the Glyph Book]
-	=]
-	txt[
+  =]
+  txt[
 In this case, if @document.draft@ is set to @true@, "This is a first draft of the Glyph Book" will be displayed; if not, "This is the official version of the Glyph Book" will be displayed instead.
 
 The %>[condition] takes up to three parameters:
@@ -24,8 +23,8 @@ The %>[condition] takes up to three parameters:
 # _(Optional)_ the text to include in the document if the condition is _not_ satisfied.
 
 Note that _all_ parameters can contain macros, of course, so you can write things like:
-	]
-	highlight[=html|
+  ]
+  highlight[=html|
 ?[and[
     eq[$[document.output]\|pdf]
     \|
@@ -33,13 +32,13 @@ Note that _all_ parameters can contain macros, of course, so you can write thing
     ]
   \|
   style[pagination.css]]
-	=]
-	p[In this case, the code[pagination.css] stylesheet is included only when you're generating a PDF document using Prince XML.]
+  =]
+  p[In this case, the code[pagination.css] stylesheet is included only when you're generating a PDF document using Prince XML.]
   section[
-		@title[Results of conditional expressions]
-		txt[
+    @title[Results of conditional expressions]
+    txt[
 The %>[condition] in Glyph works in a similar way as conditionals in programming languages: if the conditional expression (supplied as first parameter) is satisfied then the second parameter is executed or displayed. But when is a conditional expression satisfied? Glyph is a simple mini-language to perform text manipulation, and has no types, it can only understand text, therefore:
 * A conditional expression is satisfied if it evaluates to a non-empty string except "false".
 * A conditional expression is not satisfied if it evaluates to an empty string or the string "false".
-		]
+    ]
   ]

data/book/text/text_editing/esc_quot.glyph

@@ -47,7 +47,7 @@ This is another section.
  		]
  		tr[
  			td[code[\\\=]]
-   		td[code[\.=]]
+   		td[code[\/=]]
    		td[Equal signs do not have to be escaped by default, but an escaped equal sign will evaluate to iself.]
  		]
  		tr[
@@ -56,9 +56,9 @@ This is another section.
    		td[Pipes must be escaped (even within quoting macros) unless they are used to separate macro parameters.]
  		]
  		tr[
-   		td[code[\\.]]
+   		td[code[\\/]]
    		td[]
-   		td[An escaped dot evaluates to nothing. Useful to separate macro identifiers from other characters: br[]code[=_\\.=>[#link\|This link is emphasized using Textile]_ =]
+   		td[An escaped dot evaluates to nothing. Useful to separate macro identifiers from other characters: br[]code[=_\\/=>[#link\|This link is emphasized using Textile]_ =]
     	]
   	]
 	]

data/book/text/text_editing/evaluation.glyph

@@ -1,5 +1,59 @@
-	txt[
-&[glang] is not a full-blown programming language and it is currently not Turing-complete (it does not provide loops). However, it is possible to evaluate simple ruby code snippets using the @ruby@ macro (aliased to @%@), like this:
+  §txt[
+    @title[Turing-completeness]
+
+As of version 0.5.0, Glyph can be considered _Turing-complete_, as it satisfies the following =>[http://c2.com/cgi/wiki?LanguageRequirementsForTuringCompleteness|requirements for Turing-completeness]:
+* A conditional construct, implemented via the %>[condition].
+* Variable assignment, by setting the value of snippets using the %>[snippet:] and of attributes using the %>[attribute:].
+* (infinite) iteration implemented through the %>[while] or recursion, which is possible thanks to the %>[define:].
+* A memory model which emulates an infinite store: there are no enforced limits on attribute/snippets allocations and number of algorithms or parameters.
+  ]
+
+  §txt[
+    @title[Operations on integer values]
+
+Glyph can be used to perform operation on integer values (additions, subtractions and multiplications). For example, code[=\/add[2\|3\|7]=] will evaluate to @12@, and code[=\/multiply[add[3\|7]\|subtract[5\|1\|2]]=] will return 20.
+
+As a more complex example, consider the following @factorial@ macro, which is able to calculate the factorial of a number recursively:
+
+highlight[=html|
+def:[factorial\|
+  ?[
+    eq[{{0}}\|0]\|1\|
+    multiply[
+      {{0}} \| factorial[subtract[{{0}}\|1]]
+    ]
+  ]
+]
+=]
+
+If you try executing code[=factorial[5]=], it will evaluate to @120@.
+
+  ]
+  §txt[
+    @title[Lexically-scoped attribute assignment]
+
+=>[#snippets] can be used in a similar way as _variables_ are used in programming languages. Or better, they can be used as _global variables_, as they are visible from anywhere in the Glyph document. If you need something more restricted to, say, a section and all its subsections, you can define your own attributes and use them in a very similar way.
+
+Consider the following Glyph code:
+  ]
+  highlight[=html|
+let[
+  @:[a\|bits]
+  @:[b\|bobs]
+  section[
+    @title[Something more about attributes]
+Attributes are like lexically scoped variables. You can use them to store @[a] and @[b].
+  ]
+]
+  =]
+  txt[
+The %>[let] here only acts as a dummy macro (it does nothing really) to bind attributes using the %>[attribute:] (aliased by code[@:]). Attributes can then be used anywhere within the @let@ macro, so the content of the section reads: "Attributes are like lexically-scoped variables. You can use them to store bits and bobs". 
+
+Note that attributes defined through the %>[attribute:] are... well, attributes! Feel free to use the %>[attribute] to access standard attributes like @title@, etc.
+  ]
+  §txt[
+    @title[Evaluating Ruby code]
+For anything more complex than what described in the previous sections you can also evaluate simple ruby code snippets using the @ruby@ macro (aliased to @%@), like this:
 * code[=%[2 + 2]=] → 4
 * code[=%[Time.now]=] → %[Time.now]
 * code[=%[Glyph::VERSION]=] → %[Glyph::VERSION]
@@ -7,4 +61,4 @@
 The scope for the code evaluation is the Kernel module, (with all inclusions required by Glyph itself). 
 
 Although it is possible to retrieve Glyph configuration settings in this way (e.g. code[=%[cfg('document.author')]=]), the %>[config] (aliased to @$@) makes things slightly simpler (e.g. code[=$[document.author]=]).
-	]
+  ]

data/book/text/text_editing/inclusions.glyph

@@ -1,4 +1,7 @@
-	txt[
+  §[
+    @title[File inclusions]
+    @id[file-inclusions]
+    txt[
 If you're authoring a user manual, a long article, or a book, writing everything inside a single @document.glyph@ file may not be optimal. For this reason, Glyph provides an %>[include] that can be used to include the contents of any file within the @text/@ directory:
 
 code[=include[general/introduction.textile]=]
@@ -10,31 +13,37 @@ When including a text file, an input filter macro is applied to its contents by
 * @.markdown@ or @.md@ → %>[markdown]
 
 You can override this behavior by setting the @filters.by_file_extensions@ configuration setting to @false@. If no extension is specified, @.glyph@ is assumed.
-
-tip[The %>[include] can also be used to include (and evaluate) ruby files (with a @.rb@ extension). In this case, the ruby file must be placed within the @lib/@ directory of the current project.]
-
+    ]
+    §txt[
+      @title[Remarks]
+* The %>[include] can also be used to include (and evaluate) ruby files (with a @.rb@ extension). In this case, the ruby file must be placed within the @lib/@ directory of the current project.
+* The %>[load] macro can be used to include the content of any file _without_ performing any evaluation.
+    ]
+  ]
+  §[
+    @title[Snippets]
+    @id[snippets]
+    txt[
 While including the context of an entire file is definitely a useful feature for content reuse, sometimes it can be an overkill. What if, for example, you just want to reuse a short procedure or even a sentence or a single word? In this case, you may want to consider using a _snippet_ instead.
 
-Snippets are text strings saved in YAML format in the @snippets.yml@ file. They can be included anywhere in your document using the %>[snippet] (or its alias @&@). 
+Snippets can be defined using the %>[snippet:] (aliased by @&:@) and called by using the %>[snippet] (aliased by @&@). Consider the following simple example:
+    ]
+    highlight[=html|
+&:[markups\|Textile or Markdown]
 
-tip[Besides storing snippets in the @snippets.yml@ file, you can also define them right in your document, using the %>[snippet:].]
-	]
-	box[Example|
-	p[Consider the following code[snippets.yml] file:]
-	highlight[=yaml|
---- 
-:glang: Glyph Language
-:macros: Glyph Macros
-:sq_esc: \\\|-
-  Square brackets must be escaped 
-  unless used as macro delimiters or within a quoting macro.
-:markups: Textile or Markdown
-:test: \\\|-
-  This is a 
-  Test snippet
-	=]
-	p[You can use code[=&[markups]=] anywhere in your document instead of having to type "\.&[markups]" every time. Additionally, later on you can change the value of the code[markups] snippet only in the code[snippets.yml] file to change it everywhere else in the document.]
-	] 
-	tip[
+Glyph supports &[markups].
+    =]
+    p[You can use code[=&[markups]=] anywhere in your document instead of having to type "\/&[markups]" every time. Additionally, later on you can change the value of the  code[markups] to change it everywhere else in the document.]
+    tip[
 Snippets (or any other macro) can be nested within other snippets. Glyph takes care of checking if you nested snippets or macros mutually and warns you as necessary.
-	]
+    ]
+  ]
+  §[
+    @title[Fragments]
+    @id[fragments]
+    txt[As an even simpler alternative to snippets, consider using _fragments_. The %>[fragment] (aliased by @##@) can be used to mark a section of Glyph code as a fragment that can then be _embedded_ using the %>[embed] (aliased by @<=@), like this:]
+    
+    highlight[=html|
+Snippets and fragments ##[good_way\|are a good way to reuse] small chunks of content, while the include and load macros <=[good_way] entire files.
+    =]
+  ]

data/book/text/text_editing/macro_composition.glyph

@@ -0,0 +1,28 @@
+txt[
+Glyph macros can be _composed_ with other using the @/@ character. Macro composition can be used instead of nesting, provided that macro containers (also called _dispatchers_ in certain situations) take only one parameter and no attributes.
+
+For example, the following code:
+]
+highlight[=html|
+?[
+  not[output?[pdf]]\|
+  ...
+]
+=]
+
+p[Can be written like this:]
+
+highlight[=html|
+?[
+  not/output?[pdf]\|
+  ...
+]
+=]
+
+txt[
+In this case, the %>[not] was composed with the %>[output?], thus removing one level of nesting.
+
+Composition can be useful to simplify complex Glyph macro constructs, but also for _macro dispatching_. Currently, Glyph supports two _dispatchers_:
+* The %>[s], used to call almost any method of the Ruby String class.
+* The %>[xml], used to render raw XML tags.
+]