glyph 0.1.0 → 0.2.0

data/book/text/license.glyph

@@ -0,0 +1,21 @@
+Copyright (c) 2010 **Fabio Cevasco**, =>[http://www.h3rald.com]  
+
+code[
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+]

data/book/text/{ref_commands.textile → ref_commands.glyph}

@@ -8,26 +8,31 @@ Where:
 
 section[header[Global Options]
 
-section[header[@-d@, @--debug@]
+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[header[@add@]
+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.]
+-p[_file-name_|The name (or relative path) of the new file to be created.]
 ]
 ] --[End add]
 
-section[header[@compile@]
+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)_.]
+]
+
 options[
 -o[source|
 The source file to compile. 
@@ -38,10 +43,13 @@ The format of the output file.
 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@]
+section[header[@config@|c_config]
 Gets or sets a configuration setting in the project or global configuration file (\.fmi[configuration files|#cfg]).
 
 examples[
@@ -56,12 +64,26 @@ default[false]
 ]
 ]
 parameters[
--p[setting|The name of a valid =>[#cfg_ref|configuration setting].]
--p[value|The new value of the configuration setting.]
+-p[_setting_|The name of a valid =>[#cfg_ref|configuration setting].]
+-p[_value_|The new value of the configuration setting.]
 ]
 ] --[End config]
 
-section[header[@init@]
+section[header[@help@|c_help]
+Prints information about all Glyph commands or about one specific command.
+
+examples[
+glyph help
+glyph help compile
+]
+
+parameters[
+-p[_command_|A valid Glyph command.]
+]
+
+] --[End help]
+
+section[header[@init@|c_init]
 Creates a new Glyph project in the current directory (if empty).
 
 example[glyph init]

data/book/text/ref_config.glyph

@@ -0,0 +1,108 @@
+section[header[@document.*@]
+The following configuration settings are related to the current Glyph document. Therefore, you should update them right after creating a project.
+
+	config_table[
+		ref_config[document.author|
+The author of the document.
+		]
+		ref_config[document.draft|
+If set to @true@, the document is considered a draft, so =>[#m_draftcomment|draft comments] and =>[#m_todo|todo items] will be displayed.
+		]
+		ref_config[document.filename|
+The name of the output file.
+		]
+		ref_config[document.output|
+The format of the output file. It can be set to any value stored in the $>[document.output_targets].
+		]
+		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.source|
+The main source file to compile. It can be also be overridden by calling the #>[compile] with the @-s@ option.
+		]
+
+		ref_config[document.subtitle|
+The subtitle of the document, displayed using the %>[subtitle].
+		]
+		ref_config[document.title|
+The title of the document, displayed using the %>[title].
+		]
+	]
+] --[End document section]
+
+section[header[@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]).  
+		]
+		ref_config[filters.markdown.converter|
+The name of the markdown converter to use with the %>[markdown]. It can be set to one of the following values:
+* BlueCloth
+* RDiscount
+* Maruku
+* Kramdown
+
+If not set, Glyph tests for the presence of each gem in the same order, until one is found. 
+		]
+		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). 
+		]
+		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|
+Whether the &[uv] highlighter should display line numbers or not.
+		]
+		ref_config[highlighters.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.
+
+	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[structure.frontmatter|
+The section types used in the document frontmatter.
+		]
+		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.
+		]
+	]
+] --[End structure section]
+
+section[header[@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

@@ -0,0 +1,378 @@
+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]