glyph 0.2.0 → 0.3.0

data/book/text/license.glyph

@@ -1,6 +1,6 @@
 Copyright (c) 2010 **Fabio Cevasco**, =>[http://www.h3rald.com]  
 
-code[
+codeblock[
 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

data/book/text/macros/macros_block.glyph

@@ -0,0 +1,99 @@
+section[
+	@title[Block Macros]
+
+	ref_macro[
+		@n[box]
+		@desc[Creates a titled box (@<div>@ tag).]
+		@block_example[=
+box[Why boxes?\|
+  Boxes can be used to make a section of text stand out from the rest of the document.
+]
+		=]
+		@params[
+			-p[0|The box title.]
+			-p[1|The box text.]
+		]
+	]
+
+	ref_macro[
+		@n[codeblock]
+		@desc[Used to render a block of code within @<pre>@ and @<code>@ tags.]
+		@block_example[=
+code[
+  def hello
+    puts "Hello World"
+  end
+]
+=]
+		@remarks[For code highlighting, see the %>[highlight].]
+		@params[-p[0|The code to be formatted.]]
+	]
+
+	ref_macro[
+		@n[figure]
+		@desc[Includes an image in the document, with an optional caption (see =>[#img_fig]).]
+		@block_example[=
+figure[
+  graph.png\|Monthly Pageviews
+  @width[90%]
+]
+		=]
+		@params[
+			-p[0|&[img_file]]
+			-p[1|The image caption &[opt].]
+		]
+		@attrs[
+			-a[*|&[img_attrs]]
+		]
+	]
+
+	ref_macro[
+		@n[image]
+		@desc[Includes an image in the document]
+		@block_example[=
+img[
+  holidays/landscape.jpg
+  @class[photo]
+	@style[border: 1px solid black;]
+]
+		=]
+		@params[
+			-p[0|&[img_file]]
+		]
+		@attrs[
+			-a[*|&[img_attrs]]
+		]
+	]
+
+	ref_macro[
+		@n[note]
+		@desc[Creates a note @div@ containing the value.]
+		@aliases[important, caution, tip]
+		@example[=note[This is a note.]=]
+		@params[-p[0|The text of the note.]]
+	]
+
+	ref_macro[
+		@n[pubdate]
+		@desc[Evaluates to a date string (in the format: em[current_month] em[current_year]; i.e. _%B_ _%Y_), within a @<div>@ tag.]
+		@example[=pubdate[]=]
+	]
+
+	ref_macro[
+		@n[revision]
+		@desc[Renders the revision of the document (based on the $>[document.revision]) within a @<div>@ tag.]
+		@example[=revision[]=]
+	]
+
+	ref_macro[
+		@n[subtitle]
+		@desc[Renders the subtitle of the document (based on the $>[document.subtitle]) within a @<h2>@ tag.]
+		@example[=subtitle[]=]
+	]
+
+	ref_macro[
+		@n[title]
+		@desc[Renders the title of the document (based on the $>[document.title]) within a @<h1>@ tag.]
+		@example[=title[]=]
+	]
+]

data/book/text/macros/macros_core.glyph

@@ -0,0 +1,208 @@
+section[
+	@title[Core Macros]
+
+	ref_macro[
+		@n[alias]
+		@desc[Creates a macro alias.]
+		@params[
+			-p[0|The name of the alias.]
+			-p[1|The name of an existing macro.]
+		]
+		@example[=alias[s\|section]=]
+	]
+
+	ref_macro[
+		@n[and]
+		@desc[Conditional code[and] operator, to be used with the %>[condition].]
+		@params[&[bin_params]]
+		@example[=?[and[true\|false]\|This is never displayed.]=]
+	]
+
+	ref_macro[
+		@n[comment]
+		@desc[
+Evaluates to nothing. Used to add comments in a Glyph document that will not be displayed in output files. 
+		]
+		@aliases[--]
+		@params[-p[0|The contents to comment out]]
+		@example[=--[\.=>[#link\|This link will not be evaluated]]=]
+		@remarks[Macros are not expanded within comments.]
+	]
+
+	ref_macro[
+		@n[condition]
+		@desc[
+Tests a conditional expression. For more information, see =>[#cond_macros].
+		]
+		@aliases[?]
+		@params[
+			-p[0|The condition to test]
+			-p[1|The contents to expand if the condition is satisfied.]
+		]
+		@remarks[
+For examples see any of the following:
+* %>[and]
+* %>[or]
+* %>[not]
+* %>[match]
+* %>[eq]
+		]
+	]
+
+	ref_macro[
+		@n[config]
+		@desc[Returns the value of a configuration setting.]
+		@aliases[$]
+		@example[=$[document.author]=]
+		@params[
+			-p[0|The full name of a configuration setting.]	
+		]
+	]
+
+	ref_macro[
+		@n[config:]
+		@desc[Sets the value of a configuration setting.]
+		@aliases[$:]
+		@example[=$:[document.draft\|true]=]
+		@remarks[&[unsafe]]
+		@params[
+			-p[0|The full name of a configuration setting.]	
+			-p[0|The new value of the configuration setting]	
+		]
+	]
+	
+	ref_macro[
+		@n[eq]
+		@desc[Conditional equality operator, to be used with the %>[condition].]
+		@example[=?[eq[$[document.draft]\|true]\|This is displayed only in draft documents.]=]
+		@params[&[bin_params]]
+	]
+
+	ref_macro[
+		@n[escape]
+		@desc[Evaluates to its value. Commonly used with the escaping delimiters code[\[\=] and code[\=\]].]
+		@aliases[.]
+		@example[=.\[=Macros are escaped here =>[#test].=\]=]
+		@params[-p[0|The contents to escape.]]
+	]
+
+	ref_macro[
+		@n[include]
+		@desc[
+Evaluates to the contents of a text file stored in the @text/@ directory referenced by its relative path. If &[filter_by_ext], filters the contents of the file using the =>[#f_macros|filter macro] corresponding to the file extension.
+		]
+		@aliases[@]
+		@example[=include[frontmatter/introduction]=]
+		@params[-p[0|The file to include.]]
+		@remarks[
+			ul[
+				li[&[unsafe]]
+				li[@.glyph@ is assumed if no file extension is specified.]
+				li[
+This macro can also be used to include @.rb@ ruby files within the @lib@ directory. File contents are evaluated in the context of the =>[&[yardoc]/Glyph|Glyph] module.
+				]
+			]
+		]
+	]
+
+	ref_macro[
+		@n[match]
+		@desc[
+Checks a string against a regular expression.
+		]
+		@params[
+			-p[0|The string to check.]
+			-p[1|The regular expression to match against the string.]
+			-p[2|The contents to expand if the string matches.]
+		]
+		@remarks[This macro must be used with the %>[condition].]
+		@example[=?[match[Hello!\|/^hell/i]\|This is always displayed]=]
+	]
+
+	ref_macro[
+		@n[macro:]
+		@desc[Defines a macro.]
+		@remarks[
+			ul[
+				li[&[unsafe]]
+				li[The new macro &[only_after_declaration].]
+			]
+		]
+		@aliases[%:]
+		@example[=%:[test\|"<em>test: #{value}</em>"]=]
+		@params[
+			-p[0|The name of the new macro.]
+			-p[1|The macro definition (Ruby code).]
+		]
+	]
+		
+	ref_macro[
+		@n[not]
+		@desc[Conditional @not@ operator, to be used with the %>[condition].]
+		@example[=?[not[false]\|This is always displayed.]=]
+		@params[-p[0|The expression to negate]]
+	]
+
+	ref_macro[
+		@n[or]
+		@desc[Conditional @or@ operator, to be used with the %>[condition].]
+		@example[=?[or[true\|false]\|This is always displayed.]=]
+		@params[&[bin_params]]
+	]
+
+	ref_macro[
+		@n[rewrite:]
+		@desc[Defines a new macro by rewriting (for more information, see =>[#rewriting])]
+		@aliases[rw:]
+		@params[
+			-p[0|The name of the new macro.]
+			-p[0|The macro definition (Glyph code).]
+		]
+		@block_example[=
+rw:[release\|
+  section[
+    @title[Release {{0}}]
+    {{1}}
+  ]
+]
+		=]
+		@remarks[
+			ul[
+				li[The new macro &[only_after_declaration].]
+				li[&[unsafe]]
+			]
+		]
+	]
+
+	ref_macro[
+		@n[ruby]
+		@desc[Evaluates its value as Ruby code within the context of the =>[&[yardoc]/Glyph|Glyph] module.]
+		@aliases[%]
+		@examples[=
+%[Time.now]
+%[Glyph::VERSION]
+		=]
+		@params[-p[0|The Ruby code to evaluate.]]
+		@remarks[&[unsafe]]
+	]
+
+	ref_macro[
+		@n[snippet]
+		@desc[Returns the value of a snippet.]
+		@aliases[&amp;]
+		@example[=&amp;[glang]=]
+		@params[-p[0|The ID of the snippet to retrieve.]]
+	]
+
+	ref_macro[
+		@n[snippet:]
+		@desc[Defines a snippet.]
+		@remarks[The new snippet &[only_after_declaration].]
+		@aliases[&amp;:]
+		@example[=&amp;:[test\|This is a test]=]
+		@params[
+			-p[0|The ID of the new snippet.]
+			-p[1|The contents of the new snippet.]
+		]
+	]
+]

data/book/text/macros/macros_filters.glyph

@@ -0,0 +1,40 @@
+section[
+	@title[Filter Macros]
+	@id[f_macros]
+
+	ref_macro[
+		@n[markdown]
+		@desc[
+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. 
+		]
+		@aliases[md]
+		@example[=markdown[This is *emphasized* text.]=]
+		@params[-p[0|The Markdown text to filter.]]
+	]
+
+	ref_macro[
+		@n[textile]
+		@desc[
+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@ or a @.txt@ extension. 
+		]
+		@aliases[txt]
+		@example[=textile[This is a *strong emphasis*.]=]
+		@params[-p[0|The Textile text to filter.]]
+	]
+
+	ref_macro[
+		@n[highlight]
+		@desc[Highlights a piece of source code (second parameter) according to the specified language (first parameter). fmi[code highligting|#source_code].]
+		@block_example[=
+highlight[ruby\|
+  def hello
+    puts "Hello World"
+  end
+]
+		=]
+	]
+]

data/book/text/macros/macros_inline.glyph

@@ -0,0 +1,50 @@
+section[
+	@title[Inline Macros]
+	
+	ref_macro[
+		@n[anchor]
+		@desc[Creates a named anchor (or bookmark).]
+		@aliases[bookmark, #]
+		@example[=#[test\|Test Bookmark]=]
+		@params[
+			-p[0|The identifier of the bookmark]
+			-p[1|The contents of the bookmark &[opt]]
+		]
+	]
+
+	ref_macro[
+		@n[draftcomment]
+		@desc[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.]=]
+		@params[-p[0|The text of the comment.]]
+	]
+
+	ref_macro[
+		@n[fmi]
+		@desc[Creates a _For More Information_ link (for an example usage, see the %>[link]).]
+		@example[=fmi[creating links\|#links]=]
+		@params[
+			-p[0|The object that needs additional explanation.]
+			-p[0|A valid bookmark within the document.]
+		]
+	]
+
+	ref_macro[
+		@n[link]
+		@desc[Creates an hyperlink (\.fmi[creating links|#links]).]
+		@aliases[\.=>]
+		@example[=\.=>[http://www.h3rald.com\|H3RALD.com]=]
+		@params[
+			-p[0|A valid bookmark within the document or an URL.]
+			-p[1|The text of the link &[opt].]
+		]
+	]
+
+	ref_macro[
+		@n[todo]
+		@aliases[!]
+		@desc[Saves the value as a TODO item, which can be printed using the #>[todo] and included in the document if the $>[document.draft] is set to @true@.]
+		@example[=todo[Remember to do this.]=]
+	]
+]

data/book/text/macros/macros_structure.glyph

@@ -0,0 +1,100 @@
+section[
+	@title[Structure Macros]
+
+	ref_macro[
+		@n[article]
+		@desc[
+Used to create a simple article. By default, it includes the following macros:
+* @document@
+** @head@
+*** @style\[default.css\]@
+** @body@
+*** @halftitlepage@
+**** @title@
+**** @pubdate@
+**** @subtitle@
+**** @author@
+		]
+		@params[-p[0|The article contents.]]
+		@attrs[
+			-a[pre-title|Contents to include before the %>[title].]
+			-a[post-title|Contents to include after the %>[title].]
+			-a[head|Contents to include instead of the default code[head] macro.]
+			-a[pubdate|Contents to include instead of the default code[pubdate] macro.]
+			-a[halftitlepage|Contents to include instead of the default code[halftitlepage] macro.]
+		]
+	]
+
+	ref_macro[
+		@n[book]
+		@desc[
+Used to create a book. By default, it includes the following macros:
+* @document@
+** @head@
+*** @style\[default.css\]@
+** @body@
+*** @titlepage@
+**** @title@
+**** @pubdate@
+**** @subtitle@
+**** @revision@
+**** @author@
+		]
+		@params[-p[0|The article contents.]]
+		@attrs[
+			-a[pre-title|Contents to include before the %>[title].]
+			-a[post-title|Contents to include after the %>[title].]
+			-a[head|Contents to include instead of the default code[head] macro.]
+			-a[pubdate|Contents to include instead of the default code[pubdate] macro.]
+			-a[titlepage|Contents to include instead of the default code[titlepage] macro.]
+			-a[frontmatter|Contents to include within a code[frontmatter] macro.]
+			-a[bodymatter|Contents to include within a code[bodymatter] macro.]
+			-a[backmatter|Contents to include within a code[backmatter] macro.]
+		]
+	]
+
+	ref_macro[
+		@n[document]
+		@desc[Creates an @<html>@ tag and a DOCTYPE declaration. Called internally by the %>[book] and the %>[article].]
+		@params[-p[0|The document contents.]]
+	]
+
+	ref_macro[
+		@n[head]
+		@desc[Creates a @<head>@ tag, pre-populated with @title@ and author/copyright @<meta>@ tags.]
+		@params[-p[0|The head contents.]]
+	]
+
+	ref_macro[
+		@n[section]
+		@desc[Creates a section (@<div>@ tag).]
+		@aliases[%[=Glyph['system.structure'].values.flatten.uniq.map{\|a\| a.to_s }.push("section").sort.join(', ')=]]
+		@block_example[=
+section[
+	@title[Test Section]
+	@id[test]
+...
+]
+		=]
+		@params[-p[0|The text of the section]]
+		@attrs[
+			-a[title|The title of the section &[opt]]
+			-a[id|The ID of the section &[opt]]
+			-a[notoc|If not blank, the header will not appear in the Table of Contents. &[opt]]
+		]
+	]
+
+	ref_macro[
+		@n[style]
+		@desc[Embeds the content of a CSS or Sass file within a @<style>@ tag (\.fmi[stylesheets|#stylesheets]).]
+		@example[=style[default.css]=]
+		@params[-p[0|The stylesheet file to embed.]]
+	]
+
+	ref_macro[
+		@n[toc]
+		@desc[Generates a _Table of Contents_ based on how sections are nested in the current document.]
+		@example[=toc[1]=]
+		@params[-p[0|The maximum header depth of the TOC &[opt].]]
+	]
+]