Finished writing Macro Reference appendix.

book/lib/macros/reference.rb

@@ -25,7 +25,14 @@
 	interpret "=>[#m_#@value|#@value] macro"
 end
 
+macro :"#>" do
+	interpret "=>[#c_#@value|#@value] command"
+end
 
+macro :"$>" do
+	val = @value.gsub /\./, "_"
+	interpret "=>[#s_#{val}|#@value] setting"
+end
 
 macro :"parameters" do
 	interpret %{
@@ -63,7 +70,7 @@
 end
 
 macro :example do
-	%{*Example:* @glyph #@value@}
+	%{*Example:* @#@value@}
 end
 
 macro :examples do
@@ -73,7 +80,19 @@
 	}
 end
 
+macro :aliases do
+	%{*Aliases:* @#@value@}
+end
+
+macro :ref_macro do
+	m_name, m_value = @params
+	interpret %{
+	section[header[@#{m_name}@|m_#{m_name}]
+	#{m_value}
+	]
+	}
+end
+
 macro_alias :options => :parameters
-macro_alias '-e' => :ref_error
 macro_alias '-p' => :ref_error
 macro_alias '-o' => :option

book/snippets.yml

@@ -6,6 +6,8 @@
 :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

book/text/authoring.textile

@@ -80,7 +80,7 @@ table[
 
 ] --[End section]
 
-section[header[Sections and Headers]
+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@ macro, like so:
 
@@ -312,7 +312,7 @@ 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 are likely to be supported.
 
-section[header[Adding Stylesheets]
+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, CSS 3 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.
 

book/text/ref_commands.textile

@@ -16,7 +16,7 @@ If specified, the command is executed in debug mode and additional diagnostic in
 section[header[@add@]
 Creates a new text file in the @text/@ folder.
 
-example[add introduction.textile]
+example[glyph add introduction.textile]
 
 parameters[
 -p[file-name|The name (or relative path) of the new file to be created.]
@@ -26,7 +26,7 @@ parameters[
 section[header[@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[compile -f pdf]
+example[glyph compile -f pdf]
 
 options[
 -o[source|
@@ -45,8 +45,8 @@ section[header[@config@]
 Gets or sets a configuration setting in the project or global configuration file (\.fmi[configuration files|#cfg]).
 
 examples[
-config document.filename
-config -g document.author "Fabio Cevasco"
+glyph config document.filename
+glyph config -g document.author "Fabio Cevasco"
 ]
 
 options[
@@ -64,11 +64,11 @@ parameters[
 section[header[@init@]
 Creates a new Glyph project in the current directory (if empty).
 
-example[init]
+example[glyph init]
 ] --[End init]
 
-section[header[@todo@]
+section[header[@todo@|c_todo]
 Prints all the todo items saved using the %>[todo].
 
-example[todo]
+example[glyph todo]
 ] --[End todo]

book/text/ref_macros.textile

@@ -0,0 +1,256 @@
+section[header[Common Macros]
+
+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[todo|
+Saves the value as a TODO item, which can be printed using the #>[todo].
+
+example[todo\[Remember to do this.\]]
+]
+
+ref_macro[snippet|
+Evaluates to the snippet referenced by its value.
+
+aliases[&]
+example[&\[glang\]]
+]
+
+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[ruby|
+Evaluates its value as Ruby code (using @Kernel#instance_eval@).
+
+aliases[%]
+examples[
+%\[Time.now\]
+%\[Glyph::VERSION\]
+]
+]
+
+ref_macro[config|
+Evaluates to the configuration setting referenced by its value.
+
+aliases[$]
+example[$\[document.author\]]
+]
+
+ref_macro[escape|
+Evaluates to its value. Commonly used with the escaping delimiters @\[=@ and @=\]@.
+
+aliases[.]
+example[.\[=Macros are escaped here =>\[#test\].=\]]
+]
+
+] --[End common macros]
+
+section[header[Filter Macros|f_macros]
+
+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*.\]]
+]
+
+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.\]]
+]
+
+] --[End filter macros]
+
+section[header[Block Macros]
+
+ref_macro[note|
+Creates a note @div@ containing the value.
+
+aliases[important, caution, tip]
+example[note\[This is a note.\]]
+]
+
+ref_macro[box|
+Creates a titled box @div@.
+
+*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].
+
+*Example:*
+
+code[
+code\[
+  def hello
+    puts "Hello World"
+  end
+\]
+]
+
+]
+
+ref_macro[title|
+Renders the title of the document (based on the $>[document.title]) within a @h1@ tag.
+
+example[title\[\]]
+]
+
+ref_macro[subtitle|
+Renders the subtitle of the document (based on the $>[document.subtitle]) within a @h2@ tag.
+
+example[subtitle\[\]]
+]
+
+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[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[fig|
+Includes an image in the document, with an optional caption.
+
+examples[
+fig\[diagram.png\]
+fig\[graph.png\|Monthly pageviews\]
+]
+]
+
+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[tr|See =>[#m_table].]
+ref_macro[th|See =>[#m_table].]
+ref_macro[td|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[link|
+Creates an hyperlink (\.fmi[creating links|#links]).
+
+aliases[=>]
+examples[
+=>\[#introduction\]
+=>\[#troub\|Troubleshooting\]
+=>\[http://www.h3rald.com\|H3RALD.com\]
+]
+]
+
+ref_macro[codeph|
+Wraps the value in a @code@ tag.
+
+example[codeph\[Kernel.instance_eval\]]
+
+]
+
+ref_macro[fmi|
+Creates a _For More Information_ link (for an example usage, see the %>[link]).
+
+example[fmi\[creating links\|#links\]]
+]
+
+] --[End inline macros]
+
+section[header[Structure Macros]
+
+ref_macro[div|
+Creates a @div@ tag.
+
+*Aliases:* todo[List div aliases]
+]
+
+ref_macro[header|
+Creates an @h2@, @h3@, @h4@, etc. header (\.fmi[using headers|#sec_head]).
+
+examples[
+header\[Introduction\]
+header\[Getting Started\|gs\]
+]
+]
+
+ref_macro[document|
+The root macro used in every Glyph document.
+]
+
+ref_macro[body|
+Creates a @body@ tag.
+]
+
+ref_macro[head|
+Creates a @head@ tag, pre-populated with @title@ and author/copyright meta tags.
+]
+
+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]

book/text/troubleshooting.textile

@@ -100,7 +100,7 @@ Returned by the %>[markdown] if no valid Markup 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 @images/@ folder.
+Retured by the %>[img] or the %>[fig] respectively, if the specified image file could not be found within the @images/@ folder.
 ]
 ref_error[Bookmark '_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.