glyph 0.2.0 → 0.3.0

data/book/text/ref_commands.glyph

@@ -1,96 +1,117 @@
+txt[
 Glyph's command-line interface has been built using the =>[http://github.com/davetron5000/gli|gli] (Git-like interface) gem. Therefore, Glyph commands are all written like this:
 
-@glyph@ _global-options_ command _options_ _parameters_
+strong[glyph] em[global_options] strong[command] em[options] em[parameters]
 
 Where:
-* _global-options_ and _options_ are in the form: @-n@ _value_ or @--name=@\._value_, e.g. @-f pdf@ or @--format=pdf@
+* em[global_options] and _options_ are in the form: @-n@ _value_ or @--name=@\._value_, e.g. @-f pdf@ or @--format=pdf@
 * _parameters_ are separated by whitespaces, and can be wrapped in quotes.
-
-section[header[Global Options]
-
-section[header[@-d@, @--debug@|debug_switch]
-If specified, the command is executed in debug mode and additional diagnostic information is printed on the screen.
 ]
+section[
+	@title[Global Options]
+	section[
+		@title[code[-d], code[--debug]]
+		@id[debug_switch]
+		p[If specified, the command is executed in debug mode and additional diagnostic information is printed on the screen.]
+	]
 ]
-
-section[header[@add@|c_add]
-Creates a new text file in the @text/@ folder.
-
-example[glyph add introduction.textile]
-
-parameters[
--p[_file-name_|The name (or relative path) of the new file to be created.]
-]
-] --[End add]
-
-section[header[@compile@|c_compile]
-Compiles a Glyph document into an output file. If no options are specified, the @document.glyph@ file is used as source to produce a standalone HTML file.
-
-example[glyph compile -f pdf]
-
-parameters[
--p[_source_|The source glyph file to compile _(Optional)_.]
--p[_destination_|The destination file _(Optional)_.]
+section[
+	@title[code[add]]
+	@id[c_add]
+	p[Creates a new text file in the code[text/] folder.]
+	example[glyph add introduction.textile]
+	parameters[
+	-p[em[file_name]|The name (or relative path) of the new file to be created.]
+	]
 ]
-
-options[
--o[source|
+section[
+	@title[code[compile]]
+	@id[c_compile]
+	p[Compiles a Glyph document into an output file. If no options are specified, the code[document.glyph] file is used as source to produce a standalone HTML file.]
+	example[glyph compile -f pdf]
+	parameters[
+	-p[em[source]|The source glyph file to compile em[(Optional)].]
+	-p[em[destination]|The destination file em[(Optional)].]
+	]
+	options[
+		-o[source|
 The source file to compile. 
-default[document.glyph]
-]
--o[format|
+			default[document.glyph]
+	]
+		-o[format|
 The format of the output file.
-default[html]
-values[html, pdf]
-]
--o[auto|
+			default[html]
+			values[html, pdf]
+		]
+		-o[auto|
 If specified, enable =>[#auto_regeneration|auto regeneration] (requires the =>[http://rubygems.org/gems/directory_watcher|directory_watcher] gem to be installed).
+		]
+	]
 ]
-]
-] --[End compile]
-
-section[header[@config@|c_config]
+section[
+	@title[code[config]]
+	@id[c_config]
 Gets or sets a configuration setting in the project or global configuration file (\.fmi[configuration files|#cfg]).
-
-examples[
+	examples[
 glyph config document.filename
 glyph config -g document.author "Fabio Cevasco"
-]
-
-options[
--o[global|
+	]
+	options[
+		-o[global|
 If specified, the global configuration file is processed instead of the project file.
-default[false]
-]
+		default[false]
+		]
+	]
+	parameters[
+		-p[em[setting]|The name of a valid =>[#cfg_ref|configuration setting].]
+		-p[em[value]|The new value of the configuration setting.]
+	]
 ]
-parameters[
--p[_setting_|The name of a valid =>[#cfg_ref|configuration setting].]
--p[_value_|The new value of the configuration setting.]
-]
-] --[End config]
-
-section[header[@help@|c_help]
+section[
+	@title[code[help]]
+	@id[c_help]
 Prints information about all Glyph commands or about one specific command.
-
-examples[
+	examples[
 glyph help
 glyph help compile
+	]
+	parameters[
+		-p[em[command]|A valid Glyph command.]
+	]
 ]
-
-parameters[
--p[_command_|A valid Glyph command.]
-]
-
-] --[End help]
-
-section[header[@init@|c_init]
+section[
+	@title[code[init]]
+	@id[c_init]
 Creates a new Glyph project in the current directory (if empty).
-
-example[glyph init]
-] --[End init]
-
-section[header[@todo@|c_todo]
+	example[glyph init]
+]
+section[
+	@title[code[outline]]
+	@id[c_outline]
+Display an outline of the current document.
+	options[
+		-o[limit|
+Only display headers until the specified level.
+		]
+		-o[ids|
+Display section IDs.
+		]
+		-o[files|
+Display file names.
+		]
+		-o[titles|
+Display section titles.
+		]
+	]
+	examples[
+glyph outline -it -l 1
+glyph outline -l 2
+glyph outline -f
+	]
+]
+section[
+	@title[code[todo]]
+	@id[c_todo]
 Prints all the todo items saved using the %>[todo].
-
-example[glyph todo]
-] --[End todo]
+	example[glyph todo]
+]

data/book/text/ref_config.glyph

@@ -1,4 +1,6 @@
-section[header[@document.*@]
+section[
+	@title[document.*]
+	@id[cfg_document]
 The following configuration settings are related to the current Glyph document. Therefore, you should update them right after creating a project.
 
 	config_table[
@@ -16,6 +18,9 @@ The format of the output file. It can be set to any value stored in the $>[docum
 		]
 		ref_config[document.output_targets|
 An @Array@ containing all the possible output formats. This setting should not be changed by the user. 
+		]
+		ref_config[document.revision|
+The document's revision.
 		]
 		ref_config[document.source|
 The main source file to compile. It can be also be overridden by calling the #>[compile] with the @-s@ option.
@@ -28,9 +33,11 @@ The subtitle of the document, displayed using the %>[subtitle].
 The title of the document, displayed using the %>[title].
 		]
 	]
-] --[End document section]
+]
 
-section[header[@filters.*@]
+section[
+	@title[filters.*]
+	@id[cfg_filters]
 	config_table[
 		ref_config[filters.by_file_extension|
 If set to @true@, a filter macro is applied to included files, based on their extensions (\.fmi[including files|#incl]).  
@@ -43,6 +50,12 @@ The name of the markdown converter to use with the %>[markdown]. It can be set t
 * Kramdown
 
 If not set, Glyph tests for the presence of each gem in the same order, until one is found. 
+		]
+		ref_config[filters.coderay.*|
+Some &[coderay]-specific =>[http://coderay.rubychan.de/doc/classes/CodeRay/Encoders/HTML.html|options].
+		]
+		ref_config[filters.highlighter|
+The current highlighter to use. It can be set to @coderay@ or @ultraviolet@
 		]
 		ref_config[filters.redcloth.restrictions|
 An @Array@ containing restrictions applied to RedCloth, used by the %>[textile] (see =>[http://redcloth.rubyforge.org/classes/RedCloth/TextileDoc.html|RedCloth Documentation] for more information). 
@@ -50,59 +63,38 @@ An @Array@ containing restrictions applied to RedCloth, used by the %>[textile]
 		ref_config[filters.target|
 The output target for filters. It can be set to @html@ (for RedCloth and MarkDown) or @latex@ (RedCloth-only). 
 		]
-	]
-] --[End filters section]
-
-
-section[header[@highlighters.*@|s_highlighters]
-
-	config_table[
-		ref_config[highlighters.coderay.*|
-Some &[coderay]-specific =>[http://coderay.rubychan.de/doc/classes/CodeRay/Encoders/HTML.html|options].
-		]
-		ref_config[highlighters.current|
-The current highlighter to use. It can be set to @coderay@ or @ultraviolet@
-		]
-		ref_config[highlighters.target|
-The target output of the =>[#s_highlighters_current|current highlighter]. It can be set to anything the highlighter supports.
-		]
-		ref_config[highlighters.ultraviolet.line_numbers|
+		ref_config[filters.ultraviolet.line_numbers|
 Whether the &[uv] highlighter should display line numbers or not.
 		]
-		ref_config[highlighters.ultraviolet.theme|
+		ref_config[filters.ultraviolet.theme|
 The theme used by the &[uv] highlighter.
 		]
 	]
+] 
 
-] --[End highlighters section]
-
-section[header[@structure.*@]
-The following configuration settings are used internally by Glyph and should not be changed by the user.
-
+section[
+	@title[language.*]
 	config_table[
-		ref_config[structure.backmatter|
-The section types used in the document backmatter.
-		]
-		ref_config[structure.bodymatter|
-The section types used in the document bodymatter.
+		ref_config[language.set|
+Determines which macro set will be loaded. It can be set to:
+* glyph – Loads core, filter, xml macros plus all macros necessary for the $>[document.output].
+* xml – Loads core and xml macros.
+* core – Loads core macros only.
 		]
-		ref_config[structure.frontmatter|
-The section types used in the document frontmatter.
+		ref_config[language.options.xml_blacklist|
+The XML tags listed here cannot be generated using Glyph code.
 		]
-		ref_config[structure.hidden|
-The section types that will not be shown in the Table of Contents.
-		]
-		ref_config[structure.special|
-The section types that will be considered _special_ and whose children will not be included in the Table of Contents.
+		ref_config[language.options.xml_fallback|
+If set to true, any unknown macro name will considered an XML element (see =>[#other_elements]).
 		]
 	]
-] --[End structure section]
+]
 
-section[header[@tools.*@]
+section[
+	@title[tools.*]
 	config_table[
 		ref_config[tools.pdf_generator|
 The external program used to generate PDF files. It can only be set to @prince@.
 		]
 	]
-] --[End tools section]
-
+]

data/book/text/ref_macros.glyph

@@ -1,378 +1,6 @@
-section[header[Common Macros]
+
 
-ref_macro[and|
-Conditional @and@ operator, to be used with the %>[condition].
 
-example[=?[and[true\|false]\|This is never displayed.]=]
-]
 
-ref_macro[comment|
-Evaluates to nothing. Used to add comments in a Glyph document that will not be displayed in output files.
 
-aliases[--]
-example[=--[This is a comment. It will not be displayed in the output]=]
-]
 
-ref_macro[condition|
-Tests a conditional expression (first parameter), and evaluates to the second parameter if the condition is satisfied. If the second parameter is an %>[escape] macro, its contents are unescaped and interpreted only if the condition is satisfied. For more information, see =>[#cond_macros].
-
-aliases[?]
-
-*Examples*
-
-See any of the following:
-* %>[and]
-* %>[or]
-* %>[not]
-* %>[match]
-* %>[eq]
-
-]
-
-ref_macro[config|
-Evaluates to the configuration setting referenced by its value.
-
-aliases[$]
-example[=$[document.author]=]
-]
-
-ref_macro[config:|
-Sets the value of a configuration setting.
-
-aliases[$:]
-
-example[=$:[document.draft\|true]=]
-
-]
-ref_macro[decode|
-Decodes some text that was previously encoded (see %>[encode]). fmi[this topic|#encode_decode].
-
-aliases[**]
-
-example[=*[\=note‡\.‡¤\.91\.¤‡\.‡This will not be evaluated‡\.‡¤\.93\.¤‡\.‡\=]=]
-
-]
-
-ref_macro[encode|
-Encodes some Glyph code to prevent its evaluation, so that it can be decoded (and interpreted) later on (see the %>[decode]). fmi[this topic|#encode_decode].
-
-aliases[*]
-
-example[=*[\=note[This will not be evaluated]\=]=]
-
-]
-
-ref_macro[eq|
-Conditional equality operator, to be used with the %>[condition].
-
-example[=?[eq[$[document.draft]\|true]\|This is displayed only in draft documents.]=]
-]
-
-ref_macro[escape|
-Evaluates to its value. Commonly used with the escaping delimiters codeph[\[\=] and codeph[\=\]].
-
-aliases[.]
-example[=.\[=Macros are escaped here =>[#test].=\]=]
-]
-
-ref_macro[include|
-Evaluates to the contents of a text file stored in the @text/@ directory referenced by its value. If &[filter_by_ext], filters the contents of the file using the =>[#f_macros|filter macro] corresponding to the file extension.
-
-aliases[@]
-example[=@[introduction.textile]=]
-]
-
-ref_macro[match|
-Evaluates to @true@ if the first parameter matches the second, an empty string otherwise. The second parameter must be a valid Ruby-compatible regular expression. This macro must be used with the %>[condition].
-
-example[=?[match[Hello!\|/^hell/i]\|This is always displayed]=]
-]
-
-ref_macro[macro:|
-Defines a macro.
-
-note[The new macro &[only_after_declaration].]
-
-aliases[%:]
-
-example[=%:[test\|"<em>test: #@value</em>"]=]
-
-]
-
-ref_macro[not|
-Conditional @and@ operator, to be used with the %>[condition].
-
-example[=?[not[false]\|This is always displayed.]=]
-]
-
-ref_macro[or|
-Conditional @or@ operator, to be used with the %>[condition].
-
-example[=?[or[true\|false]\|This is always displayed.]=]
-]
-
-ref_macro[ruby|
-Evaluates its value as Ruby code (using @Kernel#instance_eval@).
-
-aliases[%]
-examples[=
-%[Time.now]
-%[Glyph::VERSION]
-=]
-]
-
-ref_macro[snippet|
-Evaluates to the snippet referenced by its value.
-
-aliases[&]
-example[=&[glang]=]
-]
-
-ref_macro[snippet:|
-Defines a snippet.
-
-note[The new snippet &[only_after_declaration].]
-
-aliases[&:]
-
-example[=&:[test\|This is a test]=]
-
-]
-
-ref_macro[todo|
-Saves the value as a TODO item, which can be printed using the #>[todo] or included in the document if the $>[document.draft] is set to @true@.
-
-example[=todo[Remember to do this.]=]
-]
-
-] --[End common macros]
-
-section[header[Filter Macros|f_macros]
-
-ref_macro[markdown|
-Uses a markdown converter (BlueCloth, RDiscount, Maruku or Kramdown) to transform the value into HTML if the $>[filters.target] is set to @html@.
-
-&[called_on_files] with a @.markdown@ or a @.md@ extension. 
-
-example[=markdown[This is *emphasized* text.]=]
-]
-
-ref_macro[textile|
-Uses the RedCloth gem to transform the value into HTML or LaTeX, depending on the value of the $>[filters.target]. 
-
-&[called_on_files] with a @.textile@ extension. 
-
-example[=textile[This is a *strong emphasis*.]=]
-]
-
-] --[End filter macros]
-
-section[header[Block Macros]
-
-ref_macro[box|
-Creates a titled box (@<div>@ tag).
-
-*Example:*
-
-code[=
-box[Why boxes?\|
-Boxes can be used to make a section of text stand out from the rest of the document.
-]
-=]
-]
-
-ref_macro[code|
-Used to render a block of code within @<pre>@ and @<code>@ tags. 
-* For inline code, see the %>[codeph].
-* For code highlighting, see the %>[highlight].
-
-*Example:*
-
-code[=
-code[
-  def hello
-    puts "Hello World"
-  end
-]
-=]
-
-]
-
-ref_macro[fig|
-Includes an image in the document, with an optional caption.
-
-examples[=
-fig[diagram.png]
-fig[graph.png\|Monthly pageviews]
-=]
-]
-
-ref_macro[highlight|
-Highlights a piece of source code (second parameter) according to the specified language (first parameter). fmi[code highligting|#source_code].
-
-*Example:*
-
-code[=
-highlight[ruby\|
-  def hello
-    puts "Hello World"
-  end
-]
-=]
-
-]
-
-ref_macro[img|
-Includes an image in the document, optionally scaled according to the specified width and height. The image must be stored within the @images/@ directory of the current project.
-
-examples[=
-img[icon.png]
-img[holidays/landscape.jpg\|70%]
-img[logo.svg\|50%\|50%]
-=]
-]
-
-ref_macro[note|
-Creates a note @div@ containing the value.
-
-aliases[important, caution, tip]
-example[=note[This is a note.]=]
-]
-
-ref_macro[pubdate|
-Evaluates to a date string (in the format: _current-month_ _current-year_; or _%B_ _%Y_), within a @<div>@ tag.
-
-example[=pubdate[]=]
-]
-
-ref_macro[subtitle|
-Renders the subtitle of the document (based on the $>[document.subtitle]) within a @<h2>@ tag.
-
-example[=subtitle[]=]
-]
-
-ref_macro[table|
-Evaluates to an HTML table. Used in conjunction with the =>[#m_tr|@tr@], =>[#m_td|@td@] and =>[#m_th|@th@] macros.
-
-*Example:*
-
-code[=
-table[
-  tr[
-    th[Name]
-    th[Value]
-  ]
-  tr[
-    td[A]
-    td[1]
-  ]
-  tr[
-    td[B]
-    td[2]
-  ]
-]
-=]
-
-]
-
-ref_macro[td|See =>[#m_table].]
-
-ref_macro[title|
-Renders the title of the document (based on the $>[document.title]) within a @<h1>@ tag.
-
-example[=title[]=]
-]
-
-ref_macro[th|See =>[#m_table].]
-ref_macro[tr|See =>[#m_table].]
-
-] --[End block macros]
-
-section[header[Inline Macros]
-
-ref_macro[anchor|
-Creates a named anchor (or bookmark).
-
-aliases[bookmark, #]
-example[=#[test\|Test Bookmark]=]
-]
-
-ref_macro[codeph|
-Wraps the value in a @<code>@ tag.
-
-example[=codeph[Kernel.instance_eval]=]
-
-]
-
-ref_macro[draftcomment|
-If the $>[document.draft] is set to @true@, displays a draft comment within the document.
-
-aliases[dc]
-
-example[=dc[This is printed only in draft documents.]=]
-
-]
-
-ref_macro[fmi|
-Creates a _For More Information_ link (for an example usage, see the %>[link]).
-
-example[=fmi[creating links\|#links]=]
-]
-
-ref_macro[link|
-Creates an hyperlink (\.fmi[creating links|#links]).
-
-aliases[\.=>]
-examples[=
-=>[#introduction]
-=>[#troub\|Troubleshooting]
-=>[http://www.h3rald.com\|H3RALD.com]
-=]
-]
-
-] --[End inline macros]
-
-section[header[Structure Macros]
-
-ref_macro[body|
-Creates a @<body>@ tag.
-]
-
-ref_macro[div|
-Creates a @<div>@ tag.
-
-*Aliases:* codeph[%[=Glyph['structure'].values.flatten.uniq.map{\|a\| a.to_s }.push("section").sort.join(', ')=]]
-]
-
-ref_macro[document|
-The root macro used in every Glyph document. It creates an @<html>@ tag.
-]
-
-ref_macro[head|
-Creates a @<head>@ tag, pre-populated with @title@ and author/copyright @<meta>@ tags.
-]
-
-ref_macro[header|
-Creates an @h2@, @h3@, @h4@, etc. header (\.fmi[using headers|#sec_head]).
-
-examples[=
-header[Introduction]
-header[Getting Started\|gs]
-=]
-]
-
-ref_macro[section|See =>[#m_div].]
-
-ref_macro[style|
-Embeds the content of a CSS or Sass file within a @<style>@ tag (\.fmi[stylesheets|#stylesheets]).
-
-example[=style[default.css]=]
-]
-
-ref_macro[toc|
-Generates a _Table of Contents_ based on how sections and headers are nested in the current document.
-
-example[=toc[]=]
-]
-
-] --[End structure macros]