Updated troubleshooting section

book/document.glyph

@@ -63,12 +63,14 @@ book[
 			include[extending/interpreting]
 			include[extending/further_reading]
 		]
---[
 		chapter[
 			@title[Troubleshooting]
-			textile[include[troubleshooting]]
+			textile[include[troubleshooting/errors_intro]]
+			textile[include[troubleshooting/errors_generic]]
+			textile[include[troubleshooting/errors_parser]]
+			textile[include[troubleshooting/errors_command]]
+			textile[include[troubleshooting/errors_macro]]
 		]
-]
 	]
 	@backmatter[
 		appendix[

book/text/text_editing/raw_html.glyph

@@ -4,6 +4,7 @@ txt[So far we examined how to create @<div>@ tags for sections, links, images...
 * 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]).]

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.
+		]
+	]
+] 

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].
+		]
+	]
+] 

book/text/troubleshooting/errors_intro.glyph

@@ -0,0 +1,4 @@
+![New error: Cannot reset '#@value' setting (system use only).]
+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] macro.
+
+tip[As a general rule, more diagnostic information is provided if Glyph is run in =>[#debug_switch|debug mode].]

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.byem[file]extension] is set to @true@, but the extension was not recognized.
+		]
+		ref_error[Invalid regular expression: em[regexp]|
+Returned by the %>[match] macro 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] macro if no highlighters are installed.
+		]
+		ref_error[CodeRay highlighter not installed. Please run: gem install coderay|
+Returned by the %>[highlight] macro if $>[highlighters.current] is set to @coderay@ but &[coderay] is not installed.
+		]
+		ref_error[UltraViolet highlighter not installed. Please run: gem install ultraviolet|
+Returned by the %>[highlight] macro if $>[highlighters.current] 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] macro 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 %>[header] if the anchor ID supplied as parameter 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.
+		]
+	]
+]