glyph 0.3.0 → 0.4.0

data/book/text/stats/stats.glyph

@@ -0,0 +1,79 @@
+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|
+{{example}}
+		=]
+		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]
+=====================================
+stats \[options\] 
+    Display statistics
+
+Options:
+    -b, --bookmarks - Display stats about bookmarks
+    --bookmark=arg  - Display stats about a single bookmark
+    -f, --files     - Display stats about project files
+    -l, --links     - Display stats about links
+    --link=arg      - Display stats about links matching a regular expression
+    -m, --macros    - Display stats about macros
+    --macro=arg     - Display stats about a single macro
+    -s, --snippets  - Display stats about snippets
+    --snippet=arg   - Display stats about a single snippet
+]
+txt[
+If no options are specified, the command returns a summary containing different element totals, i.e.:
+* The files used in the project
+* Macro definitions and instances
+* Snippets
+* Bookmarks
+* Links and references
+
+Example:
+]
+highlight[=html|
+=====================================
+Glyph - Statistics
+=====================================
+
+===== Files
+-- Total Files: 50
+-- /text    -- 46
+-- /images  -- 3
+-- /styles  -- 0
+-- /layouts -- 0
+-- /lib     -- 1
+
+===== Macros
+-- Total Macro Instances: 2950
+-- Total Macro Definitions: 22
+-- Total Macro Aliases: 57
+-- Total Used Macro Definitions: 60
+
+===== Snippets
+-- Total Snippets: 21
+-- Total Used Snippets: 21
+-- Total Unused Snippets: 0
+
+===== Bookmarks
+-- Total Bookmarks: 221
+-- Total Referenced Bookmarks: 87
+-- Total Unreferenced Bookmarks: 135
+
+===== Links
+-- Total Internal Links: 87
+-- Total External Links: 97
+=]

data/book/text/text_editing/attribute_intro.glyph

@@ -0,0 +1,22 @@
+	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.]

data/book/text/text_editing/code.glyph

@@ -1,6 +1,3 @@
-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.
 
@@ -47,5 +44,3 @@ end
 * You must always escape pipes (@\|@) with the code or the highlight macro.
 		]
 	]
-] 
-

data/book/text/text_editing/conditionals.glyph

@@ -1,6 +1,3 @@
-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.
 
@@ -46,4 +43,3 @@ The %>[condition] in Glyph works in a similar way as conditionals in programming
 * 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

@@ -0,0 +1,64 @@
+	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/evaluation.glyph

@@ -1,5 +1,3 @@
-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
@@ -10,4 +8,3 @@ The scope for the code evaluation is the Kernel module, (with all inclusions req
 
 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

@@ -1,7 +1,4 @@
-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

@@ -1,6 +1,3 @@
-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|
@@ -25,5 +22,3 @@ figure[example.png\|An example figure.
 		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

@@ -1,6 +1,3 @@
-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:
 
@@ -41,4 +38,3 @@ tip[Besides storing snippets in the @snippets.yml@ file, you can also define the
 	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

@@ -1,6 +1,3 @@
-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
@@ -47,7 +44,5 @@ 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. 
-	]
-]
+	p[By default, validation is only enabled for internal links (i.e. the check occurs if the first parameter of the %>[link] starts with a code[#]). You can enable it for external links as well by setting the $>[options.url_validation] to code[true]. If URL validation is enabled, an error is returned if a link returns an HTTP status greater than 302.]
+	important[Enabling URL validation may significantly slow down compilation if a lot of external links are present.]

data/book/text/text_editing/macro_intro.glyph

@@ -1,6 +1,4 @@
-section[
-	@title[Introducing &[macros]]
-	@id[macro_intro]
+
 	txt[
 The most important concept to grasp about Glyph is the concept of _macro_.
 
@@ -14,98 +12,3 @@ A macro can often have one or more aliases. For example, @=>@ is an alias for th
 * 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

@@ -1,12 +1,3 @@
-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:]
@@ -32,81 +23,3 @@ This is another paragraph with some -deleted- text.
 			=]
 		]
 		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].]
-		]
- 
-	]
-]