glyph 0.4.2 → 0.5.0

data/book/text/extending/output_format.glyph

@@ -17,7 +17,7 @@ The first step required to add a new output format to Glyph is extending Glyph's
     :extension: '.html'
     :filter_target: 'html'
     :base: '/glyph/book/'
-    :macro_dirs: ['html', 'html5']
+    :macro_rep: html5
     :layout_dirs: ['web5']
     :layouts: 
       :topic: bookpage
@@ -63,7 +63,7 @@ namespace :generate do
     (dir/'glyph/book/images/glyph/glyph.eps').unlink 
     (dir/'glyph/book/images/glyph/glyph.svg').unlink
     # Create project page
-    project = Glyph.filter %{layout:project[
+    project = Glyph.filter %{layout/project[
         @contents[#{file_load(Glyph::PROJECT/'text/introduction.glyph')}]
       ]}
     file_write dir/"glyph.textile", project

data/book/text/extending/placeholders.glyph

@@ -5,22 +5,34 @@ Here's the source code of the %>[link]:
 	]
 	highlight[=ruby|
 macro :link do
-  href, title = @params
-  if href.match /^#/ then
-    anc = href.gsub(/^#/, '').to_sym
-    bmk = bookmark? anc
-    if bmk then
-      title \|\|= bmk[:title]
-    else
-      plac = placeholder do \|document\|
-        macro_error "Bookmark '#{anc}' does not exist" unless document.bookmarks[anc] 
-        document.bookmarks[anc][:title]
-      end
-      title \|\|= plac
-    end
+	min_parameters 1
+	max_parameters 2
+	target = param 0 
+	title = param 1 
+	if target.match /^#/ then
+		@node[:document].links << target 
+		anchor = target.gsub /^#/, ''
+		bmk = bookmark? anchor
+		if !bmk then
+			placeholder do \|document\|
+				bmk = document.bookmark?(anchor)
+				macro_error "Bookmark '#{anchor}' does not exist" unless bmk
+				bmk_title = title
+				bmk_title = bmk.title if bmk_title.blank?
+				@data[:target] = bmk.link(@source_file)
+				@data[:title] = bmk_title
+				render
+			end
+		else
+			bmk_title = title
+			bmk_title = bmk.title if bmk_title.blank?
+			@data[:target] = bmk.link(@source_file)
+			@data[:title] = bmk_title
+			render
+		end
+	else
+    # Code omitted...
   end
-  title \|\|= href
-  %{<a href="#{href}">#{title}</a>}
 end
 	=]
 	txt[

data/book/text/extending/validators.glyph

@@ -1,4 +1,4 @@
-	p[If you need to make sure that a macro is used properly, consider using =>[&[yardoc]/Glyph/Macro/Validators|validators]. These methods can be used anywhere within the macro code to check whether certain conditions are met or not. Some default validators are provided to check the number of parameters of a macro, and they are actually used in some system macros.]
+	p[If you need to make sure that a macro is used properly, consider using =>[&[rubydoc]/Glyph/Macro/Validators|validators]. These methods can be used anywhere within the macro code to check whether certain conditions are met or not. Some default validators are provided to check the number of parameters of a macro, and they are actually used in some system macros.]
 	p[If you want to create your own validators, you can call the generic code[validate] method which takes the message to display in case of error, a Hash of options and a block containing the validation to perform.]
 	box[Validating macro placement|
 		txt[

data/book/text/getting_started/configuration.glyph

@@ -2,7 +2,7 @@
 	textile[
 Glyph stores configuration settings in the following YAML files:
 # Your _Project Configuration_ is stored in the @config.yml@ file, included in each Glyph Project.
-# Your _Global Configuration_ is stored in a @.glyphrc@ file in your code[$HOME] (or ==\.code[%HOMEPATH%]== on Windows) directory (not created by default).
+# Your _Global Configuration_ is stored in a @.glyphrc@ file in your code[$HOME] (or ==\/code[%HOMEPATH%]== on Windows) directory (not created by default).
 # The _System Configuration_ is stored in the source directory of Glyph itself.
 
 When compiling, Glyph loads all these configuration files and merges them according to the following rules:

data/book/text/getting_started/create_project.glyph

@@ -16,10 +16,10 @@ Glyph requires the following gems:
 * rake
 
 Additionally, some Glyph macros may require additional gems, such as:
-* RedCloth (\.%>[textile])
-* BlueCloth _or_ RDiscount _or_ Maruku _or_ Kramdown (\.%>[markdown])
-* Haml (if you want to load .sass files with the %>[style])
-* CodeRay _or_ UltraViolet (\.%>[highlight])
+* RedCloth (\/%>[textile])
+* BlueCloth _or_ RDiscount _or_ Maruku _or_ Kramdown (\/%>[markdown])
+* Sass (if you want to load .sass files with the %>[style])
+* CodeRay _or_ UltraViolet (\/%>[highlight])
 * directory_watcher (to use auto-regeneration with the #>[compile])
 	]
 
@@ -33,5 +33,4 @@ Every Glyph project is comprised of the following directories:
 Additionally, the following files are also created at top level:
 * @config.yml@ -- containing your =>[#cfg|Project Configuration].
 * @document.glyph@ -- containing the =>[#struct|structure] of your document.
-* @snippets.yml@ -- containing your text =>[#incl|snippets].
 ]

data/book/text/getting_started/structure.glyph

@@ -36,7 +36,7 @@ book[
 	textile[
 Even without knowing anything about &[glang], you can easily figure out that this file defines a document with a Table of Contents, a Preface some Chapters and an Appendix.
 
-As you can see, Glyph wraps portions of text within square brackets preceded by an identifier. These identifiers are used for em[\.=>[#macro_intro|macros]] and em[\.=>[#attribute_intro|attributes]]. The only syntactic difference between macros and attributes is that attributes are preceded by a code[@]. 
+As you can see, Glyph wraps portions of text within square brackets preceded by an identifier. These identifiers are used for em[\/=>[#macro_intro|macros]] and em[\/=>[#attribute_intro|attributes]]. The only syntactic difference between macros and attributes is that attributes are preceded by a code[@]. 
 
 For now, think about a macro as something that performs a certain action and -- generally -- produces some text output or manipulation of the text inside it. In this way, it becomes easy to understand that the @chapter@ macro creates a chapter and the %>[include] includes an external file, for example.
 Attributes "belong" to the macro they're in, so in this case the %>[book] has the following attributes:
@@ -47,5 +47,5 @@ Attributes "belong" to the macro they're in, so in this case the %>[book] has th
 More specifically, in this @document.glyph@ file:
 * The %>[book] wraps every other macro and is used to create the document header and default title page.
 * Then, the code[@frontmatter], code[@bodymatter], and code[@backmatter] attributes are used to divide the portions of your document according to the rules of =>[http://en.wikipedia.org/wiki/Book_design|book design]. They are not mandatory, but they can be used, for example, to number your appendixes with letters instead of numbers and similar.
-* @preface@, @chapter@, @appendix@ are just a way to wrap content in @<div>@ tags, from an HTML point of view, but they are also necessary to nest the content of your document and generate the Table of Contents automatically, together through code[@title] attributes.
+* @preface@, @chapter@, @appendix@ are just a way to wrap content in @<div>@ tags, from an HTML point of view (or @<section>@ tags, in HTML5), but they are also necessary to nest the content of your document and generate the Table of Contents automatically, together through code[@title] attributes.
 	]

data/book/text/macros/macros_core.glyph

@@ -1,214 +1,356 @@
 
-	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[
+  ref_macro[
+    @n[add]
+    @desc[Adds two or more integers together.]
+    @params[Two or more integer values.]
+    @example[=add[2\|5\|7]=]
+  ]
+
+  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[attribute]
+    @desc[Returns the value of the specified attribute. ##[see_let|For a more complete example, see the %>[let]].]
+    @aliases[@]
+    @example[=@[title]=]
+    @params[-p[0|The name of the attribute to retrieve.]]
+  ]
+
+  ref_macro[
+    @n[attribute:]
+    @desc[Sets the value of the specified attribute. <=[see_let].]
+    @aliases[@:]
+    @example[=@:[title\|Test Title]=]
+    @params[
+      -p[0|The name of the attribute to set.]
+      -p[1|The value of the attribute.]
+    ]
+  ]
+
+  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[
+    ]
+    @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[
+    ]
+    @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[1|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[
+    ]
+  ]
+
+  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[1|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[fragment]
+    @desc[Delimits a fragment of text that can be embedded using the %>[embed].]
+    @aliases[##]
+    @example[=##\[test_fragment\|This is an embeddable fragment\]=]
+    @params[
+      -p[0|The ID of the fragment.]
+      -p[1|The contents of the fragment.]
+    ]
+  ]
+
+  ref_macro[
+    @n[embed]
+    @desc[Embeds text previously-delimited using the %>[fragment].]
+    @aliases[&amp;=]
+    @example[=&amp;=\[test_fragment\]=]
+    @params[-p[0|The ID of the fragment.]]
+  ]
+
+  def:[comp_macro|
+    ref_macro[
+      @n[{{0}}]
+      @desc[Returns em[true] if the first parameter is {{0}} the second one.]
+      @example[={{1}}\[5\|2\]=]
+      @params[
+        -p[0|The first integer to compare.]
+        -p[1|The second integer to compare.]
+      ]
+    ]
+  ]
+
+  comp_macro[gt|greater than]
+
+  comp_macro[gte|greater than or equal to]
+
+  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[output?]
-		@desc[Evaluates to true if Glyph is generating output in the specified format(s).]
-		@example[=?[output?[web\|web5]\|This text is printed only when generating web or web5 output.]=]
-		@params[
-			-p[0, ...|a valid output target.]
-		]
-	]
-
-	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\|
+    ]
+    @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 =>[&[rubydoc]/Glyph|Glyph] module.
+        ]
+      ]
+    ]
+  ]
+
+  ref_macro[
+    @n[let]
+    @desc[Used to bind one or more attributes via the %>[attribute]. Actually, you can use %>[attribute] inside any other macro, but it looks tidier in this way.]
+    @block_example[=
+let[
+  @:[a\|2]
+  @:[b\|3]
   section[
-    @title[Release {{0}}]
-    {{1}}
+    @title[Testing]
+    @[title]: @[a] * @[b] = multiply[@[a]\|@[b]] --[Outputs: Testing: 2 * 3 = 6]
   ]
 ]
-		=]
-		@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[=
+    =]
+    @params[-p[0|Any content.]]
+  ]
+
+  ref_macro[
+    @n[load]
+    @desc[Embeds the contents of a file.]
+    @params[
+      -p[0|The file to embed, relative to the Glyph project folder.]
+    ]
+    @example[=load[my_samples.rb]=]
+  ]
+
+  comp_macro[lt|less than]
+
+  comp_macro[lte|less than or equal to]
+
+  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[multiply]
+    @desc[Multiplies two or more integers together.]
+    @params[Two or more integer values.]
+    @example[=add[3\|5\|9]=]
+  ]
+
+  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[output?]
+    @desc[Evaluates to true if Glyph is generating output in the specified format(s).]
+    @example[=?[output?[web\|web5]\|This text is printed only when generating web or web5 output.]=]
+    @params[
+      -p[0, ...|a valid output target.]
+    ]
+  ]
+
+  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[define:]
+    @desc[Defines a new macro in Glyph code (for more information, see =>[#rewriting])]
+    @aliases[def:]
+    @params[
+      -p[0|The name of the new macro.]
+      -p[0|The macro definition (Glyph code).]
+    ]
+    @block_example[=
+def:[factorial\|
+  ?[
+    eq[{{0}}\|0]\|1\|
+    multiply[
+      {{0}} \| factorial[subtract[{{0}}\|1]]
+    ]
+  ]
+]
+factorial[5]
+    =]
+    @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 =>[&[rubydoc]/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.]
-		]
-	]
+    =]
+    @params[-p[0|The Ruby code to evaluate.]]
+    @remarks[&[unsafe]]
+  ]
+
+  ref_macro[
+    @n[s]
+    @desc[Can be used to dispatch almost any instance method of the ruby =>[http://rubydoc.info/stdlib/core/1.9.2/String|String] class.]
+    @examples[=
+s/match[This is a test string\|/test/]
+s/sub[This is a test string\|/a test/\|another test]
+    =]
+  ]
+
+  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.]
+    ]
+  ]
+
+  ref_macro[
+    @n[subtract]
+    @desc[Subtracts two or more integers together.]
+    @params[Two or more integer values.]
+    @example[=add[10\|5\|2]=]
+  ]
+
+  ref_macro[
+    @n[xml]
+    @desc[When used composed with another macro, it can be used to render arbitrary raw XML tags.]
+    @example[=xml/img[@src[test.png]@alt[A Test image]]=]
+  ]
+
+  ref_macro[
+    @n[while]
+    @desc[Keeps evaluating the second parameter while a condition is satisfied.]
+    @block_example[=
+let[
+  @count[5]
+  @text[-]
+  while[gt[@[count]\|0]\|
+    @:[text\|s/concat[@[text]\|@[count]-]]          
+    @:[count\|subtract[@[count]\|1]]
+  ]
+  @[text] --[Outputs: -5-4-3-2-1-]
+]
+    =]
+    @params[
+      -p[0|The condition to check.]
+      -p[1|The code to evaluate while the condition is satisfied.]
+    ]
+  ]