glyph 0.1.0

data/book/text/ref_macros.textile

@@ -0,0 +1,256 @@
+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

@@ -0,0 +1,118 @@
+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]

data/config.yml

@@ -0,0 +1,63 @@
+:document:
+  :source: 'document.glyph'
+  :author: ""
+  :title: ""
+  :filename: ""
+  :output: ""
+  :output_targets: [:html, :pdf]
+:structure:
+  :hidden:
+    - :imprint
+    - :dedication
+    - :inspiration
+    - :postscript
+    - :colophon
+    - :promotion
+  :special:
+    - :preface
+    - :foreword
+    - :introduction
+    - :acknowledgement
+    - :prologue
+    - :epilogue
+    - :addendum
+    - :glossary
+    - :bibliography
+    - :references
+    - :index
+    - :lot
+    - :lof
+  :frontmatter:
+    - :preface
+    - :imprint
+    - :dedication
+    - :inspiration
+    - :foreword
+    - :introduction
+    - :acknowledgement
+    - :prologue
+  :bodymatter:
+    - :volume
+    - :book
+    - :part
+    - :chapter
+  :backmatter:
+    - :epilogue
+    - :afterword
+    - :postscript
+    - :appendix
+    - :addendum
+    - :glossary
+    - :colophon
+    - :bibliography
+    - :promotion
+    - :references
+    - :index
+    - :lot
+    - :lof
+:pdf_renderer: 'prince'
+:filters:
+  :by_file_extension: true
+  :target: 'html'
+  :redcloth:
+    :restrictions: []

data/document.glyph

@@ -0,0 +1,29 @@
+document[
+  head[style[default.css]]
+  body[
+    titlepage[
+      title[]
+      author[]
+      pubdate[]
+    ]
+    frontmatter[
+      toc[]
+      preface[header[Preface]
+        @[preface.textile]
+      ]
+    ]
+    bodymatter[  
+      chapter[header[Chapter #1]
+        @[chapter_1.textile]
+      ]
+      chapter[header[Chapter #2]
+        @[chapter_2.textile]
+      ]
+    ]
+		backmatter[
+			appendix[header[Appendix A]
+				@[appendix_a.textile]
+			]
+		]
+  ]
+]