]> git.wincent.com - wikitext.git/commitdiff
doc: updates for "output_style" and HTML5 changes
authorWincent Colaiuta <win@wincent.com>
Sun, 13 Jun 2010 10:03:55 +0000 (12:03 +0200)
committerWincent Colaiuta <win@wincent.com>
Sun, 13 Jun 2010 10:03:55 +0000 (12:03 +0200)
Signed-off-by: Wincent Colaiuta <win@wincent.com>
README.rdoc
doc/RELEASE-NOTES
doc/rdoc.rb

index 5c08a13330d8855c6d0a3bb8980c76bbaf6c814c..c978f144c9b7935cfd0b0ead71ce280db125dd93 100644 (file)
@@ -284,10 +284,17 @@ the last path component is optional.
 
   {{foo.png}}
 
-Would become:
+When outputting using HTML syntax (the default), this would become:
+
+  <img src="/images/foo.png" alt="foo.png">
+
+When outputting using XML syntax, this would become a self-closing tag:
 
   <img src="/images/foo.png" alt="foo.png" />
 
+See the Wikitext::Parser documentation for information on setting the
+output syntax.
+
 You can override the "/images/" prefix using the +img_prefix+ attribute
 of the Parser.
 
@@ -299,7 +306,7 @@ slash; that is:
 
 Would become:
 
-  <img src="/foo.png" alt="/foo.png" />
+  <img src="/foo.png" alt="/foo.png">
 
 = Rails support
 
@@ -309,7 +316,21 @@ translated from wikitext markup into HTML when rendered.
 
 Likewise, a +to_wikitext+ method (aliased as +w+) is added to the +String+
 class (and also +NilClass+, for convenience) so that content can be easily
-translated.
+translated from inside view templates following patterns like:
+
+  @post.body.w
+
+The +to_wikitext+ method will preprocess its string using the
+String#wikitext_preprocess method, if it is defined, before feeding the string
+through the parser. This can be used to add application-specific behavior such
+as converting special strings like:
+
+  ticket #1234
+
+into links. An example preprocessor is included with the extension but it is
+not active by default; it can be activated with:
+
+  require 'wikitext/preprocess'
 
 Finally, a Wikitext::Parser#shared_parser method is added to provide
 convenient access to a shared singleton instance of the parser so as to
index e45e1e5253995e72edd8ab5b27dbb2ea31e8454d..f15552e205648c3b2f2e4f00560cd04072598d96 100644 (file)
@@ -12,6 +12,8 @@ the source code repository at: http://git.wincent.com.
 * use Rails 3 hooks to auto-initialize when listed in Gemfile
 * +code+ tags are now emitted instead of +tt+ tags for compliance
   with the HTML5 specification
+* new +output_style+ setting to switch between HTML syntax (the new
+  default) and XML syntax
 
 = Changes in 1.12
 
index b6501e48d701dc28d6e86ec5a92c030ac03e590e..ddd80653a71014cec5cfe7f19a2027b120b01ce0 100644 (file)
@@ -129,6 +129,35 @@ module Wikitext
   # contexts where they would otherwise disturb the visual harmony of
   # the page.
   #
+  # == +output_style+ (Symbol)
+  #
+  # Wikitext emits valid HTML5 fragments. By default, the output syntax is
+  # HTML. Optionally, the output syntax can be changed to XML by setting the
+  # +output_style+ to ":xml".
+  #
+  # This can be done during initialization:
+  #
+  #   parser = Wikitext::Parser.new :output_style => :xml
+  #
+  # Or via setting an attribute on the parser:
+  #
+  #   parser = Wikitext::Parser.new
+  #   parser.output_style = :xml
+  #
+  # Or at parse time:
+  #
+  #   parser = Wikitext::Parser.new
+  #   parser.parse input, :output_style => :xml
+  #
+  # In practice the only difference between the two output syntaxes is that
+  # the XML syntax uses self closing +img+ tags:
+  #
+  #   <img src="foo.png" alt="Foo" />
+  #
+  # While the HTML syntax does not:
+  #
+  #   <img src="foo.png" alt="Foo">
+  #
   # == +link_proc+ (lambda or Proc object)
   #
   # "Red links" can be implemented by providing a custom +link_proc+ block
@@ -253,6 +282,8 @@ module Wikitext
     #                         entirely).
     # +base_heading_level+::  An integer between 0 and 6 denoting the
     #                         current "heading level" (documented above).
+    # +output_style+::        A symbol, ":xml", to emit XML syntax (by
+    #                         default HTML syntax is emitted)
     def parse string, options = {}
       # This is just a placeholder.
       # See parser.c for the C source code to this method.