glyph 0.2.0 → 0.3.0

data/book/text/text_editing/code.glyph

@@ -0,0 +1,51 @@
+section[
+	@title[Source Code]
+	@id[source_code]
+	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|
+def find_child(&block)
+  children.each do \|c\|
+    c.descend do \|node, level\|
+      return node if block.call(node)
+    end
+  end
+  nil
+end
+	=]
+	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\\\.\|
+        return node if block.call(node)
+      end
+    end
+    nil
+  end
+\=]
+	=]
+	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\|
+      return node if block.call(node)
+    end
+  end
+  nil
+end
+	=]
+	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

@@ -0,0 +1,49 @@
+section[
+	@title[Conditional Macros]
+	@id[cond_macros]
+	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.:
+* %>[eq]
+* %>[not]
+* %>[and]
+* %>[or]
+* %>[match]
+
+Consider the following code:
+	]
+	highlight[=html|
+?[$[document.draft]\|
+This is a first draft of the Glyph Book]
+?[not[$[document.draft]]\|
+This is the official version of the Glyph Book]
+	=]
+	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 two parameters:
+* the first one is the condition to evaluate
+* the second one is the text to include in the document only if the condition is satisfied.
+
+Note that _both_ parameters can contain macros, of course, so you can write things like:
+	]
+	highlight[=html|
+?[and[
+    eq[$[document.output]\|pdf]
+    \|
+    eq[$[tools.pdf_generator]\|prince]
+    ]
+  \|
+  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.]
+  section[
+		@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/evaluation.glyph

@@ -0,0 +1,13 @@
+section[
+	@title[Evaluating Ruby code and Configuration Settings]
+	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:
+* code[=%[2 + 2]=] → 4
+* code[=%[Time.now]=] → %[Time.now]
+* code[=%[Glyph::VERSION]=] → %[Glyph::VERSION]
+
+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/glyph_files.glyph

@@ -0,0 +1,7 @@
+section[
+	@title[.glyph files]
+	txt[
+The @text@ folder of any Glyph folder contains all the text source files used to produce a document. Although there are no restrictions on the extension of the files in this folder, you may want to use @.glyph@, especially if =>[http://www.vim.org|Vim] is your favorite text editor.
+The reason is simple: a Glyph syntax file is =>[http://www.vim.org/scripts/script.php?script_id=3086|available on vim.org]. Although not essential, syntax highlighting does help when editing Glyph files. 
+	]
+]

data/book/text/text_editing/images.glyph

@@ -0,0 +1,29 @@
+section[
+	@title[Images and Figures]
+	@id[img_fig]
+	p[Same as for =>[#links|links], you can also include images and figures using &[markups]. If you want additional features, you can use the %>[image] and the %>[figure], as shown in the following example:]
+
+	box[Example|
+		p[&[gcode]]
+		highlight[=html|
+image[glyph.svg
+  @with[20%]
+  @height[20%]
+]
+figure[example.png\|An example figure.
+  @alt[Example Figure]
+]
+	=]
+		p[&[htmlcode]]
+		highlight[=html|
+<img src="images/glyph.svg" width="20%" height="20%" />
+<div class="figure">
+  <img src="images/example.png" alt="Example Figure"/>
+  <div class="caption">An example figure.</div>
+</div>
+	=]
+		txt[Any attribute passed to the %>[image] or the %>[figure] is automatically passed to the underlying @<img>@ tag.]
+	]
+	note[In future releases, figures will be numbered automatically and included in a em[List of Figures] section.]
+] 
+

data/book/text/text_editing/inclusions.glyph

@@ -0,0 +1,44 @@
+section[
+	@title[Including Files and Snippets]
+	@id[incl]
+	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]=]
+
+The macro call above loads the contents of the @introduction.textile@ file, within the @text/general@ directory.
+
+When including a text file, an input filter macro is applied to its contents by default, based on the file extension used:
+* @.textile@ or @.txt@ → %>[textile]
+* @.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.]
+
+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 @&@). 
+
+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[
+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.
+	]
+]

data/book/text/text_editing/links.glyph

@@ -0,0 +1,53 @@
+section[
+	@title[Links and Bookmarks]
+	@id[links]
+	txt[
+Lightweight markups let you create internal and external links in a very easy way, and you can still do so in Glyph. However, if you do so:
+* you can't check if they are valid
+* you can't infer the link title automatically
+
+If you care about link validation and you want to save some keystrokes, then you should use:
+* the %>[link] (aliased to @=>@) -- to create internal and external links.
+* the %>[anchor] (aliased to @#@) -- to create named anchors (bookmarks) within your document.
+	]
+	box[Example|
+		p[&[gcode]]
+		highlight[=html|
+This is a link to link[#test].
+...
+This is link[#wrong].
+This is a #[test\\\|test anchor].
+		=]
+		p[&[htmlcode]]
+		highlight[=html|
+<p>This is a link to <a href="#test">test anchor</a>.</p>
+<p>...</p>
+<p>This is <a href="#wrong">#wrong</a>.</p>
+<p>This is a <a id="test">test anchor</a>.</p>
+		=]
+		p[Additionally, the following warning message is displayed when =>[#compile|compiling]:]
+		highlight[=html|
+warning: Bookmark 'wrong' does not exist
+ -> source: @: authoring.textile
+ -> path: document/body/bodymatter/chapter/@/textile/section/section/box/link
+		=]
+	]
+	txt[
+Basically, if you use the %>[link] and the %>[anchor], Glyph makes sure that:
+* all links point to valid anchors within the document (regardless if the anchors are before or after the link, in snippets or included files).
+* there are no duplicate anchors within the documents.
+* if no title is specified as second parameter for the %>[link], the anchor's name is used as such.
+
+Besides using the %>[anchor], you can also create an anchor for a header by passing an code[@id] attribute the the %>[section], like this: 
+	]
+	highlight[=html|
+section[
+  @title[My Section]
+  @id[my_section]
+...
+]
+	=]
+	note[
+At present, link validation and automatic title retrieval only works with internal links (i.e. the check occurs if the first parameter of the %>[link] starts with a code[#]). In the future, the macro could be extended to support external (http) links as well. 
+	]
+]

data/book/text/text_editing/macro_intro.glyph

@@ -0,0 +1,111 @@
+section[
+	@title[Introducing &[macros]]
+	@id[macro_intro]
+	txt[
+The most important concept to grasp about Glyph is the concept of _macro_.
+
+A Glyph macro is, in a nutshell, an identifier of some kind that wraps a value or parameters within square brackets. More specifically:
+* The macro identifier can contain _any_ character except for: @\[@, @\]@, @\\@, @\|@, code[@] or spaces.
+* The delimiters can be either @\[@ and @\]@ or @\[=@ and @=\]@ (\.fmi[differences between delimiters|#esc_quot]). 
+* The value can be anything, even other macros. If a macro supports more than one parameter, they must be separated with @\|@. For example, the %>[link] can take an optional second parameter for the link text: @\..[=link[#link_id\|This is the link text]=]@.
+* A macro can also have _attributes_, which look exactly like macros but their identifier starts with a code[@].
+
+A macro can often have one or more aliases. For example, @=>@ is an alias for the %>[link], so the following macro calls are equivalent:
+* code[=\.=>[#test\|Test Section]=]
+* code[=\.link[#test\|Test Section]=]
+	]
+]
+section[
+	@title[Macro attributes]
+	@id[attribute_intro]
+	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[
+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|
+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.]
+]
+section[
+	@title[Escaping and Quoting]
+	@id[esc_quot]
+	txt[
+Glyph doesn't require any special control characters like LaTeX, and its macro syntax is very straightforward and liberal. This however comes with a price: because square brackets are used as delimiters, you must escape any square bracket in your text with a backslash. That's not _too_ bad if you think about it, unless you're writing programming code, in which case escaping every single square bracket can be painful.
+
+If a portion of your text contains an excessive amount of square brackets, you may consider using the %>[escape] (or its alias @.@) with the @\[=@ and @=\]@ delimiters. By itself, the escape macro doesn't do anything: it just evaluates to its contents, but the special delimiters act as an escape for any square bracket within them. As a consequence, any macro within @\[=@ and @=\]@ will _not_ be evaluated.
+
+You can use the quoting delimiters with _any_ macro identifier. Obviously, using them as delimiters for things like %>[section]s may not be a good idea, but they should be more or less mandatory with the %>[codeblock] or the %>[highlight], especially when it contains square brackets or even Glyph code, like this:
+	]
+
+	highlight[=html|
+codeblock\[=
+  section[
+    @title[A section]
+    @id[test]
+This is a section.
+    section[
+    @title[A nested section]
+This is another section.
+    ]
+  ]
+\=]
+	=]
+
+	note[Although quoting delimiters allow you to use square brackets without escaping them, you must still escape them if you want to escape quoting delimiters themselves.]
+
+	p[Besides square brackets, there are other characters that must or can be escaped with backslashes, as shown in the following table:]
+
+	table[
+ 		tr[
+   		th[Escape Sequence]
+   		th[Evaluates to...]
+   		th[Notes]
+ 		]
+ 		tr[
+ 			td[code[\\\.\[]]
+   		td[code[\[]]
+   		td[&[sq_esc]]
+  		]
+ 		tr[
+   		td[code[\\\.\]]]
+   		td[code[\]]]
+   		td[&[sq_esc]]
+ 		]
+ 		tr[
+   		td[code[\\\\]]
+   		td[code[\\]]
+   		td[Backslashes do not have to be escaped by default, but an escaped backslash will evaluate to itself.]
+ 		]
+ 		tr[
+ 			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[
+   		td[code[\\\.\|]]
+   		td[code[\|]]
+   		td[Pipes must be escaped (even within quoting macros) unless they are used to separate macro parameters.]
+ 		]
+ 		tr[
+   		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]_ =]
+    	]
+  	]
+	]
+] 

data/book/text/text_editing/raw_html.glyph

@@ -0,0 +1,112 @@
+section[
+txt[So far we examined how to create @<div>@ tags for sections, links, images... but what about lists, tables or paragraphs? How is it possible to create them using Glyphs? You have two possibilities (besides using raw HTML code, that is):
+* use a lightweight markup supported by Glyph (currently &[markups])
+* rely Glyph's _XML fallback_ feature
+]
+	@title[Other HTML Elements]
+	@id[other_elements]
+	section[
+		@title[&[markups]]
+		p[&[markups] are very easy and intuitive to use, and they can produce HTML markup with almost no effort. Using them with Glyph is as simple as using the %>[textile] (aliased to code[txt]) and the %>[markdown] (aliased to code[md]).]
+		box[Example|
+			p[The following Glyph code:]
+			highlight[=html|
+textile[
+This is a paragraph with some _emphasized_ text.
+
+This is another paragraph with some -deleted- text.
+* This is
+* a bulletted
+* list
+]
+			=]
+			p[produces the following HTML code:]
+			highlight[=html|
+<p>This is a paragraph with some <em>emphasized</em> text.</p>
+<p>This is a paragraph with some <del>deleted</del> text.</p>
+<ul>
+  <li>This is</li>
+  <li>a bulletted</li>
+  <li>list</li>
+</ul>
+			=]
+		]
+		important[Be careful when using block-level HTML with Textile and Markdown: sometimes it may be necessary to add extra empty lines or escape tags.]
+	]
+	section[
+		@title[XML Fallback]
+		p[Sure Textile and Markdown are great, but sometimes you may want to just use HTML, without the extra verbosity, of course. Take tables for example: Textile offers an easy way to create them, but things may get dirty when you need to have multiple paragraphs or lists within cells.]
+		p[Very early versions of Glyph used to offered some simple code[table], code[tr], code[tr], code[td] macros just for that. Of course the problem was that thy didn't offer any way to customize the markup by adding, for example, CSS classes.]
+		p[Instead, by default, Glyph can convert any unrecognized macro to the corresponding XML element and macro attributes to XML attributes.]
+		box[Example|
+			p[&[gcode]]
+			highlight[=html|
+table[@class[features]
+  tr[
+		th[ID]
+		th[Priority]
+		th[Description]
+  ]
+  tr[
+    td[27]
+    td[span[@style[color:red;font-weight:bold;] HIGH]]
+    td[HTML output]
+  ]
+  tr[
+    td[42]
+    td[span[@style[color:green;font-weight:bols;] LOW]]
+    td[
+      p[Support for less-used tags:]
+      ul[
+        li[cite]
+        li[sup]
+        li[...]
+      ]
+    ]
+  ]
+]
+			=]
+			p[&[htmlcode]]
+			highlight[=html|
+<table class="features">
+  <tr>
+    <th>ID</th>
+    <th>Priority</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>27</td>
+    <td><span style="color:red;font-weight:bold;">HIGH</span></td>
+    <td>HTML output</td>
+  </tr>
+  <tr>
+    <td>42</td>
+    <td><span style="color:green;font-weight:bold;">LOW</span></td>
+    <td>
+      <p>Support for less-used tags:</p>
+      <ul>
+        <li>cite</li>
+        <li>sup</li>
+        <li>...</li>
+      </ul>
+    </td>
+  </tr>
+</table>
+      =]
+		]
+		p[Basically, if the $>[language.options.xml_fallback] is set to code[true], any macro unknown to Glyph with at most one parameter will be converted to an XML tag with the same name and any attribute will be converted to the corresponding XML attribute.]
+		important[While macro names and attributes are validated so that an error is returned if they contain illegal character, no check is performed against any particular XML schema.]
+		txt[Additionally, it is possible to force macro-to-XML conversion by prepending an equal sign to any macro, so for example code[=\.=snippet[test]=] will be converted into @<snippet>test</snippet>@.]
+	]
+	section[
+		@title[Blacklisted XML tags]
+		@id[xml_blacklist]
+		txt[
+By default, the following tags are blacklisted and will be ignored:
+%[="* "+Glyph['language.options.xml_blacklist'].join("\n* ")=]
+
+tip[You can change this list by modifying the $>[language.options.xml_blacklist].]
+		]
+ 
+	]
+]