RubyGems - newstile - Versions diffs - 1.0.1 - Mend

newstile 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (405) hide show

data/doc/default.template ADDED

@@ -0,0 +1,80 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="{lang:}" lang="{lang:}">
+  <head>
+    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
+    <meta name="author" content="Thomas Leitner" />
+    <meta name="copyright" content="2009-2010 Thomas Leitner" />
+    <meta name="description" content="newstile is a fast, pure-Ruby Markdown-superset converter" />
+    <meta name="keywords" content="ruby, newstile, markdown, text markup" />
+    <link href="{relocatable: default.css}" type="text/css" rel="stylesheet" media="screen,projection" />
+    <link href="{relocatable: news.atom}" type="application/atom+xml" rel="alternate" />
+    <script src="http://newstile.rubyforge.org/js/jsMath/easy/load.js" type="text/javascript"></script>
+    <title>{title:} | newstile</title>
+  </head>
+  <body>
+    <div id="fullheader">
+      <div id="header">
+        <h1 id="logo"><a href="{relocatable: /}" title="Homepage">newstile <span class='slogan'>fast, pure-Ruby Markdown-superset converter</span></a></h1>
+      </div>
+      <div id="donation">
+        <form action="https://www.paypal.com/cgi-bin/webscr" method="post">
+          <input type="hidden" name="cmd" value="_s-xclick" />
+          <input type="hidden" name="encrypted" value="-----BEGIN PKCS7-----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-----END PKCS7-----
+" />
+          <input type="image" src="https://www.paypal.com/en_US/i/btn/btn_donate_SM.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!" />
+          <img alt="" border="0" src="https://www.paypal.com/en_US/i/scr/pixel.gif" width="1" height="1" />
+        </form>
+      </div>
+    </div>
+    <div id="fullnav">
+      <div id="nav">
+        {menu: {max_levels: 1, used_nodes: files}}
+      </div>
+    </div>
+    <div id="fullintro">
+      <% if context.content_node.node_info[:page].blocks.has_key?('intro') %>
+      <div id="intro">
+        <div id="intro-in">
+          <webgen:block name="intro" node="first" />
+        </div>
+      </div>
+      <% end %>
+    </div>
+    <div id="container">
+      <div id="sidebar"><div id="sidebar-content">
+        <webgen:block name="sidebar" node="first" notfound="ignore" />
+      </div></div>
+      <div id="main">
+        <webgen:block name="content" />
+        <div class="clear"></div>
+      </div>
+    </div>
+    <div id="footer" class="shadow">
+      <div class="float-left">Copyright © 2009 Thomas Leitner</div>
+      <div class="float-right">Based on a design by <a href="http://www.davidkohout.cz" title="Original template design">David Kohout</a></div>
+    </div>
+    <!-- Start of StatCounter Code -->
+    <script type="text/javascript">
+      var sc_project=4267845;
+      var sc_invisible=1;
+      var sc_partition=46;
+      var sc_click_stat=1;
+      var sc_security="41321455";
+    </script>
+    <script type="text/javascript" src="http://www.statcounter.com/counter/counter_xhtml.js"></script>
+    <noscript><div class="statcounter">
+        <a title="web counter" class="statcounter" href="http://www.statcounter.com/free_hit_counter.html">
+          <img class="statcounter" src="http://c.statcounter.com/4267845/0/41321455/1/" alt="web counter" />
+        </a>
+    </div></noscript>
+    <!-- End of StatCounter Code -->
+  </body>
+</html>

data/doc/documentation.page ADDED

@@ -0,0 +1,72 @@
+---
+title: Documentation
+in_menu: true
+sort_info: 7
+---
+## Overview
+newstile is first and foremost a library for converting text written in a superset of Markdown to
+HTML. However, due to its modular architecture it is able to support additional input and output
+formats. The following input and output formats are currently supported:
+* Input: [newstile](parser/newstile.html) (a superset of Markdown), [html](parser/html.html)
+* Output: [HTML](converter/html.html), [LaTeX](converter/latex.html), [newstile](converter/newstile.html)
+## Usage
+{:ruby: lang='ruby'}
+The newstile package provides two ways for using it:
+* **As a library**
+  newstile uses basically the same API as [RedCloth], [BlueCloth] and [Maruku]:
+      require 'newstile'
+      puts Newstile::Document.new(text).to_html
+  {:ruby}
+  The second parameter to the `new` call is an options hash for (de)activating certain features. For
+  example, to disable automatic header ID generation, you can do the following:
+      puts Newstile::Document.new(text, :auto_ids => false).to_html
+  {:ruby}
+  The default parser used is `newstile`, however, you can select a different one with the `:input`
+  option:
+      puts Newstile::Document.new(text, :input => 'html').to_latex
+  {:ruby}
+  You can also reuse the created document object to produce multiple outputs:
+      doc = Newstile::Document.new(text, :input => 'html')
+      puts doc.to_html
+      puts doc.to_latex
+  {:ruby}
+  More information on how to use or extend newstile can be found in the [API
+  documentation](rdoc/index.html)!
+* **As an application**
+  Together with the library files a binary called `newstile` is shipped which can be used to convert
+  text in any supported format (currently only newstile syntax) to any supported output format (e.g.
+  HTML or LaTeX). It either reads from the files specified as the command line arguments or from the
+  standard input. For example:
+      newstile path/to/newstile/doc/syntax.page
+  The input and output formats as well as all available newstile options are supported through
+  command line switches.
+## Tests
+newstile uses various test suites to verify the correct working of the parsers and converters. For
+more information, have a look at the [tests document](tests.html).
+{include_file: doc/links.markdown}

data/doc/index.page ADDED

@@ -0,0 +1,96 @@
+---
+title: Home
+in_menu: true
+sort_info: 1
+---
+## Overview
+If you want to get started with newstile, have a look at the [installation page](installation.html)
+to see how you can install it on your system. Then look through the
+[documentation](documentation.html) for finding information about how to actually use newstile and
+its parsers/converters. The [syntax](syntax.html) provides a detailed description of the superset of
+Markdown which newstile supports.
+{tikz:: path: overview.png
+img_attr: {style: 'background:transparent'}
+libraries: [mindmap, trees, arrows]
+transparent: true
+resolution: 300 100
+opts: |
+  mindmap, concept color=black, text=white,
+  root concept/.append style={font=\Large},
+  level 1 concept/.append style={font=\Large, minimum size=2.6cm},
+  level 2 concept/.append style={font=\Large},
+}
+\node[concept, font=\Large] (lib) {newstile's internal representation}
+  child[concept color=orange, grow=150, ->] {node[concept] (i-newstile) {newstile}}
+  child[concept color=orange, grow=210] {node[concept] (i-html) {HTML}}
+  child[concept color=green!50!black, grow=40] {node[concept] (o-html) {HTML}}
+  child[concept color=green!50!black, grow=0] {node[concept] (o-newstile) {newstile}}
+  child[concept color=green!50!black, grow=-45] {
+    node[concept] (o-latex) {\LaTeX}
+    child[grow=0] {
+      node[concept] (o-latex-pdf) {PDF}
+    }
+  }
+  child[concept color=green!50!black, grow=-45] {node[concept] {\LaTeX}}
+;
+\draw [dash pattern=on 0pt off 2pt,line width=5pt,arrows=-angle 60,shorten >=15pt,shorten <=10pt,color=orange]
+   (i-newstile) edge(lib)
+   (i-html) edge (lib);
+\draw [dash pattern=on 0pt off 2pt,line width=5pt,arrows=-angle 60,shorten >=10pt,shorten <=15pt,color=green!50!black]
+   (lib) edge(o-html)
+   (lib) edge (o-newstile)
+   (lib) edge (o-latex);
+{tikz}
+{: style="text-align: center"}
+## Bugs, Forums, Mailing Lists
+If you have found a bug, you should [report it here][bug_report]. Also, there are [forums][forum]
+and [mailing lists][ml] available if you have any questions!
+[bug_report]: http://rubyforge.org/tracker/?atid=28673&group_id=7403&func=browse
+[forum]: http://rubyforge.org/forum/?group_id=7403
+[ml]: http://rubyforge.org/mail/?group_id=7403
+## Thanks
+newstile would not be possible without the prior work of many other people. I want to thank everyone
+involved with making Markdown such a nice markup language and especially the developers of other
+Markdown implementations because newstile borrowed many ideas from existing packages.
+## Author
+* Thomas Leitner
+* e-Mail: <t_leitner@gmx.at>
+* GPG Key-Id: 0xB2D0A854
+[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/
+[Maruku]:             http://maruku.rubyforge.org
+[BlueCloth]: http://www.deveiate.org/projects/BlueCloth
+--- name:intro
+## Welcome to the newstile site
+**newstile** (sic, not Newstile or KramDown, just newstile) is a *free* GPL-licensed
+[Ruby](http://www.ruby-lang.org) library for parsing and converting a superset of Markdown. It is
+completely written in Ruby, supports standard Markdown (with some minor modifications) and various
+extensions that have been made popular by the [PHP Markdown Extra] package and [Maruku].
+It is probably the fastest pure-Ruby Markdown converter available (June 2010), being about 4x faster
+than [Maruku] and about 9x faster than [BlueFeather].
+<p class="a-center">
+The latest version of newstile is <b>0.11.0</b> and it was released on <b>2010-10-01</b>.
+</p>
+[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/
+[Maruku]: http://maruku.rubyforge.org
+[BlueFeather]: http://ruby.morphball.net/bluefeather/index_en.html

data/doc/installation.page ADDED

@@ -0,0 +1,90 @@
+---
+title: Download &amp; Installation
+in_menu: true
+sort_info: 5
+---
+# Download & Installation
+## Compatibility Notes
+newstile should work on any platform which supports Ruby. It has been successfully tested on the
+following platforms:
+* Linux with Ruby 1.8.5, 1.8.6, 1.8.7, 1.9.1, 1.9.2-preview1 and jruby 1.5.0.
+* Mac OSX with Ruby 1.8.5, 1.8.6, 1.8.7, 1.9.1, 1.9.2-preview1 and jruby 1.5.0.
+See the platform specific installation notes for more information!
+## Platform Specific Installation Instructions
+### Linux
+There are a variety of Linux distributions out there with different package management systems. So
+we will focus on instructions for Ubuntu 9.04 here (which should probably also work for any newer
+Ubuntu version or any recent Debian based distribution).
+After running the following commands, newstile is installed and ready to use:
+    sudo aptitude install ruby rubygems
+    sudo gem1.8 install newstile
+> You will also need to add `export PATH=$PATH:/var/lib/gems/1.8/bin` to your `~/.bashrc` because
+> this is the binary path the executable files get installed to.
+### Mac OS X
+Mac OS X Snow Leopard comes with Ruby and Rubygems preinstalled. So installing newstile is as easy
+as running:
+    sudo gem install newstile
+### Windows
+You need to install Ruby first. This can easily be done by using the One-Click-Installer - just
+download the *latest* installation binary from the [files section][1] of the One-Click-Installer
+homepage and run it. After that open a command shell (select `Start -> Run...`, then enter `cmd` and
+click on `Ok`) and type in the following:
+    gem install newstile
+[1]: http://rubyforge.org/frs/?group_id=167
+## Generic Installation Instructions
+### Using Rubygems
+If you are using Rubygems, installing the latest version of newstile is as simple as executing
+    gem install newstile
+### Manual Installation
+The latest version of newstile can always be downloaded as `.tar.gz` or `.zip` from [its files
+section on Rubyforge](http://rubyforge.org/frs/?group_id=7403). After the download the package needs
+to be decompressed and then you can install newstile using the included `setup.rb` installation
+method:
+    $ ruby setup.rb config
+    $ ruby setup.rb setup
+    $ ruby setup.rb install
+### Using the repository version
+newstile uses git as its versioning system and newstile's repository is hosted on GitHub. The
+repository always contains a clean state of the current development version of newstile. To check
+out newstile use the following command:
+     git clone git://github.com/gettalong/newstile.git
+## Dependencies
+Since newstile is written in Ruby, you just need the [Ruby interpreter](http://www.ruby-lang.org)
+versions 1.8.5, 1.8.6, 1.8.7 or 1.9.1. There are no other dependencies.

data/doc/links.markdown ADDED

@@ -0,0 +1,6 @@
+[Maruku]: http://maruku.rubyforge.org
+[PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/
+[Pandoc]: http://johnmacfarlane.net/pandoc/
+[jsMath]: http://www.math.union.edu/~dpvc/jsMath/
+[BlueCloth]: http://deveiate.org/projects/BlueCloth
+[RedCloth]: http://redcloth.org/

data/doc/news.feed ADDED

@@ -0,0 +1,10 @@
+---
+title: newstile News
+description: newstile - a fast, pure Ruby Markdown-superset converter
+site_url: http://newstile.rubyforge.org/
+author: Thomas Leitner
+author_url: http://newstile.rubyforge.org
+number_of_entries: 10
+rss: false
+entries: [news/*.html]

data/doc/news.page ADDED

@@ -0,0 +1,28 @@
+---
+title: News
+in_menu: true
+sort_info: 30
+--- pipeline:tags,blocks,fragments
+<h1>News</h1>
+<a href="{relocatable: news.atom}">Atom-Feed</a>
+<webgen:block name="newsdata" node="current" />
+--- name:newsdata pipeline:erb
+<%
+context.content_node.tree.node_access[:alcn].select do |na,no|
+  na =~ /\/news\/.+/ && no.is_file?
+end.collect {|na,no| no}.sort.reverse.each do |node|
+  context.options['contentprocessor.newstile.options'] = {:auto_id_prefix => node.lcn.tr('.', '-')}
+%>
+<div class='news-item'>
+<div class="news-date float-right">
+  Published on <%= node['created_at'].strftime("%A, %d %B %Y") %>
+</div>
+<%= context.render_block(:name => 'content', :chain => [node]) %>
+</div>
+<% end %>

data/doc/quickref.page ADDED

@@ -0,0 +1,564 @@
+---
+title: Quick Reference
+in_menu: true
+sort_info: 9
+--- name:sidebar
+<h1>Contents</h1>
+{menu: {used_nodes: fragments, min_levels: 4, max_levels: 6}}
+--- name:content
+# Quick Reference
+Below are examples of all available structural elements that can be used in a newstile text. Since
+the newstile syntax is a superset of the Markdown syntax, only a small part of the available syntax
+is not available in standard Markdown syntax. Note, that only the most basic syntax information is
+given. However, a link to the detailed syntax for each element is provided (which also details the
+differences to the standard Markdown syntax). The quick reference is for version **<%=
+::Newstile::VERSION %>** of the syntax documentation.
+newstile has two main classes of elements: block and span level elements. Block level elements are
+used to create paragraphs, headers, lists and so on whereas span level elements are used to markup
+text phrases as emphasized, as a link and so on.
+All examples below feature the newstile source, the converted HTML source and the output as it
+appears in the browser. This looks like this:
+<div class="kdexample">
+<pre class="kdexample-before"><code>newstile example code</code></pre>
+<pre class="kdexample-after-source"><code>Example code converted to HTML</code></pre>
+<div class="kdexample-after-live" style="clear:none">
+Live browser view of example code
+</div>
+</div>
+<div class="clear"></div>
+# Block Level Elements - Main Structural Elements
+## Paragraphs
+{kdlink: {oid: paragraphs, part: "paragraphs"}}
+Paragraphs are separated by one or more blank lines:
+{kdexample::}
+The first paragraph.
+Another paragraph
+{kdexample}
+Explicit line breaks in a paragraph can be made by using two spaces or two backslashes at the end of a line:
+{kdexample::}
+This is a paragraph
+which contains a hard line break.
+{kdexample}
+## Headers
+{kdlink: {oid: headers, part: "headers"}}
+newstile supports Setext style headers and atx style headers. A header must always be preceded by a
+blank line except at the beginning of the document:
+{kdexample::}
+First level header
+==================
+Second level header
+-------------------
+{kdexample}
+{kdexample::}
+# H1 header
+## H2 header
+### H3 header
+#### H4 header
+##### H5 header
+###### H6 header
+{kdexample}
+If you set the option `auto_ids` to `false` (for example, by using the `options` extension, see
+[Extensions](#extensions)), then the automatic header ID generation is turned off:
+{kdexample::}
+{:options auto_ids="false" /}
+# A header without an ID
+{kdexample}
+## Blockquotes
+{kdlink: {oid: blockquotes, part: "blockquotes"}}
+A blockquote is started using the `>` marker followed by an optional space; all following lines that
+are also started with the blockquote marker belong to the blockquote. You can use any block level
+elements inside a blockquote:
+{kdexample::}
+> A sample blockquote.
+> >Nested blockquotes are
+> >also possible.
+>
+> ## Headers work too
+> This is the outer quote again.
+{kdexample}
+## Code Blocks
+{kdlink: {oid: code-blocks, part: "code blocks"}}
+newstile supports two different code block styles. One uses lines indented with either four spaces
+or one tab whereas the other uses lines with tilde characters as delimiters -- therefore the content
+does not need to be indented:
+{kdexample::}
+    This is a sample code block.
+    Continued here.
+{kdexample}
+{kdexample::}
+~~~~~~
+This is also a code block.
+~~~
+Ending lines must have at least as
+many tildes as the starting line.
+~~~~~~~~~~~~
+{kdexample}
+## Horizontal Rules
+{kdlink: {oid: horizontal-rules, part: "horizontal rules"}}
+It is easy to insert a horizontal rule in newstile: just use three or more asterisks, dashes or
+underscores, optionally separated by spaces or tabs, on an otherwise blank line:
+{kdexample::}
+* * *
+\---
+  _  _  _  _
+---------------
+{kdexample}
+## Lists
+{kdlink: {oid: lists, part: "lists"}}
+newstile supports ordered and unordered lists. Ordered lists are started by using a number followed
+by a period, a space and then the list item text. The content of a list item consists of block level
+elements. All lines which have the same indent as the text of the line with the list marker belong
+to the list item:
+{kdexample::}
+1. This is a list item
+2. And another item
+2. And the third one
+   with additional. text
+{kdexample}
+As the content consists of block level elements you can do things like the following:
+{kdexample::}
+1.  This is a list item
+    > with a blockquote
+    # And a header
+2.  Followed by another item
+{kdexample}
+Nested lists are also easy to create:
+{kdexample::}
+1. Item one
+   1. sub item one
+   2. sub item two
+   3. sub item three
+2. Item two
+{kdexample}
+Lists can occur directly after other block level elements, however, there has to be at least one
+blank line if you want to follow a paragraph with a list:
+{kdexample::}
+This is a paragraph.
+1. This is NOT a list.
+1. This is a list!
+{kdexample}
+Unordered lists are started by using an asterisk, a dash or a plus sign (they can be mixed) and a
+space. Apart from that unordered lists follow the same rules as ordered lists:
+{kdexample::}
+* Item one
++ Item two
+- Item three
+{kdexample}
+## Definition Lists
+{kdlink: {oid: definition-lists, part: "definition lists"}}
+A definition list works similar to a normal list and is used to associate definitions with terms.
+Definition lists are started when a normal paragraph is followed by a line starting with a colon and
+then the definition text. One term can have many definitions and multiple terms can have the same
+definition. Each line of the preceding paragraph is assumed to contain one term, for example:
+{kdexample::}
+term
+: definition
+: another definition
+another term
+and another term
+: and a definition for the term
+{kdexample}
+If you insert a blank line before a definition (note: there must only be one blank line between the
+terms and the first definition), the definition will be wrapped in a paragraph:
+{kdexample::}
+term
+: definition
+: definition
+{kdexample}
+Each term can be styled using span level elements and each definition is parsed as block level
+elements, i.e. you can use any block level in a definition. Just use the same indent for the lines
+following the definition line:
+{kdexample::}
+This *is* a term
+: This will be a para
+  > a blockquote
+  # A header
+{kdexample}
+## Tables
+{kdlink: {oid: tables, part: "tables"}}
+newstile supports a syntax for creating simple tables. A line starting with a pipe character (`|`)
+starts a table row. However, if the pipe characters is immediately followed by a dash (`-`), a
+separator line is created. Separator lines are used to split the table header from the table body
+(and optionally align the table columns) and to split the table body into multiple parts. If the
+pipe character is followed by an equal sign (`=`), the tables rows below it are part of the table
+footer.
+{kdexample::}
+| A simple | table |
+| with multiple | lines|
+{kdexample}
+{kdexample::}
+| Header1 | Header2 | Header3 |
+|:--------|:-------:|--------:|
+| cell1   | cell2   | cell3   |
+| cell4   | cell5   | cell6   |
+|----
+| cell1   | cell2   | cell3   |
+| cell4   | cell5   | cell6   |
+|=====
+| Foot1   | Foot2   | Foot3
+{: rules="groups"}
+{kdexample}
+## HTML elements
+{kdlink: {oid: html-blocks, part: "HTML blocks"}}
+newstile allows you to use block level HTML tags (`div`, `p`, `pre`, ...) to markup whole blocks of
+text -- just start a line with a block level HTML tag. newstile syntax is normally not processed
+inside an HTML tag but this can be changed with the `parse_block_html` option. If this options is
+set to `true`, then the content of a block level HTML tag is parsed by newstile either as block
+level or span level text, depending on the tag:
+{kdexample::}
+<div style="float: right">
+Something that stays right and is not wrapped in a para.
+</div>
+{options: parse_block_html="true"}
+<div>
+This is wrapped in a para.
+</div>
+<p>
+This can contain only *span* level elements.
+</p>
+{kdexample}
+## Block Attributes
+{kdlink: {oid: block-ials, part: "block IALs"}}
+{kdlink: {oid: attribute-list-definitions, part: "ALDs"}}
+You can assign any attribute to a block level element. Just directly follow the block with a *block
+inline attribute list* (or short: block IAL). A block IAL consists of a left curly brace, followed
+by a colon, the attribute definitions and a right curly brace. Here is a simple example which sets the
+`title` attribute of a block quote:
+{kdexample::}
+> A nice blockquote
+{: title="Blockquote title"}
+{kdexample}
+As one often wants to set one or more CSS classes on an element, there is an easy shortcut:
+{kdexample::}
+> A nice blockquote
+{: .class1 .class2}
+{kdexample}
+A shortcut for setting the ID is also provided. Just prefix the ID with a hash symbol:
+{kdexample::}
+> A nice blockquote
+{: #with-an-id}
+{kdexample}
+Sometimes one wants to use the same attributes for many elements. newstile allows you to define the
+attributes in one place with an *attribute list definition* (or short: ALD) and just reference this
+definition in a block IAL. An ALD has the same structure as a block IAL but the colon has to be
+replace with a colon, the reference name and another colon. By just using the reference name as-is
+in a block IAL, one can include the attributes of the referenced ALD:
+{kdexample::}
+{:refdef: .c1 #id .c2 title="title"}
+paragraph
+{: refdef}
+{kdexample}
+The order in a block IAL or ALD is important because later defined attributes overwrite (with the
+exception of the shortcut for CSS classes) prior defined attributes:
+{kdexample::}
+{:refdef: .c1 #id .c2 title="title"}
+paragraph
+{: refdef .c3 title="t" #para}
+{kdexample}
+## Extensions
+{kdlink: {oid: extensions, part: "extensions"}}
+newstile provides some less used functionality through a common syntax. This will allow the easy
+addition of other extensions if need arises. Currently, there are extensions for ignoring text (i.e.
+treating text as comment), for inserting arbitrary text as-is into the output and for setting
+newstile options.
+Here is an example that shows how to insert comments into text:
+{kdexample::}
+This is a paragraph
+{:comment}
+This is a comment which is
+completely ignored.
+{:/comment}
+... paragraph continues here.
+Extensions can also be used
+inline {:nomarkdown}**see**{:/}!
+{kdexample}
+As one can see from the above example, the syntax for extensions is nearly identical to that of
+ALDs. However, there is no trailing colon after the extension name and the extension end tag needs a
+slash between the colon and the extension name. One can also use the short form of the end tag, i.e.
+`{:/}`. Attribute definitions can be specified on the start tag by separating them with a space from
+the extension name. Also, if the extension does not have a body, there needs to be a slash right
+before the closing brace:
+{kdexample::}
+{:options auto_ids="false" /}
+# Header without id
+{kdexample}
+# Span Level Elements - Text Modifiers
+## Emphasis
+{kdlink: {oid: emphasis, part: "emphasis"}}
+Emphasis can be added to text by surrounding the text with either asterisks or underscores:
+{kdexample::}
+This is *emphasized*,
+_this_ too!
+{kdexample}
+Strong emphasis can be done by doubling the delimiters:
+{kdexample::}
+This is **strong**,
+__this__ too!
+{kdexample}
+The form with the asterisks can also be used to markup parts of words:
+{kdexample::}
+This w**ork**s as expected!
+{kdexample}
+## Links and Images
+{kdlink: {oid: links-and-images, part: "links and images"}}
+A simple link can be created by surrounding the text with square brackets and the link URL with
+parentheses:
+{kdexample::}
+A [link](http://newstile.rubyforge.org)
+to the newstile homepage.
+{kdexample}
+You can also add title information to the link:
+{kdexample::}
+A [link](http://newstile.rubyforge.org "hp")
+to the homepage.
+{kdexample}
+There is another way to create links which does not interrupt the text flow. The URL and title are
+defined using a reference name and this reference name is then used in square brackets instead of
+the link URL:
+{kdexample::}
+A [link][newstile hp]
+to the homepage.
+[newstile hp]: http://newstile.rubyforge.org "hp"
+{kdexample}
+If the link text itself is the reference name, the second set of square brackets can be omitted:
+{kdexample::}
+A link to the [newstile hp].
+[newstile hp]: http://newstile.rubyforge.org "hp"
+{kdexample}
+Images can be created in a similar way: just use an exclamation mark before the square brackets. The
+link text will become the alternative text of the image and the link URL specifies the image source:
+{kdexample::}
+An image: ![gras](img/image.jpg)
+{kdexample}
+## Inline Code
+{kdlink: {oid: code-spans, part: "code spans"}}
+Text phrases can be easily marked up as code by surrounding them with backticks:
+{kdexample::}
+Use `Newstile::Document.new(text).to_html`
+to convert the `text` in newstile
+syntax to HTML.
+{kdexample}
+If you want to use literal backticks in your code, just use two or more backticks as delimiters. The
+space right after the beginning delimiter and the one right before the closing delimiter are ignore:
+{kdexample::}
+Use backticks to markup code,
+e.g. `` `code` ``.
+{kdexample}
+## Footnotes
+{kdlink: {oid: footnotes, part: "footnotes"}}
+Footnotes can easily be used in newstile. Just set a footnote marker (consists of square brackets
+with a caret and the footnote name inside) in the text and somewhere else the footnote definition (which
+basically looks like a reference link definition):
+{kdexample::}
+This is a text with a
+footnote[^1].
+[^1]: And here is the definition.
+{kdexample}
+The footnote definition can contain any block level element, all lines following a footnote
+definition indented with four spaces or one tab belong to the definition:
+{kdexample::}
+This is a text with a
+footnote[^2].
+[^2]:
+    And here is the definition.
+    > With a quote!
+{kdexample}
+As can be seen above the footnote name is only used for the anchors and the numbering is done
+automatically in document order.
+## Abbreviations
+{kdlink: {oid: abbreviations, part: "abbreviations"}}
+Abbreviations will work out of the box once you add an abbreviation definition. So you can just
+write the text and add the definitions later on.
+{kdexample::}
+This is an HTML
+example.
+*[HTML]: Hyper Text Markup Language
+{kdexample}
+## HTML Elements
+{kdlink: {oid: html-spans, part: "HTML spans"}}
+HTML is not only supported on the block level but also on the span level:
+{kdexample::}
+This is <span style="color: red">written in
+red</span>.
+{kdexample}
+## Inline Attributes
+{kdlink: {oid: span-ials, part: "span IALs"}}
+As with a block level element you can assign any attribute to a span level elements using a *span
+inline attribute list* (or short: span IAL). A span IAL has the same syntax as a block IAL and must
+immediately follow the span level element:
+{kdexample::}
+This is *red*{: style="color: red"}.
+{kdexample}