docgenerator-creole 3.0.0

data/lib/docgenerator/creole/characters.rb

@@ -0,0 +1,131 @@
+=begin rdoc
+Creole characters
+
+This classes define special characters as inclusions.
+
+* Inclusions are used later with {{xx}}
+  more at http://www.wikicreole.org/wiki/Inclusion
+=end
+
+#
+
+module Docgenerator
+  module Creole
+
+=begin rdoc
+Define special characters as inclusions.
+
+See also Creole::CHARACTERS
+=end
+    module Characters
+=begin rdoc
+Define a 'shy' as {{shy}}
+=end
+      class Creole_shy < Creole_inclusion_and_plugin
+        set_inclusions_key '-'
+        set_inclusions_key 'shy'
+        
+        def to_doc(target, options = {})
+          element(:shy).to_doc(target, options)
+        end  
+      end #Creole_shy
+=begin rdoc
+Define a 'thinsp' as {{thinsp}}
+
+Could be used as Soft hypen (&shy;) without dash:
+http://stackoverflow.com/questions/5038920/html-soft-hypen-shy-without-dash
+=end
+      class Creole_thinsp < Creole_inclusion_and_plugin
+        set_inclusions_key 'thinsp'
+        
+        def to_doc(target, options = {})
+          element(:thinsp).to_doc(target, options)
+        end  
+      end #Creole_thinsp
+=begin rdoc
+Define a 'wbr' as {{wbr}}
+=end
+      class Creole_wbr < Creole_inclusion_and_plugin
+        set_inclusions_key 'wbr'
+        
+        def to_doc(target, options = {})
+          element(:wbr).to_doc(target, options)
+        end  
+      end #Creole_wbr
+=begin rdoc
+Define a 'radic' as {{radic}}
+=end
+      class Creole_radic < Creole_inclusion_and_plugin
+        set_inclusions_key 'radic'
+        
+        def to_doc(target, options = {})
+          element(:radic).to_doc(target, options)
+        end  
+      end #Creole_shy
+
+=begin rdoc
+Define a 'nil' as {{nil}}
+=end
+      class Creole_nil < Creole_inclusion_and_plugin
+        set_inclusions_key  'nil'
+        
+        def to_doc(target, options = {})
+          ''
+        end  
+      end   #Creole_nil
+
+=begin rdoc
+=end
+      class Creole_gt < Creole_inclusion_and_plugin
+        set_inclusions_key 'gt'
+        set_inclusions_key '>'
+        
+        def to_doc(target, options = {})
+          element(:gt).to_doc(target, options)
+        end  
+      end #Creole_gt
+=begin rdoc
+=end
+      class Creole_lt < Creole_inclusion_and_plugin
+        set_inclusions_key '<'
+        
+        def to_doc(target, options = {})
+          element(:lt).to_doc(target, options)
+        end  
+      end #Creole_lt
+
+=begin rdoc
+=end
+      class Creole_gg < Creole_inclusion_and_plugin
+        set_inclusions_key 'dgt'
+        set_inclusions_key '>>'
+        
+        def to_doc(target, options = {})
+          element(:gg).to_doc(target, options)
+        end  
+      end #Creole_gt
+=begin rdoc
+=end
+      class Creole_ll < Creole_inclusion_and_plugin
+        set_inclusions_key 'dlt'
+        set_inclusions_key '<<'
+        
+        def to_doc(target, options = {})
+          element(:ll).to_doc(target, options)
+        end  
+      end #Creole_ll
+
+=begin rdoc
+=end
+      class Creole_ldots < Creole_inclusion_and_plugin
+        set_inclusions_key 'hellip'
+        set_inclusions_key '...'
+        
+        def to_doc(target, options = {})
+          element(:ldots).to_doc(target, options)
+        end  
+      end #Creole_ldots
+
+    end #module Characters
+  end #module Creole
+end #module Docgenerator

data/lib/docgenerator/creole/creole.rb

@@ -0,0 +1,708 @@
+#encoding: utf-8
+=begin rdoc
+Define class Docgenerator::Creole::Creole
+=end
+
+module Docgenerator
+
+=begin rdoc
+Collect the classes to handle Creole-input.
+
+More about creole at http://www.wikicreole.org/
+=end
+  module Creole
+
+=begin rdoc
+Creole is a standard wiki-syntax for wikitexts.
+Definition see http://www.wikicreole.org
+
+I liked this definition.
+When you look at the website, you get a definition and 
+you get an explanation, why it is like this. - great!
+
+This class gets a creole-text and translate it to elements of the docgenerator,
+they can be used by Document or directly like Element#to_doc.
+
+Example:
+  wiki = Creole.new()
+  wiki << <<txt
+  =Test document
+  This is a little test text with **bold** and //italic// text.
+  txt
+  wiki.to_latex()
+ 
+Often I use it in combination with "Here"-Documents with __END__:
+
+  require 'docgenerator/creole'
+
+  doc = Docgenerator::Creole::Creole_document.new()
+  doc << DATA
+  doc.save('test.html')
+  __ END__
+  Content
+--
+Im  Code beispiel steht __<space>END__ 
+Würde dort __END__ stehen, hätte rdoc einen Fehler.
+++
+=end
+    class Creole  
+      class << Creole  
+        #Define a default for targetdir-option in Creole.new. 
+        attr_accessor :targetdir
+      end
+      
+=begin rdoc
+Define the Creole-object.
+
+Options:
+* :log => Logger to catch information.
+
+  Alternativ you have access to the default logger via Creole#log
+* :targetdir => directory, where you want to save the result.
+
+  This directory is important for checks for internal links.
+  
+  You may change the default '.' with 
+    Docgenerator::Creole::Creole.targetdir = 'mysubdir'
+* :ignore: A regex describing parts to be ignored during text parsing. e.g. /^#~.*$/ for usage with scite.
+* :encoding: The encoding used for creole.
+  Default is UTF-8
+=end
+      def initialize( options = {} )
+        @options = {
+          :logname => 'Creole',  #Just a name for easier debugging/logging
+          :targetdir  => self.class.targetdir || '.',
+          :wrap_at  => 75,    #Default line wrapping
+          #~ :parsetest             => false  #Make an immediate test for parsing #fixme
+          #~ :placeholders = 
+          #Definition how to handle the sectioning.
+          :title_levels => {
+            0 => nil,
+            1 => :h1,
+            2 => :h2,
+            3 => :h3,
+            4 => :h4,
+            5 => :h5,
+            6 => :h6,
+          },
+          :ignore => nil, #Define a "local" comment, e.g /^#~.*$/ 
+          :encoding => __ENCODING__,
+        }.update(options)        
+        @placeholders = Placeholders::Collection.dup
+        @inclusions     = Inclusions::Collection.dup
+        @plugins        = Plugins::Collection.dup
+        
+        #Store the given source text
+        @source  = []
+        #Store the pre-parsed content
+        @normsource  = []
+        @toc  = []  #Collection of all heading lines
+        @footnotegroups = {}  #Collection of footnote groups
+        
+        @targetdir  = @options[:targetdir] if @options[:targetdir]
+        
+        @log  = @options[:log]
+        @log = Log4r::Logger.new(@options[:logname], Log4r::INFO) unless @log
+        @log.outputters = Log4r::StdoutOutputter.new('log_stdout') if  @log.outputters.empty?
+
+        @creation_caller = caller.first
+        self  <<  @options[:content]  if @options[:content]
+      end
+      
+      #Hash with placeholders.
+      #
+      #Placeholders are used with <<<'name'.
+      #This accessor is needed to add more placeholders for specific wikis.
+      #Default: Creole::Placeholders
+      attr_reader :placeholders
+      attr_reader :options
+      
+      #Hash with inclusions.
+      #This accessor is needed to add more inclusions for specific wikis.
+      #Default: Creole::Inclusions
+      attr_reader :inclusions
+      #Hash with all plugins
+      #This accessor is needed to add more plugins for specific wikis.
+      #Default: Creole::Plugins
+      attr_reader :plugins
+      #All footnotegroups of the wiki
+      attr_reader :footnotegroups 
+
+      #Error Class
+      class InputError < ArgumentError; end
+=begin rdoc  
+Get some content.
+Strings are taken like strings.
+Array items are handled like lines.
+
+It is possible to add the content of a file. Just add the open file handle.
+In case of ruby scripts, the part after __END__ is used as input.
+
+Content added with << starts always with a new paragraph, but it may contain 
+multiple paragraphs, lists...
+=end
+      def << ( input )
+        case input
+          when String
+          source = input
+        when Array
+          #Items of the array are handled like single lines.
+          #The chomp avoid double \n (the array items may already have their own newlines).
+          source = input.map{|item| item.chomp}.join("\n")  #ohne doppelte xx 
+        when File
+          #If file is a ruby script, then use the wiki-code after __END__
+          #
+          #Often scripts contains there own text content after __END__.
+          #So we have to catch, if << is called with DATA
+          if /\.rb\Z/ =~ input.path and $0 != input.path
+            @log.info("Take content of #{input.inspect} after __END__") if @log.info?
+            begin
+              line = input.readline while line != "__END__\n"
+            rescue EOFError
+              @log.error("No __END__ found in #{input.inspect}") if @log.error?
+            end  
+          end
+          #Read the code
+          source = input.readlines.join
+        else
+          raise InputError, "Don't know, how to handle #{input.class} in Creole#<<"      
+        end
+        begin
+          source_enc = source.encode(@options[:encoding])
+        rescue Encoding::UndefinedConversionError => err
+          @log.warn("Encoding conversion error <#{err}>") if @log.warn?
+          source_enc = source.encode(@options[:encoding], :undef => :replace)
+        end
+        @source << source_enc 
+        #Parse the given source.
+        #This is done immediate, so you have a chance to localize the line, where an error occurs.
+        #(Some errors are reported later during to_doc).
+        #fixme: option to parse immediate at << or later
+        #immediate_parse => true...
+        @normsource.push( *parse( source_enc  ) )
+      end #<< ( input )
+=begin rdoc
+Parse the given creole code and build a "normalized source"
+=end
+      def parse( source = @source )
+        
+        normsource = []    
+        statusflag = nil  #Variable to store the actual status. nil = nothing special.
+        normsource << Creole_line.new(:dummy)
+
+        if ! source.respond_to?(:each_with_index)
+          #Ruby 1.9 removed each from String
+          if source.respond_to? :each_line
+            source = source.each_line 
+          else
+            @log.fatal("Unable to parse #{source.class}: #{source.inspect}" ) if @log.fatal?
+            return normsource
+          end
+        end
+
+
+        #
+        #Check code line by line
+        #
+        source.each_with_index{|line, lineno|
+          #Check special status
+          case statusflag
+            when nil  #Nothing to do
+            when :pre
+              line =~ /\}\}\}/ ? statusflag = nil : normsource.last.content << line
+              next
+            when :placeholder
+              #~ if line =~ /^>>>$/ #did not catch each system specific line end.
+              if line =~ /^>>>(\r\n?|\n)/   #finish placeholder (started with <<<)
+                statusflag = nil 
+                normsource.last.content.close
+              else
+                normsource.last.content << line
+              end
+              next
+            else
+              @log.fatal("Undefined status #{statusflag}: #{line.inspect}" ) if @log.fatal?
+            end #statusflag
+            
+          #
+          #Parse the wiki text on line level (main structure)
+          case line
+            #Skip this line, if it correspond to a special comment-pattern.
+            #Can be used for application-specific comments.
+            #
+            #Example: 
+            #   :ignore => /^(#~.*)$/
+            #This comment is created by scite using Ctrl-Q (for ruby-scripts).
+            when @options[:ignore]
+                @log.info("Found comment in line %2i: %s" % [
+                  lineno, #line.inspect
+                  [$~.pre_match, '<<', $1, '>>', $~.post_match].join.strip,
+                ]) if @log.info?
+            #Headings
+            #http://www.wikicreole.org/wiki/Headings
+            #
+            #Modification of standard: Labels are possible.
+            when /^(=+)(?:\[(.*)\])?(.+?)(=*)\s*$/
+              normsource << Creole_line.new(:title, $3, :level => $1.size, :label => $2 )
+              @toc << normsource.last
+              #Creole doesn't need a trailing ===, but when it is ther, it should be correct
+              if $1.size != $4.size and $4.size > 0
+                @log.warn("Heading problem #{$1} doesn't match <#{$4}>: #{line.inspect}" ) if @log.warn?
+              end
+              if $~.post_match !~ /\s*/
+                @log.warn("Ignore text #{$~.post_match.inspect} after title  <#{line.inspect}>" ) if @log.warn?
+              end
+              #And close the actual level
+              #See unit test test_creole_mix_titles_list
+              normsource << Creole_line.new(:dummy )
+            #Empty line
+            when /^\s*$/
+              normsource << Creole_line.new(:dummy )
+            when /^----\s*$/
+              normsource << Creole_line.new(:hr )
+            #List entry
+            when /^\s*((\*|\#)+)/
+              normsource << Creole_line.new(:list, $~.post_match, :listtype => $1 )
+            #Tabular
+            when /^\|/
+              #fixme tab soll in par...
+              #~ normsource.last << Creole_line.new(:placeholder, 
+              #~ ... unless anpassen...
+              normsource << Creole_line.new(:placeholder, 
+                                            @placeholders['creole_tabular'].new(self),
+                                            :start => lineno
+                                          ) unless normsource.last.content.is_a?(Creole_tab)
+              normsource.last.content << line
+            #http://www.wikicreole.org/wiki/PreformattedAndNowiki
+            when /^\{\{\{\s*$/  #Kind of verbatim
+              normsource << Creole_line.new(:pre, [], :start => lineno )
+              statusflag = :pre
+            #~ when /^<<<(.*)\|?(.*?)/ #fixme options for placeholders?
+            when /^<<<(.*)/       #placeholder (collect everything until >>>
+              ph, par = $1.split(/\|/,2)
+              placeholder = @placeholders[ph].new(self, par)
+              if placeholder.instance_of?(Placeholders::Dummy)
+                @log.warn("Unknown placeholder #{ph.inspect} used in line #{lineno}" ) if @log.warn?
+              end
+              normsource << Creole_line.new(:placeholder, placeholder, :start => lineno )
+              statusflag = :placeholder
+            else
+              case normsource.last.type
+                when :par, :list
+                  normsource.last.content << line
+                else
+                  normsource << Creole_line.new(:par, line )
+                end
+          end
+        }
+        case statusflag
+          when nil  #ok
+          when :pre
+            @log.warn("Unclosed verbatim found (start at #{normsource.last.add_info[:start]})" ) if @log.warn?
+            #~ raise ''
+          when :placeholder
+            #One possible source: Regexp $ is system specific.
+            @log.warn("Unclosed placeholder #{normsource.last.type} (start at #{normsource.last.add_info[:start]})" ) if @log.warn?
+          else
+            @log.warn("Wiki ends with status #{statusflag.inspect}" ) if @log.warn?
+        end
+        return normsource
+      end #parse
+      #Logger to collect messages.
+      attr_reader :log
+      #Returns the source as it was received
+      attr_reader :source
+      #The pre-parsed content. 
+      attr_reader :normsource
+      #Directory for the target.
+      #Can be used to check internal links (images, local files...)
+      attr_reader :targetdir
+  
+=begin rdoc
+Return a table of contents as a list.
+=end
+      def toc( i_options = {})
+        options = {
+          :listtype  => :ul,
+          :level    => 4,
+          #~ :startlevel  => 1,
+          }.update(i_options)
+
+        if ! options[:level].is_a?(Integer)
+          @log.error("Toc: toclevel is no number but '#{options[:level].inspect}'. Set 4") if @log.error?
+          options[:level] = 4
+        end
+
+
+        toclist = []
+        toclabel = [0] #help variable to construct labels
+        listtype = '*'
+        case options[:listtype]
+          when '*', :ul, :itemize
+            listtype = '*'
+          when '#', :ol, :enumerate
+            listtype = '#'
+          else
+            @log.error("Toc: Unknown listtype #{options[:listtype]}") if @log.error?
+        end
+        
+        @toc.each{|tocentry|
+            level = tocentry.add_info[:level]
+            #Skip deeper levels then wanted.
+            next if level > options[:level]
+
+            #Build the label
+            if level > toclabel.size
+              toclabel << 0
+            elsif level < toclabel.size
+              toclabel.pop
+            end
+            #Happens if there is a jump gap on section levels (subsubsection inside section without subsection)
+            if ! toclabel[level-1]
+              @log.warn("Missing toclevel for <#{tocentry.content}> #{tocentry.add_info.inspect}")
+              #add dummy level 
+              toclabel << 0
+              toclist << "#{listtype * ( level - 1)} ---"
+            end
+            toclabel[level-1] = toclabel[level-1] + 1 
+
+            #Check if there was already a label.
+            #If yes: use it. If not: build a new one with the help of toclabel.
+            if tocentry.add_info[:label]
+              label = tocentry.add_info[:label]
+            else
+              label = tocentry.add_info[:label] = toclabel.join('-')
+            end
+            
+            #Feature to create the toc if higher levels are missing /start at h3...)
+            #~ if level < options[:startlevel]
+              #~ @log.warn( "toc: TOC starts not at #{options[:startlevel]}, but level #{level}" ) if @log.warn?
+              #~ next 
+            #~ end
+            
+            toclist << "#{listtype * level}[[##{label}|#{tocentry.content}]]"
+          }
+          toclist = <<toc
+<<<html
+<div class = 'toc'>
+>>>
+#{toclist.join("\n")}
+<<<html
+</div>
+>>>
+toc
+
+        return Creole.new( :content => toclist, :log => @log )
+      end #toc
+=begin rdoc
+Wrapping mechanism for texts.
+
+Don't do anything, if line_width is 0.
+
+See also http://stackoverflow.com/questions/7548968/format-output-to-40-characters-long-per-line/7549032#7549032
+and http://forum.ruby-portal.de/viewtopic.php?t=3844&p=24578
+=end
+      def word_wrap(text, line_width = @options[:wrap_at] ) 
+        return text if line_width <= 0        
+        text.gsub(/\n/, ' ').gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1\n").strip
+      end
+=begin rdoc
+Prepare document.
+=end
+      def to_doc( target, options = {} )
+        options[:log] = @log unless options[:log]
+        #
+        #Delete again all footnotegroups.
+        #Else you get footnotes doubled.
+        @footnotegroups = {}  #Collection of footnote groups
+        return normsource2elements( @normsource, options ).to_doc(target, options)
+      end #to_doc
+=begin rdoc
+Take the given normsource and build a list of elements.
+Used by
+- Creole#to_doc
+-  Creole_ruby#to_doc
+=end
+      def normsource2elements( normsource, options )
+        doc = []    
+        elements = {} #little collector for lists
+        normsource.each{|line|
+          case line.type
+            when :dummy
+              elements  = {}
+            #Here we define the sectioning.
+            #line.add_info[:level] contains the number of = from the wiki.
+            #
+            when :title
+              options[:log].error("%s: Undefined title level %i" % [__method__,line.add_info[:level]]) if options[:log].error? and ! @options[:title_levels][line.add_info[:level]]
+              doc << element(@options[:title_levels][line.add_info[:level]], {
+                                  :id => line.add_info[:label]
+                                  #inline or not? 
+                                  #Required for filenames with _ 
+                                  #But: http://www.wikicreole.org/wiki/Headings says no.
+                                  #Make decision depending on a setting?
+                                  }, line.content ).cr          
+                                  #~ }, inline(line.content, options ) ).cr          
+            when :list
+              key = line.add_info[:listtype]
+              if ! elements[key]
+                case key[-1,1]
+                when '*';  elements[key] = element(:ul).cR
+                when '#';  elements[key] = element(:ol).cR
+                else
+                  options[:log].error("Undefined listtype #{key[-1,1]}") if options[:log].error?
+                end
+                if key.size == 1  #new list, add to document
+                  doc << elements[key] 
+                elsif parent_list = elements[key[0,key.size-1]] #new sublist, add to "parent"
+                  parent_list << element(:li).cr unless parent_list.content.last.is_a?(:li)
+                  parent_list.content.last << elements[key] 
+                else  #sublist without parent.
+                  options[:log].error("List #{key} with missing superlist") if options[:log].error?
+                  doc << element(:comment,{},'Sublist without superlist - move on top level').cr #add pending list on top level.
+                  doc << elements[key] #add pending list on top level.
+                end
+              end
+              elements.each{|ekey, list|
+                case ekey
+                  when key
+                    list << element(:li,{}, inline(line.content, options) ).cr
+                  else
+                    elements.delete(ekey) if ekey.size >= key.size
+                end
+              }
+          when :pre
+            doc << element(:verbatim, {}, line.content ).cR
+          when :hr
+            doc << element(:hr).cr
+          when :placeholder
+            doc << line.content
+          when :par
+            doc << element(:par, {}, inline(line.content, options)).cR
+          else
+            options[:log].error("Wrong line type #{ line.type.inspect }") if options[:log].error?
+          end
+        }
+        
+        return doc
+      end #to_doc_internal
+=begin rdoc
+Parse the inline text.
+
+Options is a Hash and may contain:
+* :log (default: @log)
+=end
+      def inline( text,  options )
+        
+        raise ArgumentError, "Creole#inline: Options no Hash" unless options.is_a?(Hash)
+        options[:log]           = @log unless options[:log]
+        options[:plugins]      = @plugins unless options[:plugins]
+        options[:inclusions]  = @inclusions unless options[:inclusions]
+        
+        res = []  #result
+        stack = []  #
+
+        #~ http_regex  = 
+        #fixme: Only once to reduce runtime
+        splitregex = Regexp.new(
+          '(' + [
+                '\[\[.+?\]\]',  # [[...links]]
+                'https?:\/\/.+?(\s|\Z)', #including the next space!!
+                '\*\*', #bold
+                '\/\/', #emph
+                '\\\\\\\\', #newline
+                '\{\{\{.*?\}\}\}', #inline verbatim
+                '\{\{.*?\}\}', #images/inclusion
+                '<<.*?>>',   #Plugins
+                #Catch characters with special meaning in regexp, e.g. $
+                CHARACTERS.keys.map{|key| key.sub(/([\$])/, '\\\\\1')}.join('|')
+                ].join('|')  + ')'
+        )
+        #Splitt along 'active' elements.
+        #~ @options[:wrap_at]
+        #~ text.gsub(/\n/, ' ').split(splitregex).each{|el|
+        text.split(splitregex).each{|el|
+          case el
+            when '**' #bold
+              if stack.last.is_a?(:textbf)
+                  stack.pop #leave bold area
+              else 
+                stack << newel = element(:textbf) #enter bold area
+                if stack.size > 1
+                  stack[-2] << newel
+                else
+                  res << newel 
+                end
+              end
+            when '//' #italic
+              if stack.last.is_a?(:emph)
+                stack.pop #leave italic area
+              else
+                stack << newel = element(:emph) #enter italic area
+                if stack.size > 1
+                  stack[-2] << newel 
+                else
+                  res << newel 
+                end
+              end
+            when '\\\\' #newline
+              ( stack.last ? stack.last  : res ) << element(:newline).cr
+            #Something like [[http:...]]
+            when %r{^\[\[(.+?)(?:\|(.*?))?\]\]}  #Link
+              link = $1
+              linktext = $2 ? $2 : $1
+              case link
+                when /^(https?|ftp):\/\/.+?/
+                  link = link
+                #local file via file://...
+                when /^(file):\/\/(.+)/
+                  link = link
+                  check_link_existence( $2, options[:log] )
+                when /^\./, /\S:[\\\/]/  #lokal file
+                  link = link
+                  check_link_existence( link, options[:log] )
+                when /^#/   #internal link
+                  link = link
+                  #fixme tex?
+                else  #internal link
+                  #This is normally the wiki-links.
+                  #But this is no wiki, it's a documentgenerator with wiki syntax.
+                  options[:log].warn("Unclear link <#{el}> #{self.inspect}") if options[:log].warn?
+                  link = link
+              end
+              if link == linktext #Avoid replacement of // inside linktext
+                href = element(:a, {:href=>link}, linktext )
+              else
+                href = element(:a, {:href=>link}, inline(linktext, options) )
+              end
+              if stack.last  
+                stack.last << href 
+              else
+                res << href
+              end
+            #All links should be catched before
+            when %r{\[\[(.*)\]\]}
+              options[:log].error("Lost link <#{el}>") if options[:log].error?
+            #fixme: there are obsolete 2 additional spaces in the result.
+            when /^http/ #implicit link
+              #~ href = element(:a, {:href=>el.strip}, el.strip ) #This makes problems with TeX (unmasked _,%...)
+              href = element(:url, {}, el.strip )
+              el =~ /(\s|\Z)$/  #get the end-space/newline if available
+              endspace = ( $1.empty? ? nil : $1 )
+              if stack.last  
+                stack.last << href
+                #~ stack.last << last_char #add again the 
+              else
+                res << href
+                #~ res << last_char  #add again the end-space/newline
+              end
+            #No-wiki inline: {{{text}}}
+            when /\{\{\{(.*)\}\}\}/     #verbatim
+              if stack.last  
+                stack.last << element(:verb,{},$1)
+              else
+                res << element(:verb,{},$1)
+              end
+            #Inclusion 
+            #creole implements a general inclusion.
+            #Main usage are pictures/images ({{picname|alt}}),
+            #but it can be more...
+            #
+            #Available inclusions are defined in Creole::Inclusions resp. Creole#inclusions,
+            when /\{\{(.+?)(?:\|(.*))?\}\}/     #Inclusion (e.g. images)
+              if stack.last  
+                stack.last << inclusion_or_plugin($1, $2, options[:inclusions])
+              else
+                res << inclusion_or_plugin($1, $2, options[:inclusions])
+              end
+            #Plugin
+            #Used like Inclusions.
+            #
+            #available plugins are defined in Creole::Plugins resp. Creole#plugins
+            when /<<(.+?)(?:\|(.*))?>>/
+              if stack.last  
+                stack.last << inclusion_or_plugin($1, $2, options[:plugins])
+              else
+                res << inclusion_or_plugin($1, $2, options[:plugins])
+              end
+            #No special wiki command. The text is "normal" text.
+            else  #text to add
+              #Replace characters.
+              if CHARACTERS[el]
+                insertion = CHARACTERS[el]
+                startspace = endspace = nil
+              else
+                startspace = ( el[0,1] =~ /\s/ )
+                endspace = ( el[-1,1] =~ /\s/ )
+                insertion = word_wrap( el )         #wrap content
+              end
+              if stack.last 
+                stack.last << insertion
+                #This adds some obsolete spaces in case of newlines at the end.
+                #But if I compare with ' ', then words will be concatenated without separator.
+                stack.last << ' ' if endspace
+              else  #Just some text without any format
+                res << ' ' if startspace #Keep space
+                res << insertion
+                res << ' ' if endspace #Keep space
+              end
+            end
+        }
+        res
+      end #inline
+=begin rdoc
+Inclusion or Plugin.
+Creole implements a general inclusion.
+Main usage are pictures/images ({{picname|alt}}),
+but it can be more...
+
+The last paramter contains a hash with the supported inclusions/plugins.
+=end
+      def inclusion_or_plugin( link, p_additions, inclusions )
+        
+        addition, additions = nil
+        #Splitt additions at | 
+        if p_additions
+          addition, *additions = p_additions.split(/\|/)
+        end
+
+        inclusion = inclusions[link]
+        #check inclusion.ancestors?
+        #~ if inclusion.superclass != Creole_inclusion_and_plugin
+        if inclusion.is_a?(Creole_inclusion_and_plugin)
+          @log.error( "Wrong inclusion/plugin definition for #{link} (#{inclusion.inspect}, expected #{inclusions.default.superclass})") if @log.error?
+          return nil
+        end
+        ip = inclusion.new( link, addition, additions, self )
+        return ip
+      end #inclusion
+=begin rdoc
+Check for links and pictures if the target exist.
+
+Absolute DOS-Pathes are detected (C:\...).
+Relative pathes are searched from @options[:targetdir] (default '.').
+
+Different locations are not supported (e.g. to implement LaTeXs \graphicspath)
+=end
+      def check_link_existence( filename, log )
+        case filename
+          when /^.:/#absolute DOS-path (e.g. c:\...)
+            path = filename.dup
+          else  #relative path
+            path = "#{@options[:targetdir]}/#{filename}".sub(/^\//, '')
+          end
+        path.sub!(/(\.html?)#.*$/, '\1') #Don't check anchor inside html
+        if ! File.exist?(path)
+          log.warn("Reference not found: <#{filename}> (looking at <#{path}>)") if log.warn?
+          #~ log.debug("Reference not found: <#{path}>") if log.debug?
+          fpath = File.expand_path("#{Dir.pwd}/#{path}")
+          log.debug("Reference not found: <#{fpath}>") if log.debug?
+        end
+      end #check_link_existence
+
+      def inspect()
+        "<#{self.class} (created #{@creation_caller})>"
+      end
+    end #Creole 
+  end #module Creole
+end #module Docgenerator