glyph 0.3.0 → 0.4.0

data/book/snippets.yml

@@ -5,7 +5,7 @@
 :gcode: "The following Glyph code:"
 :htmlcode: "Is translated into the following HTML code:"
 :markups: Textile or Markdown
-:filter_by_ext: "the $>[filters.by_file_extension] is @true@"
+:filter_by_ext: "the $>[options.filters_by_file_extension] is @true@"
 :called_on_files: "If &[filter_by_ext], this macro is called automatically on =>[#m_include|included] files"
 :only_after_declaration: "can only be used _after_ its declaration"
 :coderay: "=>[http://coderay.rubychan.de/|Coderay]"

data/book/text/{acknowledgement.glyph → acknowledgements.glyph}

@@ -1,8 +1,10 @@
+txt[
 Glyph was designed and developed by =>[http://www.h3rald.com|Fabio Cevasco] (h3rald).
 
 Special thanks to the following individuals who contributed to Glyph by reporting and fixing issues and/or proposing and implementing new features:
 * =>[http://www.jabbslad.com|Jamie Atkinson] (Jabbslad)
 * =>[http://koraktor.github.com|Sebastian Staudt] (koraktor)
-
-
+* =>[http://balcone.eveel.ru|Dmitry A. Ustalov] (eveel)
+* =>[http://www.stuartellis.eu|Stuart Ellis] (stuartellis)
+]
     

data/book/text/changelog.glyph

@@ -1,7 +1,7 @@
 %[=
 macro :features do
 	verb = (@name == :features) ? "Implemented" : "Fixed"
-	total = @node.children[0].children.length
+	total = @node.child_macros.length
 	interpret %{
 		section[
 			@title[#{total} #{@name.to_s.capitalize} #{verb}]
@@ -30,11 +30,37 @@ rw:[issue|
 		td[txt[{{1}}]]
 	]
 ]
-?[%[lite?]|
+?[eq[%[ARGV\[0\]]|generate]|
 	%:[%>|"#{value} macro"]
 	%:[#>|"#{value} command"]
 	%:[$>|"#{value} setting"]
 ]
+release[0.4.0|September 3th 2010|
+	features[
+		issue[40|A new #>[stats] can be used to display statistics about project files, snippets, macros, bookmarks and links.]
+		issue[73|It is now possible to validate online HTTP links.]
+		issue[112|It is now possible to use _wkhtmltopdf_ instead of Prince to generate PDF files from HTML files.]
+		issue[114|It is now possible to generate documents comprised of multiple files (topics).]
+		issue[115|It is now possible to define layouts (used when generating multi-file outputs) using Glyph macros.]
+		issue[120|It is now possible to compile your project to a single HTML5 file (@html5@ output) or multiple files (@web5@ output)]
+		issue[135|Stylesheets can now be linked and imported as well as embedded.]
+		issue[138|@web@ and @web5@ output formats inherit @html@ macros.]
+		issue[142|A new %>[navigation] can be used in @web@ and @web5@ outputs to navigate through topics.]
+		issue[143|A topic-based TOC is generated when compiling to @web@ or @web5@]
+		issue[144|Two new validators are now available to check whether a macro has (or doesn't have) a certain ancestor: @within@ and @not_within@.]
+		issue[147|The default stylesheets provided by Glyph are now compatible with HTML5 outputs (html5 and web5).]
+		issue[148|It is now possible to create custom tasks and commands to extend Glyph functionality.]
+	]
+	bugs[
+		issue[133|Added HTML charset to Glyph documents (utf-8).]
+		issue[136|Moved utility functions to separate @Glyph::Utils@ module.]
+		issue[139|Heavily restructured Glyph configuration.]
+		issue[140|Added @Glyph::Macro::Helpers@ module to avoid code duplication in macros for different output formats.]
+		issue[141|Prevented non-rb files to be loaded as macros.]
+		issue[145|Dotfiles are now ignored by #>[init].]
+		issue[167|Fixed PDF book download links.]
+	]
+]
 release[0.3.0|June 13th 2010|
 	features[
 		issue[39|A new #>[outline] is available to display the document outline.]
@@ -47,7 +73,7 @@ release[0.3.0|June 13th 2010|
 		issue[124|Implemented new %>[article] and %>[book].]
 		issue[126|A new %>[rewrite:] has been implemented to create simple macros using just Glyph code.]
 		issue[127|A new %>[alias] has been implemented to create macro aliases.]
-		issue[128|A blacklist for XML tags has been exposed via the $>[language.options.xml_blacklist].]
+		issue[128|A blacklist for XML tags has been exposed via the @language.options.xml_blacklist@ setting.]
 		issue[129|The %>[include] can now be used in lite mode, it can evaluate ruby files and requires relative paths.]
 		issue[130|A new "safe mode" has been implemented to explicitly forbid certain potentially unsafe macros.]
 	]

data/book/text/compiling/compiling.glyph

@@ -1,23 +1,47 @@
+txt[
+By default, a Glyph project can be "compiled" into an HTML document. Additionally, Glyph can also be used to produce documents in the following formats:
+* HTML5
+* PDF (generated from HTML using a third-party generator like &[prince] or &[wkhtml])
+* Web (i.e. multiple HTML files)
+* Web5 (i.e. multiple HTML5 files)
+]
 section[
-	@title[Compiling a project]
-	@id[compile]
-	p[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 output targets will be supported.]
-	section[
-		@title[HTML output]
-		p[To compile a Glyph project to an HTML document, use the #>[compile] within your Glyph project folder. Glyph parses the code[document.glyph] file (and all included files and snippets); if no errors are found, Glyph creates an HTML document in the code[/output/html] folder.] 
-		p[The name of the HTML file can be set in the configuration (\.$>[document.filename]).]
-	]
-	section[
-		@title[PDF Output]
-		p[To generate a PDF document, you must specify code[pdf] as format, like this:]
-		p[code[= glyph compile -f pdf =]]
-		p[The command above will attempt to compile the project into an HTML document and then call Prince to generate a PDF document from it. In order for this to work, you must download and install &[prince]. It's not open source, but the free version is fully functional, and it just adds a small logo on the first page.]
-		note[Glyph v\.%[Glyph::VERSION] has been successfully tested with Prince v7.0, and the PDF version of this very book was generated with it.]
-	]
-	section[
-		@title[Auto Regeneration]
-		@id[auto_regeneration]
-		txt[You can also call the #>[compile] with a @--auto@ switch. If you do so, your project will be recompiled automatically every time any source file is changed.]
-		note[Auto regeneration requires the =>[http://rubygems.org/gems/directory_watcher|directory_watcher] gem to be installed.]
+	@title[HTML/HTML5 output]
+	p[To compile a Glyph project to an HTML document, use the #>[compile] within your Glyph project folder. Glyph parses the code[document.glyph] file (and all included files and snippets); if no errors are found, Glyph creates an HTML document in the code[/output/html] folder.] 
+	p[The name of the HTML file can be set in the configuration (\.$>[document.filename]).]
+	p[To create an HTML5 file instead, you must specify it explicitly like this:]
+	p[code[= glyph compile -f html5 =]]
+]
+section[
+	@title[PDF Output]
+	p[To generate a PDF document, you must specify code[pdf] as format, like this:]
+	p[code[= glyph compile -f pdf =]]
+	p[The command above will attempt to compile the project into an HTML document and then call a third-party PDF generator to convert it into a PDF file.]
+	txt[
+Currently, Glyph supports:
+* &[prince] (version 7.0 or higher) -- a commercial generator that can be used freely for personal use. Prince produces high-quality PDF files and implement most of the new features introduced in CSS3, used heavily in Glyph's =>[#default_stylesheets|code[pagination.css]] default stylesheet.
+* &[wkhtml] (version 1.0 beta4 or higher) -- an open source generator that uses the WebKit rendering engine to transform HTML files into PDF. Although not as advanced as Prince, it produces very satisfactory results.
+
+By default, Glyph attempts to use wkhtmltopdf. To change this, set the $>[output_pdf_generator] to code[prince]. 
 	]
+	note[Glyph expects PDF generators to be installed on the local machine and callable via command line using the code[wkhtmltopdf] or the code[prince] commands. Just install them as you would with any other program, depending on your operating system (yes, they both offer Windows installers).]
+	tip[Glyph's default CSS file use the free em[Gentium] font for all text. You can download it from =>[http://www.sil.org/~gaultney/gentium/|here].]
+]
+section[
+	@title[Web/Web5 Output]
+	@id[web_output]
+	txt[
+To generate a Web or Web5 output, specify @web@ or @web5@ as format. These two output formats behave different way from the others, and require that your project uses =>[#topics|topics] and =>[#layouts|layouts]. 
+
+Basically, here's what happens when you compile your project in web or web5 format:
+# The document code is parsed as normal
+# Separate topic files are generated according to the code[@src] attributes of your sections
+# The code[document.glyph] (or whatever file you're using as document source) is _not_ rendered. Instead, an @index.html@ file will be created in the output folder based on the contents of your =>[#index_layout|index layout]. 
+	]	
+]
+section[
+	@title[Auto Regeneration]
+	@id[auto_regeneration]
+	txt[You can also call the #>[compile] with a @--auto@ switch. If you do so, your project will be recompiled automatically every time any source file is changed.]
+	note[Auto regeneration requires the =>[http://rubygems.org/gems/directory_watcher|directory_watcher] gem to be installed.]
 ]

data/book/text/compiling/lite_mode.glyph

@@ -1,6 +1,3 @@
-section[
-	@title[Compiling single Glyph files]
-	@id[lite_mode]
 	p[Glyph's primary goal is to author complex documents like books or manuals. In order to do so, a Glyph project is required to keep everything organized and automated via a set of predefined conventions, exactly like Ruby on Rails or other similar frameworks do.]
 	p[If you want to write a one-page article or a short draft, however, creating and managing Glyph projects can be an unnecessary burden. Luckily, you don't have to: you can use Glyph to compile single files containing Glyph code, by adding one parameter (or two if you want to specify a custom destination file) to the #>[compile], like this:]
 	p[code[glyph compile source.glyph destination.htm]]
@@ -20,4 +17,3 @@ This sort of "lite" mode comes with a few minor limitations:
 * The files included through the %>[include] &[referenced_with_path].
 		]
 	]
-]

data/book/text/compiling/programmatic_usage.glyph

@@ -1,5 +1,3 @@
-section[
-	@title[Using Glyph programmatically]
 	txt[
 Besides using Glyph from the command line, you can also use it straight from your code. Glyph's public =>[http://yardoc.org/docs/glyph/Glyph|API] is simple and can be used to:
 * Retrieve and update configuration settings (using @Glyph\[\]@ and @Glyph\[\]=@)
@@ -11,8 +9,7 @@ That's pretty much it. Of course, both the @filter@ and @compile@ method cause G
 	tip[
 		txt[
 For an example on how to use Glyph programmatically (specifically in conjunction with the =>[http://nanoc.stoneship.org/|nanoc] static site generator), see =>[http://github.com/h3rald/h3rald|h3rald.com source code], in particular:
-* =>[http://github.com/h3rald/h3rald/blob/master/lib/glyph-data.rb|lib/glyph-data.rb] -- updating configuration settings.
-* =>[http://github.com/h3rald/h3rald/blob/master/lib/glyph-filter.rb|lib/glyph-data.rb] -- using the @Glyph#filter@ method.
+* =>[http://github.com/h3rald/h3rald/blob/master/lib/glyph_filter.rb|lib/glyph_filter.rb] -- using the @Glyph#filter@ method.
 * =>[http://github.com/h3rald/h3rald/blob/master/Rules|Rules] -- using the @Glyph#compile@ method to generate PDF files.
 		]
 	]
@@ -74,4 +71,3 @@ If enabled, the following macros cannot be used and will return an error:
 			]
 		]
 	]
-]

data/book/text/config/document.glyph

@@ -0,0 +1,35 @@
+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:
+%[=Glyph['output'].keys.reject{\|v\| v == :h3rald }.map{\|v\| "* @#{v}@"}.sort.join("\n")=]
+	]
+	ref_config[document.revision|
+The document's revision.
+	]
+	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.styles|
+How to process stylesheets. It can be set to one of the following values:
+* @embed@ -- Embed stylesheets within the document.
+* @link@ -- Link stylesheets.
+* @import@ -- Import stylesheets using the code[@import] CSS directive. 
+	]
+	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].
+	]
+]

data/book/text/config/filters.glyph

@@ -0,0 +1,28 @@
+These settings are used to configure some special options related to output filters and highlighters.
+
+config_table[
+	ref_config[filters.coderay.*|
+Some &[coderay]-specific =>[http://coderay.rubychan.de/doc/classes/CodeRay/Encoders/HTML.html|options].
+	]
+	ref_config[filters.highlighter|
+The current highlighter to use. It can be set to @coderay@ or @ultraviolet@
+	]
+	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.ultraviolet.line_numbers|
+Whether the &[uv] highlighter should display line numbers or not.
+	]
+	ref_config[filters.ultraviolet.theme|
+The theme used by the &[uv] highlighter.
+	]
+]

data/book/text/config/options.glyph

@@ -0,0 +1,25 @@
+The following configuration settings are used to enable or disable specific Glyph functionalities and behaviors.
+
+config_table[
+	ref_config[options.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[options.macro_set|
+Determines which macro set will be loaded. It can be set to:
+* glyph -- Loads core, filter, xml macros plus all macros necessary for the $>[document.output].
+* xml -- Loads core and xml macros.
+* core -- Loads core macros only.
+	]
+	ref_config[options.safe_mode|
+Enables Safe Mode (\.fmi[Glyph modes|#modes]).
+	]
+	ref_config[options.url_validation|
+If set to _true_, every external link will be validated (see =>[#links]). 
+	]
+	ref_config[options.xml_blacklist|
+The XML tags listed here cannot be generated using Glyph code.
+	]
+	ref_config[options.xml_fallback|
+If set to true, any unknown macro name will considered an XML element (see =>[#other_elements]).
+	]
+]

data/book/text/config/output.glyph

@@ -0,0 +1,83 @@
+&:[o_multifile|
+If set to _true_, the document will be rendered in multiple files, according to the specified =>[#topics|topics].
+]
+&:[o_extension|
+The extension to use for the output file(s).
+]
+&:[o_filter_target|
+The output target for filters. It can be set to @html@ (for RedCloth and MarkDown) or @latex@ (RedCloth-only). 
+]
+&:[o_macro_dirs|
+The directories from which macros will be loaded (both in Glyph's home and the current project directory).
+]
+&:[o_layout_dirs|
+The directories from which layout macros will be loaded (both in Glyph's home and the current project directory).
+]
+&:[o_layouts.topic|
+The name of the layout to use to render topic files.
+]
+&:[o_layouts.index|
+The name of the layout to use to render the document index file.
+]
+&:[o_base|
+The directory to use as root for all link paths.
+]
+These settings are used to configure output-specific options.
+
+
+section[
+	@title[output.pdf.*]
+	config_table[
+		out_cfg[pdf.extension]
+		out_cfg[pdf.filter_target]
+		ref_config[output.pdf.generator|
+The external program used to generate PDF files. It can be set to @prince@ or @wkhtmltopdf@.
+		]
+		out_cfg[pdf.macro_dirs]
+		out_cfg[pdf.multifile]
+	]
+]
+section[
+	@title[output.html.*]
+	config_table[
+		out_cfg[html.extension]
+		out_cfg[html.filter_target]
+		out_cfg[html.macro_dirs]
+		out_cfg[html.multifile]
+	]
+]
+section[
+	@title[output.html5.*]
+	config_table[
+		out_cfg[html5.extension]
+		out_cfg[html5.filter_target]
+		out_cfg[html5.macro_dirs]
+		out_cfg[html5.multifile]
+	]
+]
+section[
+	@title[output.web.*]
+	config_table[
+		out_cfg[web.base]
+		out_cfg[web.extension]
+		out_cfg[web.filter_target]
+		out_cfg[web.layout_dirs]
+		out_cfg[web.layouts.index]
+		out_cfg[web.layouts.topic]
+		out_cfg[web.macro_dirs]
+		out_cfg[web.multifile]
+	]
+]
+section[
+	@title[output.web5.*]
+	config_table[
+		out_cfg[web5.base]
+		out_cfg[web5.extension]
+		out_cfg[web5.filter_target]
+		out_cfg[web5.layout_dirs]
+		out_cfg[web5.layouts.index]
+		out_cfg[web5.layouts.topic]
+		out_cfg[web5.macro_dirs]
+		out_cfg[web5.multifile]
+	]
+]

data/book/text/extending/bookmarks_headers.glyph

@@ -1,5 +1,3 @@
-section[
-	@title[Bookmarks and Headers]
 	txt[
 The =>[&[yardoc]/Macro|@Glyph::Macro@] class also includes a few methods to check and store bookmarks and headers. Consider for example the following source code for the %>[anchor]:
 	]
@@ -16,6 +14,3 @@ end
 	txt[
 The @bookmark?@ method can be used to check the existance of a particular ID within the whole document, while the @bookmark@ method is used to store bookmark IDs and titles. In a similar way, you can use @header?@ and @header@ methods to check the existance of headers within the documents or store new ones.
 	]
-]
-
-

data/book/text/extending/command.glyph

@@ -0,0 +1,56 @@
+txt[
+Glyph relies on =>[http://davetron5000.github.com/gli/|GLI] for defining commands. This useful library provides a high-level framework for creating command-line interface similar to =>[http://git-scm.com/|Git], its DSL takes care of pretty much everything, from managing command line arguments and options to providing an interactive help system.
+]
+section[
+	@title[Creating a 'glyph generate' command]
+	txt[
+Consider the custom task defined in =>[#custom_generate_task]. Creating a custom command to call it is fairly straightforward. 
+
+First of all, create a @lib/commands@ folder in your project directory. Then, create a @.rb@ file within it, e.g. @commands.rake@.
+ 
+Finally, here's the source of the command:
+	]
+	highlight[=ruby|
+GLI.desc 'Generates a specific file required for Glyph releases'
+arg_name "file_name"
+command :generate do \|c\|
+  c.action do \|global_options,options,args\|
+    if args.blank? then
+      raise RuntimeError, "You must specify a file to generate"
+    else
+      Glyph.run 'custom:generate', args[0]
+    end
+  end
+end
+	=]
+	txt[
+That's it. If you try to run @glyph help@ within your project directory, notice that there's a new entry for the generate command:
+	]
+	highlight[html|
+$ glyph help
+=====================================
+Glyph v\.%[Glyph::VERSION]
+=====================================
+usage: glyph command \[options\]
+
+Options:
+    -d, --debug - Enable debugging
+
+Commands:
+    add      - Add a new text file to the project
+    compile  - Compile the project
+    config   - Get/set configuration settings
+    generate - Generates a specific file required for Glyph releases
+    help     - Shows list of commands or help for one command
+    init     - Create a new Glyph project
+    outline  - Display the document outline
+    stats    - Display statistics
+    todo     - Display all project TODO items
+	]
+	p[You can now run the Glyph command as expected:]
+	highlight[=html|
+$ glyph -d generate changelog
+-- Generating CHANGELOG...
+-- Done.
+	=]
+]

data/book/text/extending/commands_tasks.glyph

@@ -0,0 +1,39 @@
+txt[
+In most cases, you can extend Glyph just by creating your own =>[#macro_def|custom macros]. In some cases though, you may want to further customize Glyph to fit the needs of your project, in terms of creating =>[#custom_command|custom commands] and =>[#custom_task|custom tasks].
+
+Glyph's modular architecture (and the Ruby language itself) lets you to add _arbitrary_ functionality to its core, simply by creating a few Ruby files and putting them in the right places.
+]
+section[
+	@title[How Commands and Tasks work]
+	@id[cmd_tasks_arch]
+	txt[
+Before creating custom Glyph commands and tasks, you should have a basic understanding on how they work, and which commands -- or better, which tasks -- are already available.
+
+The following diagram outlines the relationships between commands and tasks:
+	]
+	figure[glyph/commands_tasks.png|Glyph default commands and tasks]
+	txt[
+As you can see:
+* All commands call at at least one task.
+* There are several task inter-dependencies spanning across three main Rake namespaces:
+** @project:@ -- used for tasks affecting only the physical structure of the Glyph project.
+** @load:@ -- used to load all kinds of files.
+** @generate:@ -- used to generate files or copy files from source to output directories 
+	]
+	box[Example|
+		txt[
+Suppose you want to generate a PDF file by issuing the @glyph compile -f pdf@ command. Under the hood, Glyph calls the following tasks:
+# @load:config@ -- Load the configuration files
+# @load:tasks@  -- Load custom tasks (if any)
+# @load:commands@ -- Load custom commands (if any)
+# @load:snippets@ -- Load snippets from the @snippet.yml@ file
+# @load:macros@ -- Load macros
+# @load:all@ -- Dummy task used to call the previous ones
+# @generate:document@ -- Parse, analyze and finalize the Glyph document
+# @generate:images@ -- Copy images to the output directory (if any)
+# @generate:styles@ -- Copy stylesheets to the output directory (if necessary)
+# @generate:html@ -- Generate a standalone HTML file
+# @generate:pdf@ -- Generate a PDF file from a standalone HTML file
+		]
+	]
+]