glyph 0.1.0 → 0.2.0

data/book/script/readme

@@ -0,0 +1 @@
+glyph compile text/introduction.glyph ../README.textile

data/book/snippets.yml

@@ -5,9 +5,8 @@
 :gcode: "The following Glyph code:"
 :htmlcode: "Is translated into the following HTML code:"
 :markups: Textile or Markdown
-:prince: "=>[http://www.princexml.com/|Prince]"
 :filter_by_ext: "the $>[filters.by_file_extension] is @true@"
 :called_on_files: "If &[filter_by_ext], this macro is called automatically on =>[#m_include|included] files"
-:test: |-
-  This is a 
-  Test snippet
+:only_after_declaration: "can only be used _after_ its declaration"
+:coderay: "=>[http://coderay.rubychan.de/|Coderay]"
+:uv: "=>[http://ultraviolet.rubyforge.org/|Ultraviolet]"

data/book/text/acknowledgement.glyph

@@ -0,0 +1,8 @@
+Glyph was designed and developed by =>[http://www.h3rald.com|Fabio Cevasco] (h3rald).
+
+Special thanks to the following individuals who contributed to Glyph by reporting and fixing issues and/or proposing and implementing new features:
+* =>[http://www.jabbslad.com|Jamie Atkinson] (Jabbslad)
+* =>[http://koraktor.github.com|Sebastian Staudt] (koraktor)
+
+
+    

data/book/text/authoring.glyph

@@ -0,0 +1,548 @@
+section[header[Text Editing]
+
+One of the main purposes of Glyph is streamlining text editing. Glyph accomplishes this through its own macro language that can be used in conjunction with &[markups].
+
+section[header[Introducing &[macros]]
+
+By now you probably figured out what a macro looks like: it's 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: @\[@, @\]@, @\\@, @\|@ 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 often have one or more aliases. For example, @=>@ is an alias for the %>[link], so the following macro calls are equivalent:
+
+codeph[=\.=>[#test\|Test Section]=]
+codeph[=\.link[#test\|Test Section]=]
+
+]
+
+section[header[Escaping and Quoting|esc_quot]
+
+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 %>[code], like this:
+
+code[=
+code\[=
+section[header[A section]
+
+This is a section.
+
+  section[header[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.]
+
+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[@\\\[@]
+    td[@\[@]
+    td[&[sq_esc]]
+  ]
+  tr[
+    td[@\\\]@]
+    td[@\]@]
+    td[&[sq_esc]]
+  ]
+  tr[
+    td[@\\\\@]
+    td[@\\@]
+    td[Backslashes do not have to be escaped by default, but an escaped backslash will evaluate to itself.]
+  ]
+  tr[
+    td[@\\\=@]
+    td[@=@]
+    td[Equal signs do not have to be escaped by default, but an escaped equal sign will evaluate to iself.]
+  ]
+  tr[
+    td[@\\\|@]
+    td[@\|@]
+    td[Pipes must be escaped (even within quoting macros) unless they are used to separate macro parameters.]
+  ]
+  tr[
+    td[@\\\..@]
+    td[ ]
+    td[An escaped dot evaluates to nothing. Useful to separate macro identifiers from other characters:
+codeph[= _\\..=>[#link\|This link is emphasized using Textile]_ =]
+    ]
+  ]
+]
+
+] --[End section]
+
+section[header[Sections and Headers|sec_head]
+
+Glyph documents are normally organized as a hierarchical tree of nested chapters, appendixes, sections, etc. To define a section, use the %>[section], like so:
+
+code[=
+section[
+  header[Section #1]
+
+Write the section contents here...
+
+  section[
+    header[Section #2]
+
+This section is nested into the previous one.
+
+  ] --[End of Section #2]
+] --[End of Section #1]
+=]
+
+This example defines two nested sections, each with its own header. The header is _mandatory_: it will be displayed at the start of the section and in the Table of Contents. 
+
+Note an important difference from HTML: there is no explicit level for the headers, as it will be determined at runtime when the document is compiled, based on how sections are nested. The previous code snippet (taken as it is), for example, will be transformed into the following HTML code:
+
+<notextile>
+highlight[=html|
+<div class="section">
+  <h2>Section #1</h2>
+  <p>Write the section contents here...</p>
+  <div class="section">
+    <h3>Section #2</h3>
+    <p>This section is nested in the previous one</p>
+  </div>
+</div>
+=]
+</notextile>
+
+By default, in Glyph the first header level is _2_, so the two headers are rendered as @h2@ and @h3@, respectively (@--\[...\]@ macros are _comments_, therefore they are not included in the final output).
+
+There are _a lot_ of macros that can be used in the same way as @section@, one for each element commonly used in =>[http://en.wikipedia.org/wiki/Book_design|Book Design]. Each one of them is a simple wrapper for a @<div>@ tag with a @class@ attribute set to its name.
+
+The following table lists the identifiers of all section-like macros, divided according to the part of the book they should be placed in:
+
+table[
+  tr[
+    td[*Frontmatter*]
+    td[@imprint@ ^†^, @dedication@ ^†^, @inspiration@ ^†^, @foreword@ ^‡^, @introduction@ ^‡^, @acknowledgement@ ^‡^, @prologue@ ^‡^, @toc@ ^*^]
+  ]
+  tr[
+    td[*Bodymatter*]
+    td[@volume@, @book@, @part@, @chapter@]
+  ]
+  tr[
+    td[*Backmatter*]
+    td[@epilogue@ ^‡^, @afterword@ ^‡^, @postscript@ ^†^, @appendix@, @addendum@ ^‡^, @glossary@ ^**‡^, @colophon@ ^†^, @bibliography@ ^**‡^, @promotion@ ^†^, @references@ ^**‡^, @index@ ^**‡^, @lot@ ^**‡^, @lof@ ^**‡^]
+  ]
+]
+
+<notextile>*</notextile>: The %>[toc] is used to generate the Table of Contents automatically, and it must be used with no contents (i.e.: @toc\[\]@).
+
+<notextile>**</notextile>: This macro is likely to be extended in future versions to generate/aggregate content automatically.
+ 
+†: This section is not listed in the Table of Contents.
+
+‡: Any subsection of this section is not listed in the Table of Contents.
+
+note[@frontmatter@, @bodymatter@ and @backmatter@ are also valid (and mandatory!) macro identifiers, typically already included in the default @document.glyph@ file of every project.]
+
+] --[End section]
+
+section[header[Including Files and Snippets|incl]
+
+If you're authoring a user manual, a long article or a book, writing everything inside a single file (@document.glyph@) may not be optimal. For this reason, Glyph provides an %>[include] (aliased by codeph[@]) that can be used to include the contents of any file within the @text/@ directory:
+
+codeph[=@[introduction.textile]=]
+
+The macro call above loads the contents of the @introduction.textile@ file, that can be stored _anywhere_ within the @text/@ directory.
+
+note[Unlike with =>[img_fig|image and figures] that must be included with their _relative_ path to the @images/@ folder, you must not specify a relative path when including text files. This is due to the fact that images are copied _as they are_ in the @output/<format>/images/@ directory and they have to be linked from the output file.
+
+A possible downside of this behavior is that file names must be unique within the entire @text/@ directory and any of its subdirectories]
+
+When including a text file, an input filter macro is applied to its contents by default, based on the file extension used:
+* @.textile@ &rarr; %>[textile]
+* @.markdown@ or @.md@ &rarr; %>[markdown]
+
+tip[You can override this behavior by setting the @filters.by_file_extensions@ configuration setting to @false@, like this:
+
+@glyph config filters.by_file_extensions false@]
+
+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? 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|
+Consider the following @snippets.yml@ file:
+
+<notextile>
+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
+=]
+</notextile>
+
+You can use codeph[=&[markups]=] anywhere in your document instead of having to type "Textile or Markdown" every time. Additionally, later on you can change the value of the @markups@ snippets only in the @snippets.yml@ file to change it everywhere else in the document.
+] --[End Example]
+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.
+]
+
+] --[End Section]
+
+
+section[header[Links and Bookmarks|links]
+
+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:
+* There is no built-in way to check if they are valid
+* There is no built-in way to determine the title of a link automatically
+
+If you care about link validation and you want to save some keystrokes, then you should use the following markup-agnostic macros:
+* @link@ (aliased to @=>@) -- to create internal and external links.
+* @anchor@ (aliased to @#@) -- to create named anchors (bookmarks) within your document.
+
+box[Example|
+
+&[gcode]
+
+code[=
+This is a link to link[#test].
+
+...
+
+This is link[#wrong].
+
+This is a #[test\\\|test anchor].=]
+
+&[htmlcode]
+
+<notextile>
+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>
+=]
+</notextile>
+
+Additionally, the following warning message is displayed when =>[#compile|compiling]:
+
+<notextile>
+code[=
+warning: Bookmark 'wrong' does not exist
+ -> source: @: aurhoting.textile
+ -> path: document/body/bodymatter/chapter/@/textile/section/section/box/link
+=]
+</notextile>
+
+]
+
+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 title is used as such.
+
+Besides using the %>[anchor] macro, you can also create an anchor for a header by passing an extra parameter to the %>[header], like this: codeph[=header[Header Title\|my_anchor]=].
+
+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 @#@). In the future, the macro could be extended to support external links as well. 
+]
+
+] --[End section]
+
+section[header[Evaluating Ruby code and Configuration Settings]
+
+&[glang] is not a full-blown programming language, as it does not provide control flow or variables, for example. 
+However, it is possible to evaluate simple ruby code snippets using the @ruby@ macro (aliased to @%@), like this:
+* codeph[=%[2 + 2]=] &rarr; 4
+* codeph[=%[Time.now]=] &rarr; %[Time.now]
+* codeph[=%[Glyph::VERSION]=] &rarr; %[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. codeph[=%[cfg('document.author')]=]), the %>[config] (aliased to @$@) makes things slightly simpler (e.g. codeph[=$[document.author]=]).
+
+]
+
+section[header[Conditional Macros|cond_macros]
+
+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 $>[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:
+
+code[=
+?[$[document.draft]\|
+This is a first draft of the Glyph Book]
+?[not[$[document.draft]]\|
+This is the official version of the Glyph Book]
+=]
+
+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:
+
+code[=
+?[and[
+    eq[$[document.output]\|pdf]
+    \|
+    eq[$[tools.pdf_generator]\|prince]
+    ]
+  \|
+  style[pagination.css]]
+=]
+
+In this case, the @pagination.css@ stylesheet is included only when you're generating a PDF document using Prince XML.
+
+  section[header[Using macros inside the condition macro]
+Conditionals are not implemented at parser level. This means that macros specified as the second parameter of a %>[condition] are _always_ parsed and _executed_, even _before_ that the condition is evaluated! Besides being inefficient, this can also lead to dangerous results if you're the %>[config:] or the %>[ruby], for example: because in that case a configuration setting or a piece of Ruby code is always executed...
+
+To avoid this potentially dangerous side effect, you can _\.=>[#m_encode|encode]_ the second parameter of the condition macro, like this:
+
+code[=
+?[$[document.draft]\|
+*\[\= $:[document.output|html] \=\]]
+=]
+
+If you do so, if the condition is satisfied, the condition macro decodes the second parameter and interprets its contents. In this way, if @document.draft@ is true, @document.output@ will be set to @html@, otherwise it will be left unchanged.
+  ]
+
+  section[header[Results of conditional expressions]
+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".
+  ]
+
+] --[End section]
+
+section[header[Images and Figures|img_fig]
+
+Same as for =>[#links|links], you can also include images and figures using &[markups]. If you want additional features, you can use the %>[img] and the %>[fig], as shown in the following example:
+
+box[Example|
+
+&[gcode]
+
+code[=
+img[glyph.svg\|20%\|20%]
+
+fig[example.png\|An example figure.]
+=]
+
+&[htmlcode]
+
+<notextile>
+highlight[=html|
+<img src="images/glyph.svg" width="20%" height="20%" alt="-" />
+
+<div class="figure">
+  <img src="images/example.png" alt="-"/>
+  <div class="caption">An example figure.</div>
+</div>
+=]
+</notextile>
+]
+
+note[
+In future releases, figures will be numbered automatically and included in a _List of Figures_ section.
+]
+
+] --[End of section]
+
+section[header[Source code|source_code]
+If you're a programmer, chances are that you're going to include some source code in your articles and books. Glyph providers different ways to format source code, as described in the following sections.
+
+section[header[Inline code]
+The %>[codeph] can be used to format inline code. That's exactly the same as using @<code>@ tags, just remember to use =>[#esc_quot|escaping delimiters] and to escape pipes. 
+]
+
+section[header[Code block]
+For code blocks, you have two choices: the %>[code], which simply wraps text into @<pre>@ and @<code>@ tags, or the %>[highlight] macro. The last one requires either &[coderay] or &[uv], but it highlights the most common programming language.
+
+Cosider the following piece of ruby code:
+
+code[=
+  def find_child(&block)
+    children.each do \|c\|
+      c.descend do \|node, level\|
+        return node if block.call(node)
+      end
+    end
+    nil
+  end
+=]
+
+It can be wrapped in a highlight macro, like so:
+
+code[=
+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
+\=]
+=]
+
+...to produce the following, using the $[highlighters.current] highlighter:
+ 
+<notextile>
+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
+=]
+</notextile>
+
+box[Some Remarks|
+* Highlighters require some configuration. For more information on relevant configuration settings, see the @highlighters.*@ configuration settings.
+* If you're using the %>[highlight] together with %>[textile], you must wrap the macro call within @<notextile>@ tags.
+* You must always escape pipes (@\|@) with the code or the highlight macro.
+]
+]
+
+] --[End of section]
+
+
+] --[End of Text Editing section]
+
+section[header[Compiling your project|compile]
+
+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 formats could be supported.
+
+section[header[Adding Stylesheets|stylesheets]
+
+Currently, Glyph does not provide any native way to format text and pages. The reason is that there's absolutely no need for that: CSS does the job just fine. In particular, CSS3 offers specific attributes and elements that can be used specifically for paginated documents. That's no replacement for LaTeX by any means, but it is enough if you're not looking for advanced typographical features.
+
+You can embed CSS files using the %>[style], like this:
+
+code[= style[default.css] =]
+
+In this case, the %>[style] looks for a @default.css@ file in the @/styles@ folder of your Glyph project _and_ among the default Glyph stylesheets, and embeds it within a @<style>@ tag. If you supply a file with a @.sass@ extension, it will interpret it as a Sass file and convert it to CSS automatically (if the _Haml_ gem is installed).
+
+section[header[Default Stylesheets|default_styles]
+Glyph provides the following default stylesheets, that can be referenced directly using the %>[style] macro:
+
+	table[
+		tr[
+			th[File name]
+			th[Notes]
+		]
+		tr[
+			td[@default.css@]
+			td[The default stylesheet used for this book.]
+		]
+		tr[
+			td[@pagination.css@]
+			td[A CSS3-compliant stylesheet used for pagination, suitable for PDF generation using Prince.]
+		]
+		tr[
+			td[@coderay.css@]
+			td[The default &[coderay] stylesheet, used for syntax highlighting.]
+		]
+		tr[
+			td[@ultraviolet/*@]
+			td[This folder contains the following &[uv] stylesheets, used for syntax highlighting: codeph[%[(Glyph::HOME/"styles/ultraviolet").children.sort.map{|c| c.basename}.join(", ")]]]
+		]
+	]
+
+]
+
+]
+
+section[header[HTML output]
+
+To compile a Glyph project to an HTML document, use the #>[compile] within your Glyph project folder. Glyph parses the @document.glyph@ file (and all included files and snippets); if no errors are found, Glyph creates an HTML document in the @/output/html@ folder. 
+
+The name of the HTML file can be set in the configuration (@document.filename@ setting).
+]
+
+section[header[PDF Output]
+
+To generate a PDF document, you must specify @pdf@ as format, like this:
+
+code[= glyph compile -f pdf =]
+
+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.strip] has been successfully tested with Prince v7.0, and the PDF version of this very book was generated with it.]
+
+]
+
+section[header[Auto Regeneration|auto_regeneration]
+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.]
+
+]
+
+]
+
+section[header[Compiling single Glyph files|lite_mode]
+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.
+
+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:
+
+codeph[glyph compile source.glyph destination.htm]
+
+This command will process a file called @source.glyph@ and produce an HTML file called @destination.htm@.
+
+section[header[Limitations|lite_limitations]
+&:[only_defined_through|can only be defined inside the source file, using the]
+This sort of "lite" mode comes with a few minor limitations: 
+* Snippets &[only_defined_through] %>[snippet:] macro.
+* Project configuration settings &[only_defined_through] %>[config:] macro.
+* Custom macros &[only_defined_through] %>[macro:] macro.
+* Images must be linked with their absolute path, or a path relative to the current directory, and will not be copied anywhere when the output file is generated.
+* Stylesheets must be referenced with their absolute path, a path relative to the current directory, or the name of an existing Glyph system stylesheet ![link to system stylesheet list].
+* The %>[include] cannot be used (if you need to include other text files, you should probably use a Glyph project...)
+]
+]
+
+section[header[Using Glyph programmatically]
+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[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.
+]
+
+]