glyph 0.1.0 → 0.2.0

data/book/text/extending.textile

@@ -1,148 +0,0 @@
-Glyph was created wih extensibility in mind. You can freely extend &[glang] by creating or overriding macros, to do whatever you like. Macro definitions are written in pure Ruby code and placed in @.rb@ files within the @/lib/macros@ folder of your project.
-
-section[header[Anatomy of a Macro]
-
-This is the source code of a fairly simple macro used to format a note :
-
-<notextile>
-code[=
-macro :note do
-  %{<div class="#{@name}"><span class="note-title">#{@name.to_s.capitalize}</span>#{@value}
-
-    </div>}
-end 
-=]
-</notextile>
-
-The @macro@ method takes a single Symbol or String parameter, corresponding to the name of the macro. In this case, the entire block (or _body_ of the macro) is a String corresponding to what we want the macro to evaluate to: a @<div>@ tag containing a note. 
-
-The body of the macro is evaluated in the context of the =>[http://yardoc.org/docs/h3rald-glyph/Glyph/Macro|Glyph::Macro] class, therefore its instance variables (like codeph[@name] or codeph[@value]) can be used directly.
-
-box[Why using codeph[@name] instead of just "note"?|
-For the @note@ macro, it absolutely makes no difference. However, by using codeph[@name] it is possible to re-use the same code for the @tip@, @important@ and @caution@ macros as well, which are in fact only aliases of the @note@ macro:
-
-@macro_alias :important => :note@
-@macro_alias :tip => :note@
-@macro_alias :caution => :note@
-] --[End box]
-
-The following table lists all the instance variables that can be used inside macros:
-
-table[
-  tr[
-    th[Variable]
-    th[Description]
-  ]
-  tr[
-    td[codeph[@node]]
-    td[A =>[http://yardoc.org/docs/h3rald-glyph/Node|Node] containing information about the macro, within the document syntax tree. Useful for accessing parent and child macros, and the current =>[http://yardoc.org/docs/h3rald-glyph/Glyph/Document|document]. Normally, macro nodes contain the following keys:
-- @:name@, the name of the macro
-- @:value@, the value (i.e. the contents, within the delimiters) of the macro
-- @:source@, a String identifying the source of the macro (a file, a snippet, etc.) 
-- @:document@, the parsed document tree
-
-Note that the first three keys can also be accessed via instance variables.]
-  ]
-  tr[
-    td[codeph[@name]]
-    td[The name of the macro]
-  ]
-  tr[
-    td[codeph[@value]]
-    td[The full contents (including parameters and nested macros) within the macro delimiters.]
-  ]
-  tr[
-    td[codeph[@source]]
-    td[A String identifying the source of the macro (a file, a snippet, etc.) ]
-  ]
-  tr[
-    td[codeph[@params]]
-    td[The parameters passed to the macro. In other words, the value of the macro split by pipes (@|@).]
-  ]
-] --[End Table]
-
-]
-
-section[header[Bookmarks and Headers]
-
-The =>[http://yardoc.org/docs/h3rald-glyph/Glyph/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@ macro:
-
-<notextile>
-code[=
-macro :anchor do 
-  ident, title = @params
-  macro_error "Bookmark '#{ident}' already exists" if bookmark? ident
-  bookmark :id => ident, :title => title
-  %{<a id="#{ident}">#{title}</a>}
-end
-=] </notextile>
-
-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.
-
-]
-
-section[header[Using Placeholders]
-
-Sometimes you may need to access some data that will not be available until the entire document has been fully parsed and analyzed. For example, in order to be able to validate internal links, it is necessary to know in advance if the bookmark ID referenced in the link exists or not, either before (that's easy) or even _after_ the location of the link. 
-
-Here's the source code of the @link@ macro:
-
-<notextile>
-code[=
-macro :link do
-  href, title = @params
-  if href.match /^#/ then
-    anchor = href.gsub(/^#/, '').to_sym
-    bmk = bookmark? anchor
-    if bmk then
-      title ||= bmk[:title]
-    else
-      plac = placeholder do |document|
-        macro_error "Bookmark '#{anchor}' does not exist" unless document.bookmarks[anchor] 
-        document.bookmarks[anchor][:title]
-      end
-      title ||= plac
-    end
-  end
-  title ||= href
-  %{<a href="#{href}">#{title}</a>}
-end
-=] </notextile>
-
-If there's already a bookmark stored in the current document, then it is possible to retrieve its title and use it as link text. Otherwise, it is necessary to wait until the entire document has been fully processed and then check if the bookmark exists. To do so, use the @placeholder@ method. When called, this method returns an unique placeholder, which is then substituted with the value of the block, right before the document is finalized.
-
-Within the @placeholder@ block, the @document@ parameter is, by all means, the fully analyzed document.
-]
-
-section[header[Interpreting Glyph Code]
-
-What if you need to evaluate some Glyph code _within_ a macro? Say for example you want to transform a parameter in a link, and you want to make sure that link gets validated exactly like the others, in this case, you can use the @interpret@ method, as follows:
-
-<notextile>
-code[=
-macro :fmi do
-  topic, href = @params
-  link = placeholder do |document| 
-    interpret "link[#{href}]"
-  end
-  %{<span class="fmi">for more information on #{topic}, see #{link}</span>}
-end
-=] </notextile>
-
-When the @interpreter@ method is called, the following happens:
-# A new Glyph document is created from the String passed to the method.
-# The bookmarks, headers and placeholders are passed from the main document to the new one. Because they are stored in Arrays or Hashes, they are passed by reference, so for example any new bookmark stored in the new document will also become available in the main document.
-# Any macro included in the String is evaluated, and the resulting text is returned by the method. Note that this new document does not get finalized: in other words, placeholders will be left as they are, and they'll eventually be replaced when _the main document_ is finalized.
-
-]
-
-section[header[Further Reading]
-
-For more examples on how to create more complex macros, have a look at the =>[http://github.com/h3rald/glyph/tree/master/macros/|source code] of the existing ones.
-
-To gain a deeper understanding on how macros are executed, have a look at the following Glyph classes:
-* =>[http://yardoc.org/docs/h3rald-glyph/Glyph/Macro|Glyph::Macro]
-* =>[http://yardoc.org/docs/h3rald-glyph/Glyph/Interpreter|Glyph::Interpreter]
-* =>[http://yardoc.org/docs/h3rald-glyph/Glyph/Document|Glyph::Document]
-* =>[http://yardoc.org/docs/h3rald-glyph/Glyph/Node|Node]
-]

data/book/text/ref_macros.textile

@@ -1,256 +0,0 @@
-section[header[Common Macros]
-
-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[todo|
-Saves the value as a TODO item, which can be printed using the #>[todo].
-
-example[todo\[Remember to do this.\]]
-]
-
-ref_macro[snippet|
-Evaluates to the snippet referenced by its value.
-
-aliases[&]
-example[&\[glang\]]
-]
-
-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[ruby|
-Evaluates its value as Ruby code (using @Kernel#instance_eval@).
-
-aliases[%]
-examples[
-%\[Time.now\]
-%\[Glyph::VERSION\]
-]
-]
-
-ref_macro[config|
-Evaluates to the configuration setting referenced by its value.
-
-aliases[$]
-example[$\[document.author\]]
-]
-
-ref_macro[escape|
-Evaluates to its value. Commonly used with the escaping delimiters @\[=@ and @=\]@.
-
-aliases[.]
-example[.\[=Macros are escaped here =>\[#test\].=\]]
-]
-
-] --[End common macros]
-
-section[header[Filter Macros|f_macros]
-
-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*.\]]
-]
-
-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.\]]
-]
-
-] --[End filter macros]
-
-section[header[Block Macros]
-
-ref_macro[note|
-Creates a note @div@ containing the value.
-
-aliases[important, caution, tip]
-example[note\[This is a note.\]]
-]
-
-ref_macro[box|
-Creates a titled box @div@.
-
-*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].
-
-*Example:*
-
-code[
-code\[
-  def hello
-    puts "Hello World"
-  end
-\]
-]
-
-]
-
-ref_macro[title|
-Renders the title of the document (based on the $>[document.title]) within a @h1@ tag.
-
-example[title\[\]]
-]
-
-ref_macro[subtitle|
-Renders the subtitle of the document (based on the $>[document.subtitle]) within a @h2@ tag.
-
-example[subtitle\[\]]
-]
-
-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[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[fig|
-Includes an image in the document, with an optional caption.
-
-examples[
-fig\[diagram.png\]
-fig\[graph.png\|Monthly pageviews\]
-]
-]
-
-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[tr|See =>[#m_table].]
-ref_macro[th|See =>[#m_table].]
-ref_macro[td|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[link|
-Creates an hyperlink (\.fmi[creating links|#links]).
-
-aliases[=>]
-examples[
-=>\[#introduction\]
-=>\[#troub\|Troubleshooting\]
-=>\[http://www.h3rald.com\|H3RALD.com\]
-]
-]
-
-ref_macro[codeph|
-Wraps the value in a @code@ tag.
-
-example[codeph\[Kernel.instance_eval\]]
-
-]
-
-ref_macro[fmi|
-Creates a _For More Information_ link (for an example usage, see the %>[link]).
-
-example[fmi\[creating links\|#links\]]
-]
-
-] --[End inline macros]
-
-section[header[Structure Macros]
-
-ref_macro[div|
-Creates a @div@ tag.
-
-*Aliases:* todo[List div aliases]
-]
-
-ref_macro[header|
-Creates an @h2@, @h3@, @h4@, etc. header (\.fmi[using headers|#sec_head]).
-
-examples[
-header\[Introduction\]
-header\[Getting Started\|gs\]
-]
-]
-
-ref_macro[document|
-The root macro used in every Glyph document.
-]
-
-ref_macro[body|
-Creates a @body@ tag.
-]
-
-ref_macro[head|
-Creates a @head@ tag, pre-populated with @title@ and author/copyright meta tags.
-]
-
-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]

data/book/text/troubleshooting.textile

@@ -1,118 +0,0 @@
-This chapter lists the most common error messages that can be returned when running a Glyph command. It does not aim to be an exhaustive list, especially if you =>[#extending|extended] Glyph by creating your own macros.
-
-section[header[Generic Errors]
-
-error_table[
-ref_error[Document contains syntax errors|
-This error is returned if the document was not parsed because of one or more syntax error. 
-
-*At present, no indication on the exact location of the error(s) is provided*, so the only way to determine what went wrong is to try compiling a single file at a time (@glyph compile -s source-file@), and examine more closely the source of the files that do not compile.
-]
-ref_error[Invalid alias: macro '_macro-name_' already exists|
-The alias name supplied to the @macro_alias@ method has already been used for another macro or alias.
-]
-ref_error[Undefined macro '_macro-name_'|
-The document contains a macro that does not exist, i.e. it is not a standard or used-defined =>[#macro_ref|Glyph macro or alias].
-]
-ref_error[An error occurred when generating _file-name_.pdf|
-Returned if Prince could not generate the PDF file or if Prince is not installed. Normally, Prince provides additional details on the specific error(s).
-]
-ref_error[Glyph cannot generate PDF. Please specify a valid pdf_renderer setting|
-Returned if the @pdf_renderer@ setting has not be set to a valid PDF renderer. Currently, the only supported value for this setting is @prince@.
-]
-ref_error[The current directory is not a valid Glyph project|
-Returned if a glyph command was executed outside a valid glyph project directory.
-]
-ref_error[Invalid snippet file|
-The @snippet.yml@ file contains invalid data. Most likely, it does not evaluate to a Ruby Hash.
-]
-ref_error[Directory '_directory-name_' is not empty|
-Returned when executing @glyph init@ in a directory that is not empty.
-]
-ref_error[File '_file-name_' already exists|
-Returned if the name of an existing file was specified as a parameter for the @glyph add@ command.
-]
-]
-] --[End Generic Errors]
-
-
-
-section[header[Command Errors]
-
-error_table[
-
-ref_error[Please specify a file name|
-No file name was specified for the @glyph add@ command.
-]
-
-ref_error[Output target not specified|
-Returned if no target was specified for the @glyph compile@ command _and_ if the @document.output@ configuration setting is not set.
-]
-
-ref_error[Unknown output target '_target-name_'|
-An unsupported output target was specified for the @glyph compile@ command. Only the following output targets are supported:
-- @html@
-- @pdf@
-]
-
-ref_error[Too few/too many arguments|
-Returned if the @glyph config@ command was used with no arguments or more than two arguments respectively.
-]
-
-ref_error[Unknown setting '_setting-name_'|
-The name of an unknown setting was specified for the @glyph config@ command.
-]
-]
-] --[End Command Errors]
-
-
-
-section[header[Macro Errors]
-
-The following errors are displayed in the form:
-
-_macro-path_ _message_
-
-Where:
-* _macro-path_ is the full path to the macro that returned the error, within the document syntax tree, e.g. @document/body/bodymatter/chapter/section/header/&@ if the error occurrent in a snippet within the header of a section in the @bodymatter@ part of the document.
-* _message_ is the error message.
-
-error_table[
-
-ref_error[Mutual inclusion|
-This error is returned if a catch-22 situation occurs with macro inclusion, for example if the body of a snippet includes a reference to the same snippet.
-]
-ref_error[Snippet '_snippet-id_' does not exist|
-Returned by the %>[snippet] if an invalid snippet was supplied.
-]
-ref_error[File '_file-name_' not found|
-Returned by the %>[include] if an invalid file was supplied.
-]
-ref_error[Filter macro '_macro-name_' not found|
-Returned by the %>[include] macro if the @filters.by_file_extension@ setting is set to @true@ but the file extension of the included file is not recognized as a filter macro.
-]
-ref_error[RedCloth gem not installed. Please run: gem insall RedCloth|
-Returned by the %>[textile] if the RedCloth gem is not installed.
-]
-ref_error[No MarkDown converter installed. Please run: gem insall bluecloth|
-Returned by the %>[markdown] if no valid Markup converter gem is installed. 
-
-Glyph checks for: BlueCloth, Maruku, Kramdown and RDiscount.
-]
-ref_error[Image/Figure not found|
-Retured by the %>[img] or the %>[fig] respectively, if the specified image file could not be found within the @images/@ folder.
-]
-ref_error[Bookmark '_bookmark-name_' already exists|
-Returned by the %>[anchor] or by the %>[header] if the anchor ID supplied as parameter has already been used in the document.
-]
-ref_error[Bookmark '_bookmark-name_' already exists|
-Returned by the %>[link] if the anchor ID supplied as parameter has not been used in the document.
-]
-ref_error[Stylesheet '_file-name_' not found|
-Returned by the %>[style] if the .css or .sass file supplied as parameter was not found in the @styles/@ directory.
-]
-ref_error[Haml is not installed. Please run: gem install haml|
-Returned by the %>[style] macro if a .sass file was passed as parameter but the Haml gem is not installed.
-]
-]
-] --[End Macro Errors]