glyph 0.3.0 → 0.4.0

data/book/text/license.glyph

@@ -1,5 +1,4 @@
-Copyright (c) 2010 **Fabio Cevasco**, =>[http://www.h3rald.com]  
-
+p[Copyright © 2010 strong[Fabio Cevasco], =>[http://www.h3rald.com]] 
 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

data/book/text/macros/macros_block.glyph

@@ -1,6 +1,3 @@
-section[
-	@title[Block Macros]
-
 	ref_macro[
 		@n[box]
 		@desc[Creates a titled box (@<div>@ tag).]
@@ -65,6 +62,14 @@ img[
 		]
 	]
 
+	ref_macro[
+		@n[navigation]
+		@desc[Displays links to the document's TOC and the previous/next topic (used only in =>[#layouts|layouts]). ]
+		@params[
+			-p[0|The ID of the current topic.]
+		]
+	]
+
 	ref_macro[
 		@n[note]
 		@desc[Creates a note @div@ containing the value.]
@@ -96,4 +101,3 @@ img[
 		@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

@@ -1,5 +1,3 @@
-section[
-	@title[Core Macros]
 
 	ref_macro[
 		@n[alias]
@@ -205,4 +203,3 @@ rw:[release\|
 			-p[1|The contents of the new snippet.]
 		]
 	]
-]

data/book/text/macros/macros_filters.glyph

@@ -1,11 +1,7 @@
-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@.
+Uses a Markdown converter (BlueCloth, RDiscount, Maruku or Kramdown) to transform the value into HTML if the =>[#cfg_output|code[output.*.filter_target]] setting is set to @html@.
 
 &[called_on_files] with a @.markdown@ or a @.md@ extension. 
 		]
@@ -17,7 +13,7 @@ Uses a Markdown converter (BlueCloth, RDiscount, Maruku or Kramdown) to transfor
 	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].
+Uses the RedCloth gem to transform the value into HTML or LaTeX, depending on the value of the =>[#cfg_output|code[output.*.filter_target]].
 
 &[called_on_files] with a @.textile@ or a @.txt@ extension. 
 		]
@@ -37,4 +33,3 @@ highlight[ruby\|
 ]
 		=]
 	]
-]

data/book/text/macros/macros_inline.glyph

@@ -1,6 +1,3 @@
-section[
-	@title[Inline Macros]
-	
 	ref_macro[
 		@n[anchor]
 		@desc[Creates a named anchor (or bookmark).]
@@ -47,4 +44,3 @@ section[
 		@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

@@ -1,6 +1,3 @@
-section[
-	@title[Structure Macros]
-
 	ref_macro[
 		@n[article]
 		@desc[
@@ -97,4 +94,3 @@ section[
 		@example[=toc[1]=]
 		@params[-p[0|The maximum header depth of the TOC &[opt].]]
 	]
-] 

data/book/text/ref_commands.glyph

@@ -16,7 +16,7 @@ section[
 	]
 ]
 section[
-	@title[code[add]]
+	@title[add]
 	@id[c_add]
 	p[Creates a new text file in the code[text/] folder.]
 	example[glyph add introduction.textile]
@@ -25,7 +25,7 @@ section[
 	]
 ]
 section[
-	@title[code[compile]]
+	@title[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]
@@ -49,7 +49,7 @@ If specified, enable =>[#auto_regeneration|auto regeneration] (requires the =>[h
 	]
 ]
 section[
-	@title[code[config]]
+	@title[config]
 	@id[c_config]
 Gets or sets a configuration setting in the project or global configuration file (\.fmi[configuration files|#cfg]).
 	examples[
@@ -68,7 +68,7 @@ If specified, the global configuration file is processed instead of the project
 	]
 ]
 section[
-	@title[code[help]]
+	@title[help]
 	@id[c_help]
 Prints information about all Glyph commands or about one specific command.
 	examples[
@@ -80,13 +80,13 @@ glyph help compile
 	]
 ]
 section[
-	@title[code[init]]
+	@title[init]
 	@id[c_init]
 Creates a new Glyph project in the current directory (if empty).
 	example[glyph init]
 ]
 section[
-	@title[code[outline]]
+	@title[outline]
 	@id[c_outline]
 Display an outline of the current document.
 	options[
@@ -110,7 +110,29 @@ glyph outline -f
 	]
 ]
 section[
-	@title[code[todo]]
+	@title[stats]	
+	@id[c_stats]
+	rw:[stats_option|-o[{{0}}|If specified, general statistics about {{0}} are displayed (see =>[#stats_{{0}}]).]]
+	rw:[stats_long_option|long_option[{{0}}|Display detailed statistics about the specified {{0}}.]]
+	p[Displays project statistics (\.fmi[this command|#stats]).]
+	examples[
+glyph	stats -m 
+glyph stats --link=h3rald.com
+	]
+	options[
+		stats_option[bookmarks]
+		stats_long_option[bookmark]
+		-o[files|If specified, general statistics about project files are displayed.]
+		stats_option[links]
+		long_option[link|Display detailed statistics about all links whose target matches the specified regular expression.]
+		stats_option[macros]
+		stats_long_option[macro]
+		stats_option[snippets]
+		stats_long_option[snippet]
+	]
+]
+section[
+	@title[todo]
 	@id[c_todo]
 Prints all the todo items saved using the %>[todo].
 	example[glyph todo]

data/book/text/stats/bookmarks.glyph

@@ -0,0 +1,49 @@
+stats_for[
+	@title[all bookmarks]
+	@object[all bookmarks]
+	@command[--bookmarks]
+	@example[
+===== Bookmarks
+-- Total Bookmarks: 241
+-- Total Referenced Bookmarks: 89
+-- Total Unreferenced Bookmarks: 155
+-- Bookmarks:
+     attribute_intro     auto_regeneration      c_add         c_compile    c_config                           
+     c_help              c_init                 c_outline     c_todo       cfg                                
+     cfg_document        cfg_filters            cfg_ref       cmd_ref      compile  
+\[...\]
+-- Referenced Bookmarks:
+   - attribute_intro (1)
+   - auto_regeneration (2)
+   - c_add (2)
+   - c_compile (10)
+   - c_config (6)
+   - c_init (1)
+   - c_outline (1)
+\[...\]
+-- Unreferenced Bookmarks:
+     c_help     cmd_ref    expanded_values        extending     h_1                                
+     h_10       h_102      h_105                  h_107         h_109                              
+     h_111      h_112      h_114                  h_115         h_117    
+\[...\] 
+  ]
+	@remarks[
+* All the automatically-generated bookmarks (like headers, starting with @h_@) are included as well. 
+	]
+]
+stats_for[
+	@title[a single bookmark]
+	@object[a single bookmark (e.g. code[yardoc])]
+	@command[--bookmark=c_config]
+	@example[
+===== Bookmark 'c_config' (header)
+-- Defined in: text/ref_commands.glyph
+-- Referenced in:
+   - text/changelog.glyph (2)
+   - text/getting_started/configuration.glyph (1)
+   - text/troubleshooting/errors_command.glyph (3)
+	]
+	@remarks[
+* Do not prepend the bookmark ID with @#@.
+	]
+]

data/book/text/stats/links.glyph

@@ -0,0 +1,90 @@
+stats_for[
+	@title[all links]
+	@object[all links]
+	@command[--links]
+	@example[
+===== Links
+-- Total Internal Links: 89
+-- Internal Links
+   - #attribute_intro 
+   - #auto_regeneration 
+   - #c_add 
+   - #c_compile 
+   - #c_config 
+   - #c_init 
+   - #c_outline 
+   - #c_stats 
+   - #c_todo 
+   - #cfg 
+   - #cfg_document 
+   - #cfg_filters 
+\[...\]
+-- Total External Links: 95
+-- External Links
+   - &\[yardoc\]/Glyph 
+   - &\[yardoc\]/Glyph/Document 
+   - &\[yardoc\]/Glyph/Interpreter 
+   - &\[yardoc\]/Glyph/Macro 
+   - &\[yardoc\]/Glyph/Macro/Validators 
+   - &\[yardoc\]/Glyph/Macro:update_source 
+   - &\[yardoc\]/Glyph/MacroNode 
+   - &\[yardoc\]/Glyph/Parser 
+   - &\[yardoc\]/Glyph/SyntaxNode 
+   - &\[yardoc\]/Macro 
+   - http://code.google.com/p/wkhtmltopdf/ 
+   - http://coderay.rubychan.de/ 
+   - http://coderay.rubychan.de/doc/classes/CodeRay/Encoders/HTML.html 
+\[...\]   
+  ]
+	@remarks[
+* The only criteria used to determine if a link is internal is whether it starts with a @#@ or not.
+	]
+]
+stats_for[
+	@title[links matching a regular expression]
+	@object[links matching a regular expression (e.g. code[/c_/])]
+	@command[--link=c_]
+	@example[
+===== Links matching /c_/
+-- Total Links: 8
+-- Link Targets:
+   - #c_add 
+   - #c_compile 
+   - #c_config 
+   - #c_init 
+   - #c_outline 
+   - #c_stats 
+   - #c_todo 
+   - #esc_quot 
+-- Details:
+   - #c_add (2)
+     - text/troubleshooting/errors_command.glyph (1)
+     - text/troubleshooting/errors_generic.glyph (1)
+   - #c_compile (10)
+     - text/changelog.glyph (1)
+     - text/compiling/compiling.glyph (2)
+     - text/compiling/lite_mode.glyph (1)
+     - text/compiling/programmatic_usage.glyph (2)
+     - text/getting_started/create_project.glyph (1)
+     - text/ref_config.glyph (1)
+     - text/troubleshooting/errors_command.glyph (2)
+   - #c_config (6)
+     - text/changelog.glyph (2)
+     - text/getting_started/configuration.glyph (1)
+     - text/troubleshooting/errors_command.glyph (3)
+   - #c_init (1)
+     - text/troubleshooting/errors_generic.glyph (1)
+   - #c_outline (1)
+     - text/changelog.glyph (1)
+   - #c_stats (1)
+     - text/stats/stats.glyph (1)
+   - #c_todo (1)
+     - text/macros/macros_inline.glyph (1)
+   - #esc_quot (2)
+     - text/extending/macro_def.glyph (1)
+     - text/text_editing/macro_intro.glyph (1)
+	]
+	@remarks[
+* No distinction between external and internal targets is made.
+	]
+]

data/book/text/stats/macros.glyph

@@ -0,0 +1,73 @@
+stats_for[
+	@title[all macros]
+	@object[all macros]
+	@command[--macros]
+	@example[
+===== Macros
+-- Total Macro Instances: 2497
+-- Total Macro Definitions: 65
+-- Total Macro Aliases: 57
+-- Total Used Macro Definitions: 56
+-- Macro Definitions:
+     #>            $>            %>            alias:        aliases       
+     anchor        and           article       author        block_example 
+     book          box           class         codeblock     comment       
+     condition     config        config:       config_table  default       
+     document      draftcomment  eq            error_table   escape        
+     example       examples      features      figure        fmi           
+     head          highlight     image         include       issue         
+     link          macro:        markdown      match         navigation    
+     not           note          option        or            parameters    
+     pubdate       ref_config    ref_error     ref_macro     release       
+     revision      rewrite:      ruby          section       snippet       
+     snippet:      stats_for     style         subtitle      textile       
+     title         toc           todo          values        \|xml\|         
+
+-- Used Macro Definitions:
+     #>            $>            %>            aliases       anchor        
+     and           author        block_example book          box           
+     class         codeblock     comment       condition     config        
+     config_table  default       document      eq            error_table   
+     escape        example       examples      features      figure        
+     fmi           head          highlight     image         include       
+     issue         link          note          option        or            
+     parameters    pubdate       ref_config    ref_error     ref_macro     
+     release       revision      rewrite:      ruby          section       
+     snippet       snippet:      stats_for     style         subtitle      
+     textile       title         toc           todo          values        
+     \|xml\|         
+  ]
+	@remarks[
+* Only macro _definitions_ (not their _aliases_) are displayed, both default and user-defined.
+* The @\|xml\|@ macro is a special macro used if the $>[options.xml_fallback] is enabled.
+* There's no distinction between macros defined by the user and macros defined by Glyph itself.
+	]
+]
+stats_for[
+	@title[a single macro]
+	@object[a single macro (e.g. code[note])]
+	@command[--macro=note]
+	@example[
+===== Macro 'note' 
+-- Total Instances: 18
+-- Occurrences:
+   - text/compiling/compiling.glyph (2)
+   - text/compiling/programmatic_usage.glyph (1)
+   - text/extending/params_attrs.glyph (1)
+   - text/getting_started/configuration.glyph (1)
+   - text/stats/macros.glyph (2)
+   - text/text_editing/attribute_intro.glyph (1)
+   - text/text_editing/esc_quot.glyph (1)
+   - text/text_editing/images.glyph (1)
+   - text/text_editing/inclusions.glyph (3)
+   - text/text_editing/links.glyph (1)
+   - text/text_editing/raw_html.glyph (1)
+   - text/text_editing/section_aliases.glyph (1)
+   - text/text_editing/xml_fallback.glyph (2)
+	]
+	@remarks[
+* All the instances of the specified macro definition _and all its aliases_ are collected, regardless whether a definition or an alias is specified.
+* If you use custom macros, make sure they call the =>[&[yardoc]/Glyph/Macro:update_source|Macro#update_source] appropriately method if necessary.
+* If macros are used within =>[#rewriting|rewritten] macros, they'll be also listed in each file where the rewritten macro is used. 
+	]
+]

data/book/text/stats/snippets.glyph

@@ -0,0 +1,50 @@
+stats_for[
+	@title[all snippets]
+	@object[all snippets]
+	@command[--snippets]
+	@example[
+===== Snippets
+-- Total Snippets: 21
+-- Total Used Snippets: 21
+-- Total Unused Snippets: 0
+-- Snippets:
+     bin_params             called_on_files        coderay                filter_by_ext          gcode                  
+     glang                  htmlcode               img_attrs              img_file               macros                 
+     markups                only_after_declaration only_defined_through   opt                    prince                 
+     referenced_with_path   sq_esc                 unsafe                 uv                     wkhtml                 
+     yardoc                 
+-- Used Snippets:
+     bin_params             called_on_files        coderay                filter_by_ext          gcode                  
+     glang                  htmlcode               img_attrs              img_file               macros                 
+     markups                only_after_declaration only_defined_through   opt                    prince                 
+     referenced_with_path   sq_esc                 unsafe                 uv                     wkhtml                 
+     yardoc                 
+	]
+	@remarks[
+* Information on snippet usage and definitions is available only when displaying statistics for a single snippet.
+	]
+]
+stats_for[
+	@title[a single snippet]
+	@object[a single snippet (e.g. code[yardoc])]
+	@command[--snippet=yardoc]
+	@example[
+===== Snippet 'yardoc'
+-- Definition:
+-------------------
+http://yardoc.org/docs/h3rald-glyph
+-------------------
+-- Total Used Instances: 18
+-- Usage Details:
+   - text/extending/bookmarks_headers.glyph (1)
+   - text/extending/further_reading.glyph (5)
+   - text/extending/internals.glyph (5)
+   - text/extending/macro_def.glyph (3)
+   - text/extending/validators.glyph (1)
+   - text/macros/macros_core.glyph (2)
+   - text/stats/macros.glyph (1)
+	]
+	@remarks[
+* Nested snippets appear as within the file containing the top-level snippet.
+	]
+]