RubyGems - newstile - Versions diffs - 1.0.1 - Mend

newstile 1.0.1

Files changed (405) hide show

@@ -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}