glyph 0.2.0 → 0.3.0

data/book/text/text_editing/sections.glyph

@@ -0,0 +1,63 @@
+section[
+	@title[Sections and Headers]
+	@id[sec_head]
+
+	p[Glyph documents are normally organized as a hierarchical tree of nested chapters, appendixes, sections, etc. To define a section, use the %>[section], like so:]
+
+	highlight[=html|
+section[
+  @title[Section #1]
+Write the section contents here...
+  section[
+    @title[Section #2]
+This section is nested into the previous one.
+  ] --[End of Section #2]
+] --[End of Section #1]
+	=]
+
+	txt[This example defines two nested sections. If the code[@title] attribute is specified like in this case, it will be converted to a proper HTML header and it will appear in the table of contents (see the %>[toc]).
+
+Note an important difference from HTML: there is no need for an 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:]
+
+	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>
+	=]
+
+	txt[
+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[
+   		th[Frontmatter]
+    	td[txt[@imprint@ ^&dagger;^, @dedication@ ^&dagger;^, @inspiration@ ^&dagger;^, @foreword@ ^&Dagger;^, @introduction@ ^&Dagger;^, @acknowledgement@ ^&Dagger;^, @prologue@ ^&Dagger;^, @toc@ ^*^]]
+  	]
+  	tr[
+    	th[Bodymatter]
+    	td[txt[@volume@, @book@, @part@, @chapter@]]
+  	]
+  	tr[
+    	th[Backmatter]
+    	td[txt[@epilogue@ ^&Dagger;^, @afterword@ ^&Dagger;^, @postscript@ ^&dagger;^, @appendix@, @addendum@ ^&Dagger;^, @glossary@ ^**&Dagger;^, @colophon@ ^&dagger;^, @bibliography@ ^**&Dagger;^, @promotion@ ^&dagger;^, @references@ ^**&Dagger;^, @index@ ^**&Dagger;^, @lot@ ^**&Dagger;^, @lof@ ^**&Dagger;^]]
+  	]
+	]
+
+	p[strong[*]: The %>[toc] is used to generate the Table of Contents automatically, and it takes no parameters.]
+	p[strong[**]: This macro is likely to be extended in future versions to generate/aggregate content automatically.]
+	p[strong[&dagger;]: This section is not listed in the Table of Contents.]
+	p[strong[&Dagger;]: Any subsection of this section is not listed in the Table of Contents.]
+
+	note[
+		code[frontmatter], code[bodymatter] and code[backmatter] are also macro identifiers, but they are exposed as attributes for the %>[book] and the %>[article], so if you're using either of these two macros as your root macro for your document, there's no need to use them explicitly.
+	]
+] 

data/book/text/text_editing/stylesheets.glyph

@@ -0,0 +1,36 @@
+section[
+	@title[Adding Stylesheets]
+	@id[stylesheets]
+	p[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.]
+	p[You can embed CSS files using the %>[style], like this:]
+	p[code[= style[default.css] =]]
+	txt[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[
+		@title[Default Stylesheets]
+		@id[default_stylesheets]
+		p[Glyph provides the following default stylesheets, that can be referenced directly using the %>[style]:]
+		table[
+			tr[
+				th[File name]
+				th[Notes]
+			]
+			tr[
+				td[code[default.css]]
+				td[The stylesheet used for this book.]
+			]
+			tr[
+				td[code[pagination.css]]
+				td[A CSS3-compliant stylesheet used for pagination, suitable for PDF generation using &[prince].]
+			]
+			tr[
+				td[code[coderay.css]]
+				td[The default &[coderay] stylesheet, used for syntax highlighting.]
+			]
+			tr[
+				td[code[ultraviolet/*]]
+				td[This folder contains the following &[uv] stylesheets, used for syntax highlighting: code[%[(Glyph::HOME/"styles/ultraviolet").children.sort.map{\|c\| c.basename}.join(", ")]]]
+			]
+		]
+	]
+]
+

data/book/text/troubleshooting/errors_command.glyph

@@ -0,0 +1,39 @@
+section[
+	@title[Command Errors]
+	error_table[
+		ref_error[Source file '\.em[source_file]' does not exist|
+Returned if Glyph is running in =>[#lite_mode|lite mode] and the specified source file was not found.
+		]
+		ref_error[Source and destination file are the same|
+Returned if Glyph is running in =>[#lite_mode|lite mode] and you specified the same source and destination files.
+		]
+		ref_error[DirectoryWatcher is not available. Install it with: gem install directory_watcher|
+Returned if =>[#auto_regeneration|auto regeneration] is enabled but the code[directory_watcher] gem in not installed.
+		]
+		ref_error[Document cannot be finalized due to previous errors|
+Returned if one or more errors occurred in the document prevented finalization.
+		]
+		ref_error[Please specify a file name|
+No file name was specified for the #>[add].
+		]
+		ref_error[Output target not specified|
+Returned if no target was specified for the #>[compile] _and_ if the $>[document.output] is not set.
+		]
+		ref_error[Unknown output target '\.em[target_name]'|
+An unsupported output target was specified for the #>[compile]. Only the following output targets are supported:
+			ul[
+				li[html]
+				li[pdf]
+			]
+		]
+		ref_error[Too few/too many arguments|
+Returned if the #>[config] was used with no arguments or more than two arguments respectively.
+		]
+		ref_error[Unknown setting '\.em[setting_name]'|
+The name of an unknown setting was specified for the #>[config].
+		]
+		ref_error[Cannot reset '\.em[setting_name]' setting (system use only).|
+Returned by the #>[config] when attempting to override a setting in the code[system.*] namespace.
+		]
+	]
+] 

data/book/text/troubleshooting/errors_generic.glyph

@@ -0,0 +1,29 @@
+section[
+	@title[Generic Errors]
+	error_table[
+		ref_error[Invalid alias: macro '\.em[macro_name]' already exists|
+The alias name supplied to the @macro_alias@ method has already been used for another macro or alias.
+		]
+		ref_error[Undefined macro '\.em[macro_name]'|
+The document contains a macro that does not exist, i.e. it is not a standard or used-defined =>[#macro_ref|Glyph macro or alias].
+		]
+		ref_error[An error occurred when generating _file-name_.pdf|
+Returned if Prince could not generate the PDF file or if Prince is not installed. Normally, Prince provides additional details on the specific error(s).
+		]
+		ref_error[Glyph cannot generate PDF. Please specify a valid tools.pdf_generator setting|
+Returned if the $>[tools.pdf_generator] has not be set to a valid PDF renderer. Currently, the only supported value for this setting is code[prince].
+		]
+		ref_error[The current directory is not a valid Glyph project|
+Returned if a glyph command was executed outside a valid glyph project directory.
+		]
+		ref_error[Invalid snippet file|
+The code[snippet.yml] file contains invalid data. Most likely, it does not evaluate to a Ruby code[Hash].
+		]
+		ref_error[Directory '\.em[directory_name]' is not empty|
+	Returned when executing the #>[init] in a directory that is not empty.
+		]
+		ref_error[File '\.em[file_name]' already exists|
+Returned if the name of an existing file was specified as a parameter for the #>[add].
+		]
+	]
+] 

data/book/text/troubleshooting/errors_intro.glyph

@@ -0,0 +1,3 @@
+This chapter lists the most common error messages that can be returned when running a Glyph command. It does not aim to be an exhaustive list, especially if you =>[#extending|extended] Glyph by creating your own macros or you're embedding Ruby code using the %>[ruby].
+
+tip[As a general rule, more diagnostic information is provided if Glyph is run in =>[#debug_switch|debug mode].]

data/book/text/troubleshooting/errors_macro.glyph

@@ -0,0 +1,98 @@
+section[
+	@title[Macro Errors]
+	txt[
+The following errors are displayed in the form:
+
+em[message]
+  source: em[macro_source]
+   path: em[macro_path]
+
+em[macro_value]
+
+Where:
+* em[message] is the error message.
+* em[macro_source] is the file or snippet where the error occurred.
+* em[macro_path] is the full path to the macro that returned the error, within the document syntax tree, e.g. @document/body/bodymatter/chapter/section/header/&@ if the error occurrent in a snippet within the header of a section in the @bodymatter@ part of the document.
+* em[macro_value] is the value of the macro (shown only if Glyph is running in =>[#debug_switch|debug mode]).
+	]
+	error_table[
+		ref_error[Macro '\.em[name]' takes up to em[x] parameter(s) (\.em[y] given)|
+Returned if the macro was called with extra parameters.
+		]
+		ref_error[Macro '\.em[name]' takes at least em[x] parameter(s) (\.em[y] given)|
+Returned if the macro was called with fewer parameters than expected.
+		]
+		ref_error[Macro '\.em[name]' takes exactly em[x] parameter(s) (\.em[y] given)|
+Returned if the macro was called with a different number of parameters than.
+		]
+		ref_error[Macro not available when compiling a single file.|
+Returned by the %>[include] if used in =>[#lite_mode|lite mode].
+		]
+		ref_error[Filter macro '\.em[extension]' not available|
+Returned by a filter macro if $>[filters.by_file_extension] is set to @true@, but the extension was not recognized.
+		]
+		ref_error[Invalid regular expression: em[regexp]|
+Returned by the %>[match] if an invalid regular expression was supplied.
+		]
+		ref_error[Macro '\.em[name]' takes no parameters (\.em[x] given)|
+Returned if the macro was called with parameters but none are requested.
+		]
+		ref_error[No highlighter installed. Please run: gem install coderay|
+Returned by the %>[highlight] if no highlighters are installed.
+		]
+		ref_error[CodeRay highlighter not installed. Please run: gem install coderay|
+Returned by the %>[highlight] if $>[filters.highlighter] is set to @coderay@ but &[coderay] is not installed.
+		]
+		ref_error[UltraViolet highlighter not installed. Please run: gem install ultraviolet|
+Returned by the %>[highlight] if $>[filters.highlighter] is set to @ultraviolet@ but &[uv] is not installed.
+		]
+		ref_error[Mutual Inclusion in parameter/attribute(\.em[name]): '\.em[value]'|
+Returned if a catch-22 situation occurs with macro inclusion, for example if the value of a snippet includes a reference to the same snippet.
+		]
+		ref_error[Snippet '\.em[snippet_id]' does not exist|
+Returned by the %>[snippet] if an invalid snippet ID was supplied.
+		]
+		ref_error[File '\.em[file_name]' not found|
+Returned by the %>[include] if an invalid file was supplied.
+		]
+		ref_error[Filter macro '\.em[macro_name]' not found|
+Returned by the %>[include] if the $>[filters.by_file_extension] is set to @true@ but the file extension of the included file is not recognized as a filter macro.
+		]
+		ref_error[RedCloth gem not installed. Please run: gem install RedCloth|
+Returned by the %>[textile] if the RedCloth gem is not installed.
+		]
+		ref_error[No MarkDown converter installed. Please run: gem install bluecloth|
+Returned by the %>[markdown] if no valid Markdown converter gem is installed. Glyph checks for: BlueCloth, Maruku, Kramdown and RDiscount.
+		]
+		ref_error[Image/Figure not found|
+Retured by the %>[image] or the %>[figure] respectively, if the specified image file could not be found within the code[images/] folder.
+		]
+		ref_error[Bookmark '\.em[bookmark_name]' already exists|
+Returned by the %>[anchor] or by the %>[section] if the anchor ID supplied as attribute has already been used in the document.
+		]
+		ref_error[Bookmark '\.em[bookmark_name]' already exists|
+Returned by the %>[link] if the anchor ID supplied as parameter has not been used in the document.
+		]
+		ref_error[Stylesheet '\.em[file_name]' not found|
+Returned by the %>[style] if the code[.css] or code[.sass] file supplied as parameter was not found in the code[styles/] directory.
+		]
+		ref_error[Haml is not installed. Please run: gem install haml|
+Returned by the %>[style] if a code[.sass] file was passed as parameter but the Haml gem is not installed.
+		]
+		ref_error[Invalid XML element: '\.em[element_name]'|
+An invalid XML element name was supplied to the code[\|xml\|] system macro (see =>[#other_elements]).
+		]
+		ref_error[Invalid XML element: '\.em[element_name]'|
+An invalid XML attribute name was supplied to the code[\|xml\|] system macro (see =>[#other_elements]).
+		]
+		ref_error[Macro '\.em[macro_name]' cannot be used in safe mode|
+Returned if a forbidden macro was used in safe mode (see =>[#modes]).
+		]
+		ref_error[Cannot reset 'system.\.em[setting_name]' setting (system use only).|
+Returned by the =>[config:] when attempting to override a setting in the code[system.*] namespace.
+		]
+		ref_error[Macro '\.em[macro_name]' cannot be defined by itself|
+Returned by the =>[rewrite:] if it contains a macro with the same name.
+		]
+	]
+]

data/book/text/troubleshooting/errors_parser.glyph

@@ -0,0 +1,29 @@
+section[
+	@title[Parsing Errors]
+	error_table[
+		ref_error[Macro delimiter '\.em[delimiter]' not escaped|
+Returned in case of unescaped code[\[]or code[\]].
+		]
+		ref_error[em[macro_name]\[...\] - A macro cannot start with '@' or a digit.|
+Returned if an invalid macro name was specified.
+		]
+		ref_error[Macro '\.em[macro_name]' not closed|
+Returned if a macro lacks its end delimiter code[\.=\]].
+		]
+		ref_error[Escaping macro '\.em[macro_name]' not closed|
+Returned if an escaping macro lacks its end delimiter code[\.=\]].
+		]
+		ref_error[Attribute @\.em[attribute_name] not closed|
+Returned if a macro attribute lacks its end delimiter code[\]].
+		]
+		ref_error[Attributes cannot be nested|
+Returned if a macro attribute was found immediately within another attribute.
+		]
+		ref_error[Cannot nest escaping macro '\.em[macro_name_1]' within escaping macro '\.em[macro_name_2]'|
+Returned if an escaping macro contains another escaping macro.
+		]
+		ref_error[Parameter delimiter '\|' not allowed here|
+Returned if a parameter delimiter is outside a macro or inside an attribute.
+		]
+	]
+]

data/config.yml

@@ -4,72 +4,91 @@
   :title: ""
   :subtitle: ""
   :filename: ""
+  :revision: ""
   :draft: false
   :output: 'html'
-  :output_targets: [:html, :pdf]
-:structure:
-  :hidden:
-    - :imprint
-    - :dedication
-    - :inspiration
-    - :postscript
-    - :colophon
-    - :promotion
-  :special:
-    - :foreword
-    - :acknowledgement
-    - :prologue
-    - :epilogue
-    - :addendum
-    - :glossary
-    - :bibliography
-    - :references
-    - :index
-    - :lot
-    - :lof
-  :frontmatter:
-    - :preface
-    - :imprint
-    - :dedication
-    - :inspiration
-    - :foreword
-    - :introduction
-    - :acknowledgement
-    - :prologue
-  :bodymatter:
-    - :volume
-    - :book
-    - :part
-    - :chapter
-  :backmatter:
-    - :epilogue
-    - :afterword
-    - :postscript
-    - :appendix
-    - :addendum
-    - :glossary
-    - :colophon
-    - :bibliography
-    - :promotion
-    - :references
-    - :index
-    - :lot
-    - :lof
+:language:
+  :set: 'glyph' # xml, core, filters
+  :options:
+    :xml_fallback: true
+    :xml_blacklist:
+      - applet
+      - base
+      - basefont
+      - embed
+      - frame
+      - frameset
+      - iframe
+      - isindex
+      - meta
+      - noframes
+      - noscript
+      - object
+      - param
+      - title
 :tools:
   :pdf_generator: 'prince'
-:highlighters:
-  :target: 'html'
-  :current: 'coderay'
-  :coderay:
-    # See options at http://coderay.rubychan.de/doc/classes/CodeRay/Encoders/HTML.html
-    :css: :class 
-  :ultraviolet:
-    :line_numbers: false
-    :theme: 'blackboard'
 :filters:
   :by_file_extension: true
+  :highlighter: 'coderay'
   :target: 'html'
   :markdown:
     :converter: 'bluecloth'
   :redcloth:
     :restrictions: []
+  :coderay:
+    # See options at http://coderay.rubychan.de/doc/classes/CodeRay/Encoders/HTML.html
+    :css: :class 
+  :ultraviolet:
+    :line_numbers: true
+    :theme: 'lazy'
+:system:
+  :quiet: false
+  :output_targets: [:html, :pdf]
+  :structure:
+    :hidden:
+      - :imprint
+      - :dedication
+      - :inspiration
+      - :postscript
+      - :colophon
+      - :promotion
+    :special:
+      - :foreword
+      - :acknowledgement
+      - :prologue
+      - :epilogue
+      - :addendum
+      - :glossary
+      - :bibliography
+      - :references
+      - :index
+      - :lot
+      - :lof
+    :frontmatter:
+      - :preface
+      - :imprint
+      - :dedication
+      - :inspiration
+      - :foreword
+      - :introduction
+      - :acknowledgement
+      - :prologue
+    :bodymatter:
+      - :volume
+      - :part
+      - :chapter
+    :backmatter:
+      - :epilogue
+      - :afterword
+      - :postscript
+      - :appendix
+      - :addendum
+      - :glossary
+      - :colophon
+      - :bibliography
+      - :promotion
+      - :references
+      - :index
+      - :lot
+      - :lof