glyph 0.1.0 → 0.2.0

data/book/styles/default.css

@@ -1,190 +0,0 @@
-* {
-	border: none;
-	font-family: inherit;
-	font-size: 100%;
-	font-style: inherit;
-	margin: 0;
-	padding: 0;
-}
-html {
-	background: #fff;
-}
-p, ol, ul {
-	margin: 0.3em 0;
-}
-table {
-	border-collapse: collapse;
-	border-spacing: 0;
-	margin: auto;
-	margin-top: 1em;
-}
-body {
-	line-height: 1.2em;
-	margin: 0;
-	padding: 0;
-	padding: 0 1em;
-	text-align: justify;
-}
-
-/* Structure */
-.titlepage {
-	margin: auto;
-	text-align: center;
-}
-.title, h1 {
-	font-size: 2.5em;
-	font-weight: bold;
-	line-height: 1.5em;
-	margin-bottom: 0.2em;
-}
-.titlepage h2 {
-	font-size: 1.1em;
-	font-style: italic;
-	font-weight: bold;
-	line-height: 1.2em;
-	margin-bottom: 0.5em;
-	prince-bookmark-level: none;
-}
-.author {
-	font-size: 1em;
-}
-.pubdate {
-	font-size: 0.8em;
-}
-li {
-	list-style-type: square;
-	margin: 0.4em 0;
-	margin-left: 1.5em;
-}
-ol li{
-	list-style-type: decimal;
-}
-img {
-	margin: 0 5px;
-	padding: 2px;
-}
-dt {
-	font-weight: bold;
-	margin-top: 1em;
-}
-dd {
-	font-style: italic;
-}
-p {
-	margin: 1em 0;
-}
-ol.toc {
-	margin-left: 1.5em;
-}
-.toc > li[class] {
-	font-weight: bold;
-}
-.toc li {
-	list-style-type: none;
-	margin-left: 0;
-}
-.toc li a, .toc li a:hover {
-	color: #000;
-}
-table {
-	border: 1px solid #E6E6E6;
-}
-th {
-	background: #EEE;
-}
-tr, td, th {
-	padding: 5px;
-}
-td, tr {
-	border: 1px solid #E6E6E6;
-}
-sup {
-	font-size: 0.7em;
-	font-weight: bold;
-	margin-left: -0.4em;
-}
-/* BLOCKS */
-.center {
-	margin: auto;
-	text-align: center;
-}
-.left {
-	margin: auto;
-	text-align: left;
-}
-.right {
-	margin: auto;
-	text-align: center;
-}
-
-.note, 
-.important, 
-.tip, 
-.caution, 
-.box {
-	border: 1px solid #E6E6E6;
-	display: block;
-	margin: 0.5em auto;
-	padding: 0 0.5em;
-	width: 600px;
-	background: #EEE;
-	color: #1F1F1F;
-}
-.note-title {
-	font-weight: bold;
-	margin-right: 1em;
-}
-.box-title {
-	display: block;
-	text-align: center;
-	font-weight: bold;
-}
-.code {
-	margin: 1em auto;
-	padding: 0.5em;
-	width: 600px;
-}
-/* TEXT */
-body {
-	color: #000;
-	font-size: 1em;
-}
-h2 {
-	display: block;
-	font-size: 2em;
-	font-weight: bold;
-	margin: 3em 0 1em 0;
-}
-h3 {
-	font-size: 1.6em;
-	font-weight: normal;
-	margin: 3em 0 1em 0;
-}
-h4 {
-	font-size: 1.3em;
-	font-weight: normal;
-	margin: 3em 0 1em 0;
-}
-em {
-	font-style: italic;
-}
-a {
-	color: #8A1513;
-	text-decoration: none;
-}
-a:hover {
-	color: #CF282D;
-}
-code {
-	font-size: 0.75em;
-}
-
-/* FONTS */
-body {
-	font-family: "Book Antiqua", "Times New Roman", "Serif";
-}
-
-code {
-	font-family: "Droid Sans Mono", "Consolas", "Monaco", "Courier", "Monospace";
-}
-

data/book/text/authoring.textile

@@ -1,351 +0,0 @@
-section[header[Text Editing]
-
-One of the aims of Glyph is streamlining text editing. Glyph accomplishes this through its own macro language that can be used in conjunction with &[markups].
-
-section[header[Introducing &[macros]]
-
-By now you probably figured out what a macro looks like: it's an identifier of some kind that wraps a value or parameters within square brackets. More specifically:
-* The macro identifier can contain _any_ character except for: @\[@, @\]@, @\\@, @\|@ or spaces.
-* The delimiters can be either @\[@ and @\]@ or @\[=@ and @=\]@ (\.fmi[differences between delimiters|#esc_quot]). 
-* The value can be anything, even other macros. If a macro supports more than one parameter, they must be separated with @\|@. For example, the @link@ (@=>@) macro can take an optional second parameter for the link text: @\..[==>[#link_id|This is the link text]=]@.
-
-todo[Add info about macro aliases]
-
-]
-
-section[header[Escaping and Quoting|esc_quot]
-
-Glyph doesn't require any special control characters like LaTeX, and its macro syntax is very straightforward and liberal. This however comes with a price: because square brackets are used as delimiters, you must escape any square bracket in your text with a backslash. That's not _too_ bad if you think about it, unless you're writing programming code: in that case, escaping every single square bracket can be painful.
-
-If a portion of your text contains an excessive amount of square brackets, you may consider using the @escape@ macro (or better, its alias @.@) with @\[=@ and @=\]@ as delimiters. By itself, the escape macro doesn't do anything: it just evaluates to its contents, but the special delimiters act as a quote for any square bracket within them. As a consequence, any macro within @\[=@ and @=\]@ will _not_ be evaluated.
-
-You can use the quoting delimiters with _any_ macro identifier. Obviously, using them as delimiters for things like @section@ macros may not be a good idea, but they should really be mandatory with the @code@ macro, like this:
-
-code[=
-code\[=
-section[header[A section]
-
-This is a section.
-
-  section[header[A nested section]
-This is another section.
-  ]
-]
-=\]
-=]
-
-note[Although quoting delimiters allow you to use square brackets without escaping them, you must still escape them if you want to escape quoting delimiter themselves.]
-
-Besides square brackets, there are other characters that must or can be escaped with backslashes, as shown in the following table
-
-table[
-	tr[
-		th[Escape Sequence]
-		th[Evaluates to...]
-		th[Notes]
-	]
-	tr[
-		td[@\\\[@]
-		td[@\[@]
-		td[&[sq_esc]]
-	]
-	tr[
-		td[@\\\]@]
-		td[@\]@]
-		td[&[sq_esc]]
-	]
-	tr[
-		td[@\\\\@]
-		td[@\\@]
-		td[Backslashes do not have to be escaped by default, but an escaped backslash will evaluate to itself.]
-	]
-	tr[
-		td[@\\\=@]
-		td[@=@]
-		td[Equal signs do not have to be escaped by default, but an escaped equal sign will evaluate to iself.]
-	]
-	tr[
-		td[@\\\|@]
-		td[@\|@]
-		td[Pipes must be escaped (even within quoting macros) unless they are used to separate two or more macro parameters.]
-	]
-	tr[
-		td[@\\\..@]
-		td[]
-		td[An escaped dot evaluates to nothing. Useful to separate macro identifiers from other characters:
-@\..[= _\.=>[#link|This is an emphasized link]_ =]@
-		]
-	]
-]
-
-] --[End section]
-
-section[header[Sections and Headers|sec_head]
-
-Glyph documents are normally organized as a hierarchical tree of nested chapters, appendixes, sections, etc. To define a section, use the @section@ macro, like so:
-
-code[=
-section[
-  header[Section #1]
-
-Write the section contents here...
-
-  section[
-    header[Section #2]
-
-This section is nested into the previous one.
-
-  ] --[End of Section #2]
-] --[End of Section #1]
-=]
-
-This example defines two nested sections, each with its own header. The header is _mandatory_: it will be displayed at the start of the section and in the Table of Contents. 
-
-Note an important difference from HTML: there is no explicit level for the headers, as it will be determined at runtime when the document is compiled, based on how sections are nested. The previous code snippet (taken as it is), for example, will be transformed into the following HTML code:
-
-<notextile>
-code[=
-<div class="section">
-  <h2>Section #1</h2>
-  <p>Write the section contents here...</p>
-  <div class="section">
-    <h3>Section #2</h3>
-    <p>This section is nested in the previous one</p>
-  </div>
-</div>
-=]
-</notextile>
-
-By default, in Glyph the first header level is _2_, so the two headers are rendered as @h2@ and @h3@, respectively (@--\[...\]@ macros are _comments_, therefore they are not included in the final output).
-
-There are _a lot_ of macros that can be used in the same way as @section@, one for each element of =>[http://en.wikipedia.org/wiki/Book_design|Book Design]. Each one of them is a simple wrapper for a @<div>@ tag with a class set to its name.
-
-The following table lists the identifiers of all section-like macros, divided according to the part of the book they should be placed in:
-
-table[
-	tr[
-		td[*Frontmatter*]
-		td[@imprint@ ^†^, @dedication@ ^†^, @inspiration@ ^†^, @foreword@ ^‡^, @introduction@ ^‡^, @acknowledgement@ ^‡^, @prologue@ ^‡^, @toc@ ^*^]
-	]
-	tr[
-		td[*Bodymatter*]
-		td[@volume@, @book@, @part@, @chapter@]
-	]
-	tr[
-		td[*Backmatter*]
-		td[@epilogue@ ^‡^, @afterword@ ^‡^, @postscript@ ^†^, @appendix@, @addendum@ ^‡^, @glossary@ ^**‡^, @colophon@ ^†^, @bibliography@ ^**‡^, @promotion@ ^†^, @references@ ^**‡^, @index@ ^**‡^, @lot@ ^**‡^, @lof@ ^**‡^]
-	]
-]
-
-<notextile>*</notextile>: The @toc@ macro is to generate the Table of Contents automatically, and it must be used with no contents (@toc\[\]@).
-
-<notextile>**</notextile>: This macro is likely to be extended in future versions to generate/aggregate content automatically.
- 
-†: This section is not listed in the Table of Contents.
-
-‡: Any subsection of this section is not listed in the Table of Contents.
-
-note[@frontmatter@, @bodymatter@ and @backmatter@ are also valid (and mandatory!) macro identifiers, typically already included in the default @document.glyph@ file of every project.]
-
-] --[End section]
-
-section[header[Including Files and Snippets]
-
-If you're authoring a user manual, a long article or a book, writing everything inside a single file (@document.glyph@) may not be optimal. For this reason, Glyph provides an @include@ macro (aliased by codeph[@]) that can be used to include the contents of any file within the @text/@ directory:
-
-codeph[=@[introduction.textile]=]
-
-The macro above loads the contents of the @introduction.textile@ file, that can be stored _anywhere_ within the @text/@ directory.
-
-note[Unlike with =>[img_fig|image and figures] that must be included with their _relative_ path to the @images/@ folder, you must not specify a relative path when including text files. This is due to the fact that images are copied _as they are_ in the @output/<format>/images/@ directory and they have to be linked from the output file.
-
-A possible downside of this behavior is that file names must be unique within the entire @text/@ directory (or any of its subdirectories)]
-
-When including a text file, by default an input filter macro is applied to its contents based on the file extension used:
-* @.textile@ &rarr; @textile@
-* @.markdown@ or @.md@ &rarr; @markdown@
-
-tip[You can override this behavior by setting the @filters.by_file_extensions@ configuration setting to @false@, like this:
-
-@glyph config filters.by_file_extensions false@]
-
-While including the context of an entire file is definitely a useful feature for content reuse, sometimes it can be an overkill. What if, for example, you just want to reuse a short procedure or even a sentence? In this case, you may want to consider using a _snippet_ instead.
-
-Snippets are text strings saved in YAML format in the @snippets.yml@ file. They can be included anywhere in your document using the @snippet@ macro (or its alias @&@). 
-
-box[Example|
-Consider the following @snippets.yml@ file:
-code[=
---- 
-:glang: Glyph Language
-:macros: Glyph Macros
-:sq_esc: \|-
-  Square brackets must be escaped 
-  unless used as macro delimiters or within a quoting macro.
-:markups: Textile or Markdown
-:test: \|-
-  This is a 
-  Test snippet
-=]
-You can use codeph[=&[markups]=] anywhere in your document instead of having to type "Textile or Markdown" every time. Additionally, later on you can change the value of the @markups@ snippets only in the @snippets.yml@ file to change it everywhere else in the document.
-] --[End Example]
-tip[
-Snippets (or any other macro) can be nested within other snippets. Glyph takes care of checking if you nested snippets or macros mutually and warns you if necessary.
-]
-] --[End Section]
-
-
-section[header[Links and Bookmarks|links]
-
-Lightweight markups let you create internal and external links in a very easy way, and you can still do so in Glyph. However, if you do so:
-* There is no built-in way to check if they are valid
-* There is no built-in way to determine the title of a link automatically
-
-If you care about link validation and you want to save some keystrokes, then you should use the following markup-agnostic &[macros]:
-* @link@ (aliased to @=>@) -- to create internal and external links.
-* @anchor@ (aliased to @#@) -- to create named anchors (bookmarks) within your document.
-
-box[Example|
-
-&[gcode]
-
-code[=
-This is a link to =>[#test].
-
-...
-
-This is =>[#wrong].
-
-This is a #[test\|test anchor].
-=]
-
-&[htmlcode]
-
-<notextile>
-code[=
-<p>This is a link to <a href="#test">test anchor</a>.</p>
-<p>...</p>
-<p>This is <a href="#wrong">#wrong</a>.</p>
-<p>This is a <a id="test">test anchor</a>.</p>
-=]
-</notextile>
-
-Additionally, the following warning message is displayed when =>[#compile|compiling]:
-
-<notextile>
-code[=
-warning: Bookmark 'wrong' does not exist
- -> source: @: aurhoting.textile
- -> path: document/body/bodymatter/chapter/@/textile/section/section/box/=>
-=]
-</notextile>
-
-]
-
-Basically, if you use the @=>@ and @#@ macros, Glyph makes sure that:
-* All links point to valid anchors within the document (regardless if the anchors are before or after the link, in snippets or included files).
-* There are no duplicate anchors within the documents.
-* If no title is specified as second parameter for the @=>@ macro, the anchor's title is used as such.
-
-Besides using the @#@ macro, you can also create an anchor for a header by passing an extra parameter to the @header@ macro, like this: codeph[=header[Header Title|my_anchor]=].
-
-note[
-At present, link validation and automatic title retrieval only works with internal links (i.e. the check occurs if the first parameter of the @=>@ macro starts with a @#@). In the future, the macro could be extended to support external links as well. 
-]
-
-] --[End section]
-
-section[header[Evaluating Ruby code and Configuration Settings]
-
-&[glang] is not a full-blown programming language, as it does not provide control flow or variables, for example. 
-However, it is possible to evaluate simple ruby code snippets using the @ruby@ macro (aliased to @%@), like this:
-* codeph[=%[2 + 2]=] &rarr; 4
-* codeph[=%[Time.now]=] &rarr; %[Time.now]
-* codeph[=%[Glyph::VERSION]=] &rarr; %[Glyph::VERSION]
-
-The scope for the code evaluation is the Kernel module, (with all inclusions required by Glyph itself). 
-
-Although it is possible to retrieve Glyph configuration settings in this way (e.g. codeph[=%[cfg('document.author')]=]), the @config@ macro (aliased to @$@) makes things slightly simpler (e.g. codeph[=$[document.author]=]).
-
-]
-
-section[header[Images and Figures|img_fig]
-
-In a similar way to =>[#links|links], if you want you can include images and figures using &[markups]. If you want additional features, you can use the @img@ and @fig@ macros, as shown in the following example:
-
-box[Example|
-
-&[gcode]
-
-code[=
-img[glyph.svg\|20%\|20%]
-
-fig[example.png\|An example figure.]
-=]
-
-&[htmlcode]
-
-<notextile>
-code[=
-
-<img src="images/glyph.svg" width="20%" height="20%" alt="-" />
-
-<div class="figure">
-  <img src="images/example.png" alt="-"/>
-  <div class="caption">An example figure.</div>
-</div>
-=]
-</notextile>
-
-]
-
-note[
-In future releases, figures will be numbered automatically and included in a _List of Figures_ section.
-]
-
-] --[End of section]
-
-
-] --[End of Text Editing section]
-
-section[header[Compiling your project|compile]
-
-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 formats are likely to be supported.
-
-section[header[Adding Stylesheets|stylesheets]
-
-Currently, Glyph does not provide any native way to format text and pages. The reason is that there's absolutely no need for that: CSS does the job just fine. In particular, CSS 3 offers specific attributes and elements that can be used specifically for paginated documents. That's no replacement for LaTeX by any means, but it is enough if you're not looking for advanced typographical features.
-
-You can embed CSS files using the @style@ macro, like this:
-
-code[= style[default.css] =]
-
-In this case, the @style@ macro looks for a @default.css@ file in the @/styles@ folder of your Glyph project and embeds it within a @<style>@ tag. If you supply a file with a @.sass@ extension, it will interpret it as a Sass file and convert it to CSS automatically (if the _Haml_ gem is installed).
-
-]
-
-section[header[HTML output]
-
-To compile a Glyph project to an HTML document, use the @glyph compile@ command within your Glyph project folder. Glyph parses the @document.glyph@ file (and all included files and snippets); if no errors are found, Glyph creates an HTML document in the @/output/html@ folder. The name of the HTML file can be set in the configuration (@document.filename@ setting).
-
-If you don't want to compile the whole project, you can specify a different source, like this:
-
-code[= glyph compile -s myfile.textile =]
-
-]
-
-section[header[PDF Output]
-
-To generate a PDF document, you must specify @pdf@ as format, like this:
-
-code[= glyph compile -f pdf =]
-
-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.strip] has been successfully tested with Prince v7.0, and the PDF version of this very book was generated with it.]
-
-]
-
-]
-
-