docgenerator-creole 3.0.0

data/lib/docgenerator/creole/document.rb

@@ -0,0 +1,91 @@
+#encoding: utf-8
+=begin rdoc
+=end
+
+require 'log4r'
+
+module Docgenerator
+=begin rdoc
+Collect the classes to handle Creole-input.
+
+More about creole at http://www.wikicreole.org/
+=end
+  module Creole
+=begin rdoc
+Build a document.
+This is just a little combination of the classes Document and Creole.
+
+For the future: This class could allow features t build one TeX-file and
+multiple HTML (corresponding to pages).
+
+HTML-pagebreak could be forced with ======== or something similar.
+=end
+    class Creole_document
+
+=begin rdoc
+Define a creole document. The settings are forwarded to Document#new()
+
+Some settings are used only directly in Creole_document.
+- :with_toc: Add a table of contents at the beginning of the document.
+- :content: Wiki-text. Same as Creole_document#<<
+- :logname: Name for Creole#log
+=end
+      def initialize( settings = {} )
+        @with_toc  = settings[:with_toc ]
+        settings.delete(:with_toc)  #Avoid error message in Document.new
+        settings[:logname] ||= 'CreoleDoc'  #Just a name for easier debugging/logging
+        
+        @creole = Creole.new( 
+            #Get content if available and delete setting to avoid error message in Document.new
+            :logname      => settings.delete(:logname), #for logger
+            :content  => settings.delete(:content),
+            :ignore     => settings.delete(:ignore),
+            :targetdir => settings.delete(:targetdir)
+        )
+        #fixme/ideen parameter
+        #preamble -> vor wiki-texten
+        #post -> nach wiki-texten
+
+        @doc = Document.new(settings)
+        
+        @doc.runtex = settings[:runtex] if settings[:runtex]
+        
+        @log  = @doc.log
+        
+        @doc.body << creole
+        
+      end
+      #The related document
+      attr_reader :doc
+      #The related creole-object
+      attr_reader :creole
+      #Add content to the wiki.
+      def << (content)
+        @creole << content
+      end
+=begin rdoc
+Save the creole document.
+
+If requested, the tableofcontents is added.
+The first Creole_document#save decides, which variant is added (html/tex)
+=end
+      def save( filename, options = {} )
+        if @with_toc
+            @doc.body.insertbefore(creole, element(:htmlonly,{}, creole.toc(:level => @with_toc )))
+            @doc.body.insertbefore(creole, element(:latexonly,{},element(:tableofcontents).cr))
+            case @with_toc
+              when Numeric
+                @doc.head << element(:latexonly,{},"\\setcounter{tocdepth}{#{@with_toc}}\n")
+              end 
+            @with_toc  = false #Add it only once
+        end #@with_toc
+        
+        @doc.save(filename, options )
+      end
+      #Use runtex if available.
+      def runtex=(option)
+        @doc.runtex = option
+      end
+    end
+  end
+end

data/lib/docgenerator/creole/inclusion_and_plugins.rb

@@ -0,0 +1,91 @@
+=begin rdoc
+Creole inclusions and plugins
+
+This classes are defined to implement transclusions (http://en.wikipedia.org/wiki/Transclusion)
+
+* Inclusions are used later with {{xx}}
+  more at http://www.wikicreole.org/wiki/Inclusion
+* Plugins are used later with <<xx>>
+  more at http://www.wikicreole.org/wiki/Plugin
+
+By default, an inclusion expects a pictures, unless it es defined something else.
+
+You can extend Wikis with additional inclusions:
+
+ wiki = Creole.new()
+ wiki.inclusion['xxx'] = Creole_inclusion_xxx
+=end
+
+#
+
+module Docgenerator
+  module Creole
+
+=begin rdoc
+Dummy class for all inclusions and plugins.
+Used to check the correct definition.
+
+- Inclusions are used later with {{xx}}
+- Plugins are used later with <<xx>>
+
+Derived classes (Inclusions):
+- Creole_inclusion_img
+- Creole_inclusion_footnote_group
+- Creole_inclusion_footnote
+
+Derived classes (Plugins):
+- Creole_default_plugin
+- Creole_plugin_ruby
+- Creole_plugin_ruby_raw
+More subclasses may be possible.
+=end
+    class Creole_inclusion_and_plugin
+=begin rdoc
+Example:
+  {{inclusionname|description|option1=1,option2=2}}
+
+Parameters:
+*  inclusionname: Name of the inclusion (normally fix for an instance, unless e.g. Creole_inclusion_img)
+*  description: First parameter of the plugin.
+*  options: Array with the comma separated values. 
+   In the example:
+    ['option1=1','option2=2']
+*  wiki: creole-instance, where the plugin/inclusion is defined.
+=end
+      def initialize( inclusionname, description, options, wiki )
+        @inclusionname = inclusionname
+        @description = description
+        @options = options
+        @wiki = wiki
+        
+        raise "Inclusion received no wiki but #{wiki.inspect}" unless wiki.is_a?(Creole)
+      end
+      #Reader for the wiki.
+      attr_reader :wiki
+
+=begin rdoc
+Define meta-methods for Creole_inclusion_and_plugin
+=end 
+      class << self
+=begin rdoc
+Define class as a Inclusion.
+You may use the class as:
+  {{key}}
+=end 
+        def set_inclusions_key(key)
+          Inclusions::Collection[key] = self
+        end
+=begin rdoc
+Define class as a Plugin.
+You may use the class as:
+  <<key>>
+=end 
+        def set_plugin_key(key)
+          Plugins::Collection[key] = self
+        end
+
+      end #Meta-methods
+    end #Creole_inclusion_and_plugin
+  end #module Creole
+end #module Docgenerator
+

data/lib/docgenerator/creole/inclusions.rb

@@ -0,0 +1,148 @@
+=begin rdoc
+Creole inclusions.
+
+This classes are defined to implement inclusions.
+
+* Inclusions are used later with {{xx}}
+  more at http://www.wikicreole.org/wiki/Inclusion
+
+By default, an inclusion expects a pictures, unless it es defined something else.
+
+You can extend Wikis with additional inclusions:
+
+ wiki = Creole.new()
+ wiki.inclusion['xxx'] = Creole_inclusion_xxx
+=end
+
+#
+
+module Docgenerator
+  module Creole
+
+=begin rdoc
+Define Inclusions
+
+Inclusions are used via {{...}}
+
+Default: Creole_inclusion_img (defined in class definition Creole_inclusion_img)
+=end
+    module Inclusions
+      Collection = Hash.new()
+
+=begin rdoc
+Include images.
+http://www.wikicreole.org/wiki/Images
+
+There are yet more features than in standard.
+
+This is also the default for inclusions.
+
+Usage:
+ {{picurl.jpg|Alternate text|class=cc}}
+ {{picurl.jpg|Alternate text|css=width:50%}}
+
+See also Placeholders::Creole_figure.
+=end
+      class Creole_inclusion_img < Creole_inclusion_and_plugin
+        Collection.default = self
+=begin rdoc
+Define an image.
+The existence of the picture is checked.
+
+Supported options:
+* alt (2nd parameter of {{picsrc|...}}
+* css or imgcss
+* class or imgclass
+* longdesc  (can take a url, at least opera offers to call the description)
+* width    (only LaTeX. For HTML, use css-option).
+=end
+        def initialize( picname, alt_text, options, wiki )
+          super
+          @img = element(:img,{  :src => @inclusionname })
+          @img[:alt] << alt_text if alt_text
+          #Check existence of Picture. Only possible if the related wiki is available.
+          wiki.check_link_existence( @inclusionname, wiki.log )
+
+          css = CSS.new( :log => wiki.log )
+
+          #
+          #Check for options
+          #
+          #Missing options:
+          #* align
+          #* border
+          #* height
+          #* hspace
+          #* name
+          #* vspace
+          options.each{|option|
+            case option
+              when /^(img)?css\s*=\s*(.*)/
+                $2.split(/\s*;\s*/).each{|css_assignment|
+                  css_assignment =~ /(.+?)\s*:\s*(.+)/
+                  css[$1] = $2
+                }
+              when /^(img)?class\s*=\s*(.*)/
+                @img[:class] << $2
+              when /^width\s*=\s*(.*)/  #only for TeX
+                @img[:width] << $1
+              when /^height\s*=\s*(.*)/
+                @img[:height] << $1
+              when /^texoption\s*=\s*(.*)/
+                @img[:texoption] << $1
+              when /^caption\s*=\s*(.*)/
+                #makes only sense in TeX-output.
+                @img = element(:figure,{},[element(:centering), @img.Cr, element(:caption,{},$1).cr])
+              when /^longdesc\s*=\s*(.*)/ #gibt einen URI (nach RFC 2396) an, wo eine Langbeschreibung der Grafik zu finden ist
+                @img[:longdesc] << $1
+              else
+                wiki.log.warn("Img: Undefined option #{option}") if wiki.log.warn?
+              end #case option
+          } if options
+          @img.attr[:style] << css 
+
+        end
+        def to_doc(target, options = {})
+          @img.to_doc(target, options)
+        end
+      end #Creole_inclusion_img
+
+=begin rdoc
+Some short html
+
+Usage: 
+  {{html|code}}
+
+Note:
+There is also a placeholder for larger html:
+  <<<html
+  content
+  >>>
+=end
+      class Creole_short_html < Creole_inclusion_and_plugin
+        #We don't use it as plugin. Closing > from html may be confusing as in:
+        # <<html|<em>kursuiv</em>>>
+        set_inclusions_key 'html'
+        
+        
+        def initialize( inclusionname, description, options, wiki )
+          super
+          options.each{|option|
+            #~ case option
+              #~ else
+              @wiki.log.warn("HTML with unknown option #{option.inspect} not found") if @wiki.log.warn?
+            #~ end
+          }
+          @source = description
+          
+        end
+        #Return content only for html
+        def to_doc( target, options = {})
+          target == :html ? @source.to_doc( target, options ) : ''
+        end  
+      end #Creole_inclusion_html      
+    end #module Inclusions
+  end #module Creole
+end #module Docgenerator
+
+

data/lib/docgenerator/creole/placeholder.rb

@@ -0,0 +1,242 @@
+module Docgenerator
+  module Creole
+
+=begin rdoc
+Placeholder are defined in Creole-Syntax via <<< >>>
+
+Placeholders get a name and optional parameters:
+ <<<name|parameter
+
+Placeholders collect the content between <<< and >>>. 
+
+Derived classes are:
+- Creole::Placeholders::Dummy
+- Creole::Placeholders::Html
+- Creole::Placeholders::Latex
+- Creole::Creole_tabular
+- Creole::Creole_tab
+=end
+    class Placeholder
+=begin rdoc
+Define meta-methods for Creole_inclusion_and_plugin
+=end 
+        class << self
+=begin rdoc
+Define class as a placeholder.
+You may use the class as:
+  {{key}}
+=end 
+          def set_placeholder_key(key)
+            Placeholders::Collection[key] = self
+          end
+        end
+        
+        #Error is thrown, if the parameters don't fit the need of the placeholder
+        class ParameterError < ArgumentError; end;
+=begin rdoc
+Each placeholder get the wiki where it belongs to.
+
+Parameters is an optional string.
+
+Definition inside the wiki:
+ <<<name|parameters
+ content
+ >>>
+Placeholders collect the content between <<< and >>>.
+=end
+        def initialize( wiki, parameters = nil)
+          @wiki = wiki
+          @parameters = parameters
+          @log  = @wiki.log
+        end
+        #
+        #Add the content between <<< and >>>.
+        def << (content)
+          @source = [] unless @source
+          @source << content
+        end
+        #
+        #Possibility to analyse the content.
+        def close()
+          @source.freeze
+        end
+        #Export it. Should be redefined by sub classes.
+        def to_doc( target, options = {})
+          @source.to_doc( target, options )
+        end
+      end #Placeholder
+
+
+=begin rdoc
+Collection of Placeholder-children
+
+Placeholders are used via <<<...>>>.
+=end
+    module Placeholders  
+=begin rdoc
+Just a dummy for wrong definitions.
+
+This class is used by Creole a default placeholder.
+=end
+      class Dummy < Placeholder
+      end #Placeholder::Dummy
+
+      #List of defined Placeholders.
+      Collection = Hash.new( Dummy )
+      #Get a Placeholder.
+      def self.[](key)
+        Collection[key]
+      end
+
+
+=begin rdoc
+Placeholder for pure HTML-output.
+This content is ignored in LaTeX, Wiki... documents.
+
+Usage: 
+  <<<html
+  content
+  >>>
+
+Note:
+There is also a plugin for short html:
+  {{html|code}}
+=end
+      class Creole_html < Placeholder
+        set_placeholder_key 'html'
+        #Return content only for html
+        def to_doc( target, options = {})
+          target == :html ? @source.to_doc( target, options ) : ''
+        end  
+      end #Creole_html 
+
+=begin
+Placeholder for pure LaTeX-output.
+This content is ignored in HTML, Wiki... documents.
+
+Idea for option: Parse the content by the wiki.
+
+Pro:
+-allows the usage of <<ruby|... 
+Cons:
+-unexpected conversions?
+=end
+      class Creole_latex < Placeholder
+        set_placeholder_key 'latex'
+        #Return content only for latex
+        def to_doc( target, options = {})
+          target == :latex ? @source.to_doc( target, options ) : ''
+        end  
+      end #Creole_latex 
+
+=begin rdoc
+Usage: 
+  <<<comment
+  This text is a comment.
+  >>>
+=end
+      class Creole_comment < Placeholder
+        set_placeholder_key 'comment'
+        #Return content as a comment
+        def to_doc( target, options = {})
+          case target
+            when :html; to_html( options )
+            when :latex; to_latex( options )
+            when :context; to_latex( options )
+            when :creole; to_creole( options )
+            else
+              @log.error("Creole_comment not supported for target #{target.inspect}") if @log.error?
+          end
+        end  
+        def to_html(options = {})
+          return "<!-- #{@source.join} -->"
+        end
+        alias :to_context :to_latex
+        def to_latex(options = {})
+          return @source.map{|l| "%#{l}" }.join
+        end
+        def to_creole(options = {})
+          return "<<<comment\n#{@source.join}>>>"
+        end
+      end #Creole_comment
+
+=begin
+See also Inclusions::Creole_inclusion_img
+
+Usage:
+  <<<figure|picname.jpg|options
+  Description
+  >>>
+
+Options may be:
+# options if element Figure
+# options if element CSS
+=end
+      class Creole_figure < Placeholder
+        set_placeholder_key 'figure'
+        
+        #Return content as a comment
+        def to_doc( target, options = {})
+          css = CSS.new()
+          caption = nil
+          includegraphics_options = {}
+            
+          fig = element(:figure, 
+            :style => css
+          ).CR
+          float = 'top'
+          @parameters.split(/\|/).each{|parameter|
+            case parameter
+              when /caption\s*=\s*(.*)/
+                caption = $1
+              when /class\s*=\s*(.*)/
+                fig.attr[:class] << $1
+              when /texwidth\s*=(.*)/
+                includegraphics_options[:width] = $1
+              when /(.*)=(.*)/
+                if fig.attr[$1]
+                  fig[$1] = $2
+                elsif css.supports?($1)
+                  css[$1] = $2
+                else
+                  @log.warn("Unknown option %s in figure %s" % [parameter, src])
+                end
+              else
+                if includegraphics_options[:src]
+                  @log.warn("Unknown option %s in figure %s" % [parameter, src])
+                else  #Image is first parameter.
+                  includegraphics_options[:src] = parameter 
+                end
+            end
+          }
+          
+          #Set defauts:
+          {'border-width' =>'1px',
+            'border-style' =>'solid',
+            'float' => 'right',
+            'width'  => '50%',
+          }.each{|key,value|
+            css[key]  = value unless css[key]
+          }
+            
+          fig << element(:includegraphics,includegraphics_options).cr
+          fig << element(:label,{:name=>'fig:%s' % includegraphics_options[:src]}).cr
+          if @source
+            fig << element(:newline).cr
+            fig << @source
+          end
+          fig << element(:caption,{}, caption).cr if caption
+          fig.to_doc( target, options)
+        end
+      end
+
+    end #module Placeholders
+  end #module Creole
+end #module Docgenerator
+
+
+__END__
+To be done:
+rubycode (see plugin  Creole_plugin_ruby )
+
+Steuerparameter mit | nach plugin-name?