docgenerator 1.2.1 → 2.0.0

data/lib/creole/plugins/rubycode4creole.rb

@@ -0,0 +1,136 @@
+=begin rdoc
+Little helper to make documention on ruby scripts,
+Ruby fragments are defined in the creole-source,
+You can get the code and the results.
+
+The source code is enriched with the results and can be shown.
+=end
+
+#Only for quick tests
+$:.unshift("../../") if $0 == __FILE__ 
+
+#~ fixme: use listings instead verbatim
+#~ check usage??
+
+require 'creole/creole2doc'
+require 'docgenerator/packages/rubycode4doc'
+
+module Docgenerator
+module Creole
+
+=begin rdoc
+Write rubycode inside creole-text
+=end
+module Rubycode
+
+=begin rdoc
+Print ruby source code as is
+=end
+class Code < Placeholder
+  set_placeholder_key 'rubycode'
+  #Return content in a verbatim environment
+  def to_doc( target, options = {})
+    codetest = Docgenerator::Rubycode::CodeTest.new(nil, @source.join )
+    #~ element(:verbatim,{},@source ).cr.to_doc( target, options )
+    element(:verbatim, {
+        :style => 'rubycode',
+      }, codetest.sourcecode ).cr.to_doc( target, options )
+  end  
+end #Code
+
+#
+#Print ruby source code and put the result of each line as a comment.
+#
+#Example:
+# 1 + 1
+#becomes 
+# 1 + 1   #2
+class Code_evaluated < Placeholder
+  set_placeholder_key 'rubycode_evaluated'
+  #Return content in a verbatim environment
+  def to_doc( target, options = {})
+    codetest = Docgenerator::Rubycode::CodeTest.new(nil, @source.join )
+    #~ element(:verbatim,{},@source ).cr.to_doc( target, options )
+    element(:verbatim, {
+        :style => 'rubycode_evaluated',
+      }, codetest.code_evaluation ).cr.to_doc( target, options )
+  end  
+end #Code_evaluated
+
+#
+#Print ruby source code and put the result of each line as a comment.
+#
+#Same as Code_evaluated, but export is done for in TeX-Package listings.
+class Code_evaluated_listings < Placeholder
+  set_placeholder_key 'rubycode_evaluated_listings'
+  #Return content in a verbatim environment
+  def to_doc( target, options = {})
+    codetest = Docgenerator::Rubycode::CodeTest.new(nil, @source.join )
+    #~ element(:verbatim, {
+        #~ :style => 'rubycode_evaluated',
+      #~ }, codetest.code_evaluation ).cr.to_doc( target, options )
+   codetest.code_evaluation_lstlisting.to_doc( target, options )
+      
+  end  
+end #Code_evaluated_listing
+
+#
+#Take only the output of the rubycode
+#
+class Code_output < Placeholder
+  set_placeholder_key 'rubycode_output'
+  #Return content in a verbatim environment
+  def to_doc( target, options = {})
+    codetest = Docgenerator::Rubycode::CodeTest.new(nil, @source.join )
+    #~ element(:verbatim,{},@source ).cr.to_doc( target, options )
+    element(:verbatim, {
+        :style => 'rubycode_output',
+      }, codetest.output ).cr.to_doc( target, options )
+  end  
+end #Code_output
+
+#
+#Build a table.
+#Each row corresponds with a source code line.
+#You get source code, result and output of the code line.
+#
+#
+class Code_in_tab < Placeholder
+  set_placeholder_key 'rubycode_in_tab'
+  #Return content in a verbatim environment
+  def to_doc( target, options = {})
+    codetest = Docgenerator::Rubycode::CodeTest.new(nil, @source.join )
+    codetest.code_in_tab.to_doc( target, options )
+  end  
+end #Code_in_tab
+end #module Rubycode
+end #module Creole
+end #module Docgenerator
+
+if $0 == __FILE__
+    wiki = Docgenerator::Creole::Creole.new()
+    wiki << <<wiki
+rubycode
+<<<rubycode
+1 + 1
+>>>
+----
+rubycode_output
+<<<rubycode_output
+puts 1 + 1
+>>>
+----
+rubycode_evaluated
+<<<rubycode_evaluated
+1 + 1
+>>>
+----
+rubycode_in_tab
+<<<rubycode_in_tab
+1 + 1
+>>>
+wiki
+puts wiki.to_html
+end
+
+__END__

data/lib/creole/plugins/struktex.rb

@@ -0,0 +1,59 @@
+=begin rdoc
+Add support of Struktex::Structogramm for Creole.
+=end
+require 'creole/creole2doc'
+require 'docgenerator/packages/struktex.rb'
+
+module Docgenerator
+module Creole
+
+=begin rdoc
+Define Creole placeholder.
+
+The placeholder insertion must contain three parameters:
+
+  >>>structogramm{Declarations/Interfaces;120;25}
+        Statement
+        ->	field1	description
+        <-	field2	description
+        <->	field3	description
+  <<<
+Details see Docgenerator::Structogramm
+=end
+class Creole_structogramm < Placeholder
+  set_placeholder_key('structogramm')
+  
+#~ fixme
+#~ parameters optional als placeholder,
+#~ hier aber ben�tigt. 
+#~ Defaults??
+
+  def initialize( wiki, parameters = nil)
+    super
+    #~ @wiki = wiki
+    #~ @log  = @wiki.log
+    par = parameters ? parameters.split(/;/) : []
+    case par.size
+      when 0
+        raise ParameterError, "Creole_structogramm: Missing parameters"
+      when 3
+        title = par[0]
+        x = par[1]
+        y = par[2]
+        @source = ''
+        @structogramm = Packages::Struktex::Structogramm.new( title, x, y, @source )
+    else
+      raise ParameterError, "Creole_structogramm: Wrong number of parameters: #{parameters.inspect}"
+    end
+  end
+  #Instance of class Structogramm.
+  attr_reader :structogramm
+  
+  #Return content only for latex
+  def to_doc( target, options = {})
+    target == :latex ? @structogramm.to_doc( target, options ) : ''
+  end  
+end #Creole_latex 
+
+end #module Creole
+end #module Docgenerator

data/lib/creole/plugins/todonotes.rb

@@ -0,0 +1,70 @@
+require 'docgenerator/packages/todonotes.rb'
+
+module Docgenerator
+module Creole
+
+=begin rdoc
+Classes to provide support for the todonotes-package.
+
+* http://ctan.org/tex-archive/macros/latex/contrib/todonotes/
+=end
+module Todo
+
+=begin rdoc
+Define a plugin for the todonotes-package.
+=end
+class Creole_todo < Creole_inclusion_and_plugin
+  
+  set_plugin_key('todo')  #use <<todo|..>>
+  
+  #define default options for todonotes. may be redefined for children of this class.
+  def default_options; {}; end
+
+=begin rdoc
+Usage:
+  <<todo|what to do|color=red>>
+=end
+  def initialize( inclusionname, description, options, wiki )
+    #~ @inclusionname = inclusionname #fix 'todo'
+    @description = description
+    @options = default_options.dup
+    options.each{|opt|
+      case opt
+        when /color\s*=\s*/
+          @options[:color] = $~.post_match
+        when /inline/
+          @options[:inline] = true
+        else
+          wiki.log.warn("Todo #{@description} with undefined option #{opt}")
+        end
+      }
+    @wiki = wiki
+    
+    raise "Inclusion received no wiki but #{wiki.inspect}" unless wiki.is_a?(Creole)
+  end
+  
+  def to_doc(target, options = {})
+    element(:todo, @options, @description).to_doc(target, options)
+  end  
+end #Creole_todo
+=begin rdoc
+A variant of Creole_todo with green color.
+=end
+class Creole_todo_green < Creole_todo
+    set_plugin_key('todo_green') #use <<todo_green|..>>
+  #define default options for todonotes. may be redefined for children of this class.
+  def default_options; {:color => 'green'}; end
+end
+
+=begin rdoc
+A variant of Creole_todo with inline-layout.
+=end
+class Creole_todo_inline < Creole_todo
+  set_plugin_key('todo_inline') #use <<todo_inline|..>>
+  #define default options for todonotes. may be redefined for children of this class.
+  def default_options; {:layout => 'green'}; end
+end
+
+end #module Todo
+end #module Creole
+end #module Docgenerator

data/lib/docgenerator.rb

@@ -10,8 +10,10 @@ The document generation is build via 'Elements',
 the target format is generic, actual supported are:
 -LaTeX 
 -HTML
-Plain text and a Wiki-version exist also, but they are not well maintained,
-a context-export is planned for the future (but it has a low level-importance for me).
+Plain text and two Wiki-version exist also (Wikimedia and Creole), 
+but they are not well maintained.
+A context-export is planned for the future 
+(but it has a low level-importance for me).
 
 
 ==Wiki
@@ -69,33 +71,62 @@ More at http://ruby.lickert.net/docgenerator/index.html
 #
 #For quick test
 #
-if $0 == __FILE__ and RUBY_VERSION == '1.9.1'
-  $:.unshift('./')
+if $0 == __FILE__ and RUBY_VERSION =~ /1.9/
+  $:.unshift('.')
 end
 
 
 
 =begin rdoc
-Just a dummy for the version.
-This module should be included by all classes.
+All classes of this gem are encapsulated in module Docgenerator.
 =end
-module Docgenerator   
+module Docgenerator
   #Define Version number  
-  VERSION = '1.2.1'
-end #Docgenerator
+  VERSION = '2.0.0'
+  class << self
+    @trace = nil
+=begin rdoc
+Set tracing on.
+
+Often there is the problem, that you get an error 
+when you write the element (Element#to_doc).
+
+But to correct the error, you need the location of 
+element creation, not usage.
+
+With Docgenerator.trace_on this tracing information is 
+stored during element creation.
+=end
+    def trace_on; @trace = true; end
+    #Set tracing off
+    def trace_off; @trace = false; end
+    #Check if element tracing is on., Details see Docgenerator.trace_on.
+    def trace_on?; @trace; end
+  end
 
 
 =begin rdoc
-Small include-module to define a to_doc-distributor
+Small include-module to define to_doc.
 
-If you include this, please redefine to_latex, to_html.... else you get a endless loop.
+You may include this method instead of define a element class as 
+a subclass of Element.
+
+In addition you get dummy definitions for
+* to_latex
+* to_html
+* to_context
+* to_creole
+* to_wiki
+* to_text
+
+If you include this, please redefine this methods
 =end
-module Docgenerator_to_doc
+module Element_methods
 =begin rdoc
 to_doc returns the object as a string.
 =end
   def to_doc(target, options = {})
-    o = Docgenerator_logger.set_option_defaults(options)
+    o = set_option_defaults(options)
     str = ""
     case target
       when :latex
@@ -108,6 +139,8 @@ to_doc returns the object as a string.
         str = self.to_wiki(options)
       when :creole
         str = self.to_creole(options)
+      when :text
+        str = self.to_text(options)
       else; 
         o[:log].error( "Unknown target #{target.inspect} for #{self.class}") if o[:log].error?
         str = self.to_doc_str()
@@ -115,39 +148,74 @@ to_doc returns the object as a string.
     str
   end
 =begin rdoc
-The following code must be redefinded
+Dummy method. Returns to_str (or to_s) and throws a log-information.
+
+This method should be redefinded by subclasses.
 =end
   def to_text(options = {})
-    o = Docgenerator_logger.set_option_defaults(options)
+    o = set_option_defaults(options)
     o[:log].fatal( "Please redefine to_text in #{self.class}") if o[:log].fatal?
     self.respond_to?(:to_str) ? self.to_str : self.to_s    
   end
+=begin rdoc
+Dummy method. Returns to_str (or to_s) and throws a log-information.
+
+This method should be redefinded by subclasses.
+=end
   def to_latex(options = {})
-    o = Docgenerator_logger.set_option_defaults(options)
+    o = set_option_defaults(options)
     o[:log].fatal( "Please redefine to_text in #{self.class}") if o[:log].fatal?
     self.respond_to?(:to_str) ? self.to_str : self.to_s    
   end
+=begin rdoc
+Dummy method. Returns to_str (or to_s) and throws a log-information.
+
+This method should be redefinded by subclasses.
+=end
   def to_context(options = {})
-    o = Docgenerator_logger.set_option_defaults(options)
+    o = set_option_defaults(options)
     o[:log].fatal( "Please redefine to_text in #{self.class}") if o[:log].fatal?
     self.respond_to?(:to_str) ? self.to_str : self.to_s    
   end
+=begin rdoc
+Dummy method. Returns to_str (or to_s) and throws a log-information.
+
+This method should be redefinded by subclasses.
+=end
   def to_html(options = {})
-    o = Docgenerator_logger.set_option_defaults(options)
+    o = set_option_defaults(options)
     o[:log].fatal( "Please redefine to_text in #{self.class}") if o[:log].fatal?
     self.respond_to?(:to_str) ? self.to_str : self.to_s    
   end
+=begin rdoc
+Dummy method. Returns to_str (or to_s) and throws a log-information.
+
+This method should be redefinded by subclasses.
+=end
   def to_wiki(options = {})
-    o = Docgenerator_logger.set_option_defaults(options)
+    o = set_option_defaults(options)
     o[:log].fatal( "Please redefine to_text in #{self.class}") if o[:log].fatal?
     self.respond_to?(:to_str) ? self.to_str : self.to_s    
   end
+=begin rdoc
+Dummy method. Returns to_str (or to_s) and throws a log-information.
+
+This method should be redefinded by subclasses.
+=end
   def to_creole(options = {})
-    o = Docgenerator_logger.set_option_defaults(options)
+    o = set_option_defaults(options)
     o[:log].fatal( "Please redefine to_text in #{self.class}") if o[:log].fatal?
     self.respond_to?(:to_str) ? self.to_str : self.to_s    
   end
-end #Docgenerator_to_doc
+
+=begin rdoc
+Instance-version of class method.
+=end
+  def set_option_defaults(options)
+    Docgenerator.set_option_defaults(options, self)
+  end
+  
+end #Element_methods
 
 
 require 'log4r'
@@ -174,10 +242,13 @@ but normally the problems are document problems,
 so we need the first step outside the docgenerator-path
 =end
 class LogFormatter < Log4r::BasicFormatter
-  #Use another format for the logger.
-  #
-  #Based on BasicFormatter. 
-  #When used with trace on, return the location from docgenerator and the first non-docgenerator position.
+=begin rdoc  
+Use another format for the logger.
+
+Based on BasicFormatter. 
+When used with trace on, return the location from docgenerator and 
+the first non-docgenerator position.
+=end
   def format(event)
     buff = sprintf(@@basicformat, Log4r::MaxLevelLength, Log4r::LNAMES[event.level],
            event.name)
@@ -202,28 +273,55 @@ class LogFormatter < Log4r::BasicFormatter
   end
 end #LogFormatter
 
-#Default Logger
+#Logger for Docgenerator
 DOCGENERATOR_LOGGER = Log4r::Logger.new( 'docgenerator')
-DOCGENERATOR_LOGGER.level = Log4r::FATAL
-DOCGENERATOR_LOGGER.outputters = Log4r::StdoutOutputter.new('log_stdout',
-        :formatter => LogFormatter 
-        )
+=begin
+DOCGENERATOR_LOGGER is used for gem-internal messages and problems.
 
+There will be a warning, if an Element gets no logger (option :log).
+This may be a quite common thing, so we set the default level to ERROR.
+=end
+DOCGENERATOR_LOGGER.level = Log4r::ERROR 
+DOCGENERATOR_LOGGER.level = Log4r::WARN if $0 == __FILE__  #internal test
+DOCGENERATOR_LOGGER.outputters = Log4r::StdoutOutputter.new('log_stdout',
+            :formatter => LogFormatter )
+#~ DOCGENERATOR_LOGGER.trace = true
+
+#Default Logger. Used in #set_option_defaults
+DOCGENERATOR_DEFAULT_LOGGER = Log4r::Logger.new( 'docgenerator default')
+=begin
+DOCGENERATOR_DEFAULT_LOGGER is used,
+if an Element gets no logger (option :log).
+=end
+#~ DOCGENERATOR_DEFAULT_LOGGER.level = Log4r::FATAL
+DOCGENERATOR_DEFAULT_LOGGER.level = Log4r::WARN
+DOCGENERATOR_DEFAULT_LOGGER.outputters = Log4r::StdoutOutputter.new('log_stdout',
+        :formatter => LogFormatter )
+#~ DOCGENERATOR_DEFAULT_LOGGER.trace = true
 
 =begin rdoc
-A 'global' parameter setting
+Each to_doc, to_html, to_latex, to_wiki, to_text has an option-parameter.
+
+This option-hash should contain at least a :log-value. 
+
+This method completes the option hash with a default logger and 
+returns a warning if no logger is given.
 
-For usage of
-    o = Docgenerator_logger.set_option_defaults(options)
+Usage:
+  def to_doc(target, options)
+    o = set_option_defaults(options)
     o[:log].debug("Enter ...") if o[:log].debug?
+    ...
+  end
+
 =end
-module Docgenerator_logger
-  #Each to_doc, to_html, to_latex, to_wiki, to_text has an option-parameter.
-  #This option-hash should contain at least a :log-value. 
-  #This method completes the option hash with a default logger if no logger is given.
-  def self.set_option_defaults(options)
+  def self.set_option_defaults(options, called_by = self)
+    if ! options[:log]
+      DOCGENERATOR_LOGGER.warn("Missing logger in set_option_defaults, use DOCGENERATOR_DEFAULT_LOGGER (#{called_by.inspect})") if DOCGENERATOR_LOGGER.warn?
+      DOCGENERATOR_LOGGER.debug("\n\t#{caller.join("\n\t")}") if DOCGENERATOR_LOGGER.debug?
+    end
     return {
-        :log  => DOCGENERATOR_LOGGER,
+        :log  => DOCGENERATOR_DEFAULT_LOGGER,
         #Added from Document:
         # :document   useable for documentation
         # :filename   useable for documentation
@@ -233,28 +331,22 @@ module Docgenerator_logger
         #- parent - actually used in list to detect */# for wiki-items.
       }.update(options)
   end
-end
-require 'docgenerator/standard'
-require 'docgenerator/element'
-
 =begin rdoc
-Returns an element of a type "name".
-Attributes and content are optional parameter.
+Instance-version of class method.
 =end
-def element( name, attr = {}, content = nil )
-	element = Element.get( name )
-	if element
-		element = element.new(attr, content ) if element
-	else
-		element = Element.create( name, {}, true  ).new(attr, content )
-		puts "Usage of undefined element #{name}"
-	end
-	return element
-end
+  def set_option_defaults(options)
+    Docgenerator.set_option_defaults(options, self)
+  end
+end #module Docgenerator
+
 
-require 'templates/docgenerator_template'
+require 'docgenerator/standard'
+require 'docgenerator/element_meta' #Meta-class definitions
+require 'docgenerator/element'  #includes definition of method 'element'
+#~ require 'docgenerator/compatibility_v1' #some old code
+require 'docgenerator/templates/docgenerator_template'
 require 'docgenerator/css'
-require 'templates/docgenerator_template_css'
+require 'docgenerator/templates/docgenerator_template_css'
 require 'docgenerator/attribute'
 require 'docgenerator/document'
 #~ require_relative 'docgenerator/document'
@@ -268,18 +360,16 @@ require 'docgenerator/footnote'
 require 'docgenerator/characters'	#special characters (spaces, euro-sign...)
 #~ require_relative 'docgenerator/characters'	#special characters (spaces, euro-sign...)
 
-__END__
-class Test
-	def required?(); true; end
+#quicktest
+if $0 == __FILE__  
+  #~ Docgenerator.trace_on
+  #~ el = element(:shyx)
+  #~ el = element(:img, {:width => '5px', :src => 'name' })
+  
+  doc = Docgenerator::Document.new()
+  doc.body << 'text'
+  #~ p doc.to_doc(:html, {:log => Docgenerator::DOCGENERATOR_DEFAULT_LOGGER})
+  #~ p doc.to_doc(:latex, {:log => Docgenerator::DOCGENERATOR_DEFAULT_LOGGER})
+  doc.save('xx.html')
 end
-test = Test.new()
-puts test.required?
-Test.class_eval('def required?(); false; end')
-puts test.required?
-
-testclass2 = Class.new( Test )
-test2 = testclass2.new()
-puts test2.required?
-testclass2.class_eval('def required?(); true; end')
-puts test2.required?
-puts test.required?
+__END__