README.marker

{{ style }}

= Marker =

Marker is a markup language parser designed for two needs:
# Need to mimic MediaWiki syntax
# Need to provide multiple output formats

Mimicing MediaWiki syntax is not exact.  One reason is that the MediaWiki
parser itself is very complicated and handles many cases specially.  It would
be very difficult to exactly copy the MediaWiki parser and it probably wouldn't
be worth the time because MediaWiki is intended for a wiki and needs to be
adapted to be used as a markup lanaguage--especially for multiple output
formats.  The purpose of mimicing MediaWiki syntax is so that users don't have
to learn more than one markup language, so the implementation doesn't ''need''
to be exact anyway.

Marker differs from MediaWiki in several ways, because it is a grammar-based
implementation.  The grammar is written as a [http://treetop.rubyforge.org/ Treetop]
parsing expression grammar
([http://en.wikipedia.org/wiki/Parsing_expression_grammar PEG]).

Not implemented:
# Table of contents
# Tables

== Use ==

Parsing is done with either Marker.parse or Marker.parse_file.  Both parse
methods will return a parse tree that has {{tt|to_html}} and {{tt|to_s}}
methods that "render" the markup.  Both render methods will accept an options
hash.

Example:
 >> require 'marker'
 => true
 >> m = Marker.parse "== heading ==\nparagraph with '''bold''' text"
 => Markup+...
 >> puts m.to_s
 heading
 --------------------------------------------------------------------------------
 paragraph with *bold* text
 => nil
 >> puts m.to_html
 <h2>heading</h2>
 <p>paragraph with <b>bold</b> text</p>
 => nil

=== Templates ===

Templates are implemented as method calls to a templates module.  Each method
in the templates module is considered a template and can be called using the
"{{ template | template_name }}" syntax.  Each template method is
expected to take three arguments: the render format ({{tt|:html}} or
{{tt|:text}}), an array of positional parameters, and a hash of named
parameters.  For example,
 module MyTemplates
   def logo( format, pos_params, name_params )
     case format
     when :html
       '<img src="/images/logo.png" />'
     else
       ''
     end
   end
 end

Template modules are passed to Marker by setting the {{tt|templates}} property:
 require 'my_templates'
 require 'marker'
 
 Marker.templates = Templates

If no template method is found, the template call is printed for debugging:
 >> puts Marker.parse( '{{t|one|two|name=val}}' ).to_s
 render:t( :text, ["one", "two"], {"name"=>"val"} )

Template names from markup are converted to lower case and have spaces replaced
with underscores to match ruby method naming conventions and to be case
insensitive for markup writers.  For example,
 "{{ My Template }}"  => :my_template
 "{{NaMe}}"           => :name

=== Internal Links ===

Internal links are implemented as links with default prefixes.  The link prefix
is specified by setting the {{tt|link_base}} property:
 require 'marker'
 
 Marker.link_base = 'http://example.com/pages/'
 
 >> puts Marker.parse( '[[target|name]]' ).to_html
 <p><a href='http://example.com/pages/target'>name</a></p>

The link target is appended to the link prefix, along with a beginning '/'.  If
no link base is given, links are just the link target with a beginning '/'.
The link base can also be given as a render option.

=== Unlabelled Links ===

Unlabelled, or "bare" links are detected if they start with a recognized URL
scheme such as {{tt|http}} or {{tt|https}}.  The URL is used as the link text.

== Command Line Program ==

Marker comes with a command-line program that will render both HTML and text.
If no input file is given, it reads from stdin.

 Usage: marker [--format (html|text)] [input-file]

== License ==

Marker is copyright 2009 Ryan Blue and distributed under the terms of the GNU
General Public License (GPL).  See the LICENSE file for further information on
the GPL, or visit http://creativecommons.org/licenses/GPL/2.0/.