lib/kramdown/options.rb in kramdown-0.7.0 vs lib/kramdown/options.rb in kramdown-0.8.0

@@ -1,9 +1,9 @@
 # -*- coding: utf-8 -*-
 #
 #--
-# Copyright (C) 2009 Thomas Leitner <[e-mail]>
+# Copyright (C) 2009-2010 Thomas Leitner <[e-mail]>
 #
 # This file is part of kramdown.
 #
 # kramdown is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -20,11 +20,12 @@
 #++
 #
 
 module Kramdown
 
-  # This module defines all options that are used by parsers and/or converters.
+  # This module defines all options that are used by parsers and/or converters as well as providing
+  # methods to deal with the options.
   module Options
 
     # Helper class introducing a boolean type for specifying boolean values (+true+ and +false+) as
     # option types.
     class Boolean
@@ -37,26 +38,26 @@
     end
 
     # ----------------------------
     # :section: Option definitions
     #
-    # This sections informs about the methods that can be used on the Options class.
+    # This sections informs describes the methods that can be used on the Options module.
     # ----------------------------
 
     # Contains the definition of an option.
     Definition = Struct.new(:name, :type, :default, :desc)
 
-    # Allowed option types
+    # Allowed option types.
     ALLOWED_TYPES = [String, Integer, Float, Symbol, Boolean, Array, Object]
 
     @options = {}
 
     # Define a new option called +name+ (a Symbol) with the given +type+ (String, Integer, Float,
     # Symbol, Boolean, Array, Object), default value +default+ and the description +desc+.
     #
     # The type 'Object' should only be used if none of the other types suffices because such an
-    # option will be opaque!
+    # option will be opaque and cannot be used, for example, by CLI command!
     def self.define(name, type, default, desc)
       raise ArgumentError, "Option name #{name} is already used" if @options.has_key?(name)
       raise ArgumentError, "Invalid option type #{type} specified" if !ALLOWED_TYPES.include?(type)
       raise ArgumentError, "Invalid type for default value" if !(type === default) && !default.nil?
       @options[name] = Definition.new(name, type, default, desc)
@@ -65,11 +66,11 @@
     # Return all option definitions.
     def self.definitions
       @options
     end
 
-    # Return +true+ if an option +name+ is defined.
+    # Return +true+ if an option called +name+ is defined.
     def self.defined?(name)
       @options.has_key?(name)
     end
 
     # Return a Hash with the default values for all options.
@@ -77,11 +78,12 @@
       temp = {}
       @options.each {|n, o| temp[o.name] = o.default}
       temp
     end
 
-    # Merge the #defaults Hash with the parsed options from the given Hash.
+    # Merge the #defaults Hash with the *parsed* options from the given Hash, i.e. only valid option
+    # names are considered and their value is run through the #parse method.
     def self.merge(hash)
       temp = defaults
       hash.each do |k,v|
         next unless @options.has_key?(k)
         temp[k] = parse(k, v)
@@ -183,18 +185,22 @@
 
 Default: true
 Used by: kramdown parser
 EOF
 
-    define(:extension, Object, nil, <<EOF)
-An object for handling the extensions
+    define(:html_to_native, Boolean, false, <<EOF)
+Convert HTML elements to native elements
 
-The value for this option needs to be an object that can handle the
-extensions found in a kramdown document. If this option is `nil`, the
-default extension object is used.
+If this option is `true`, the parser converts HTML elements to native
+elements. For example, when parsing `<em>hallo</em>` the emphasis tag
+would normally be converted to an `:html` element with tag type `:em`.
+If `html_to_native` is `true`, then the emphasis would be converted to a
+native `:em` element.
 
-Default: nil
+This is useful for converters that cannot deal with HTML elements.
+
+Default: false
 Used by: kramdown parser
 EOF
 
     define(:footnote_nr, Integer, 1, <<EOF)
 The number of the first footnote
@@ -205,9 +211,11 @@
 Default: 1
 Used by: HTML converter
 EOF
 
     define(:filter_html, Array, [], <<EOF)
+NOTE: This option is deprecated and will be removed in a future release!
+
 An array of HTML tags that should be filtered from the output
 
 The value can either be specified as array or as a space separated
 string (which will be converted to an array). All HTML tags that are
 listed in the array will be filtered from the output, i.e. only their