docgenerator 2.0.0 → 2.1.0

data/meta_test_and_doc/build_doc.rb

@@ -0,0 +1,333 @@
+=begin rdoc
+Build manpages for docgenerator.
+=end
+require_relative 'build__meta'
+$log = Log4r::Logger.new('doc')
+$log.outputters << Log4r::StdoutOutputter.new('stdout')
+
+DOCHEADER = <<xx
+=begin rdoc
+Generated manpages for elements.
+
+This document does not contain the implementation or code documentation.
+
+This document is the source for a manpage for usage of Docgenerator elements.
+
+The following Element are documented in this document:
+xx
+
+=begin rdoc
+Prepare a documentation, based on execution and meta-analyse.
+=end
+def mk_element_doc(elementlist, filename )
+  
+  rd_code = [
+    DOCHEADER,
+    list_of_elements = [],
+    "=end\n\n#"
+  ]
+  $log.info("Prepare #{filename}")
+  
+  elementlist.each{|cl|
+    list_of_elements << "* #{cl.name}"
+    
+    names = cl.name.to_s.split('::')
+    class_name = names.pop
+    ident = ''
+    names.each{|name|
+      rd_code << "#{ident}module #{name}"
+      ident << "  "
+    }
+    rd_code << "=begin rdoc"
+    rd_code << mk_element_manpage(cl)
+    rd_code << "=end"
+    
+    rd_code << "#{ident}class #{class_name}"
+    rd_code.last << " << #{cl.ancestors[1]}"  #add ancestor 
+    rd_code << "#{ident}#This coding is empty - this is the manpage definition, not the implementation"
+    rd_code << "#{ident}end #class #{class_name}"
+    names.reverse.each{|name|
+      ident.slice!(0..1)
+      rd_code << "#{ident}end #module #{name}"
+    }
+
+
+  } #Element.each 
+
+  File.open(filename, 'w:utf-8'){|f_test|
+    $log.info("Create #{f_test.path}")
+    f_test << "#encoding utf-8\n"
+    f_test << rd_code.join("\n")
+  }
+
+end #mk_element_doc
+
+=begin rdoc
+Create rdoc-code for element.
+
+The documentation for the methods to_latex, to_html... is added 
+to the class.
+
+We could put the documentation to the methods, but rdoc will take only 
+the documentation of the first definition.
+Class documentation is added to the existing implementation documentation.
+=end
+def mk_element_manpage(cl)
+    
+    $log.info("Create manpage content for #{cl.name}")
+    log = Log4r::Logger.new('log', Log4r::WARN) #avoid message
+    log.outputters = logoutputter = ArrayOutputter.new('xx')    
+    rd_code = []
+    el = cl.new(:log => log )
+    rd_code << <<code    
+=#{cl.name}
+code
+
+#See also ::#{cl.name}
+
+    if el.attr.empty?
+      rd_code<< "#{cl.name} does not contain attributes"
+    else
+      #
+      # Attribute overview has three variants:
+      # - tab -- does not work
+      # - tab_ascii
+      # - list -- very long, bad vor overview -> not used
+      rd_code<< "==Attributes"
+      rd_code << mk_attr_overview(:tab_ascii, el.attr, el)
+      #~ rd_code << mk_attr_overview(:tab, el.attr)
+      #~ rd_code << mk_attr_overview(:list, el.attr)
+    end
+    
+    rd_code<< "\n"
+    #~ rd_code<< "==Content"
+    if el.content?
+      el << 'content'
+      rd_code<< "#{cl.name} can contain content."
+    else
+      rd_code<< "#{cl.name} allows no content."
+    end
+    
+    rd_code<< "\n==Generate an object"
+    cmd = "  test = #{el.class}.new( "
+    if ! el.attr.empty?
+      cmd << "{"
+      el.attr.sort_by{|k,a| a.sortkey }.each{|k,a|
+        #~ cmd << "\n      #{k.inspect} => #{a.content.empty? ? "''" :  a.content.inspect}, #" 
+        cmd << "\n       %s%-20s => <<value>>, %% %s%s" % [ 
+                                      a.required? ? " " :  '#',
+                                      k.inspect,
+                                      #~ a.content.empty? ? "''" :  a.content.inspect,
+                                      a.required? ? "required" :  'optional',
+                                      a.allowed_values ? ", values: #{a.allowed_values.inspect}" : '',
+                                  ]
+      }
+      cmd << "\n      }"
+    else
+      cmd << "{}" if el.content?
+    end
+    cmd << ", 'content'" if el.content?
+    cmd << ")"
+    
+    #~ cmd << "\n  test << #{el.content.inspect}" if el.content?
+    
+    cmd << "\n\nAlternative generation\n"
+    el.element_ids.each{|id|
+      cmd << "  test = element(#{id.inspect}"
+      if el.attr.empty?
+        cmd << ", {}" if el.content?
+      else
+        cmd << ", {...Attributes...}" 
+      end
+      cmd << ", 'content' " if el.content?
+      cmd << ")\n"
+    }
+    rd_code << cmd
+  
+  
+    rd_code<< "\n==Outputs"
+    
+    
+    %w{latex html context text wiki creole}.each{|target|
+      check_cr = true #Is it necessary to check #cr, 'Cr...
+
+      el2 = el.dup  #later check with cr, cR... would modify the result
+      
+      logoutputter.flush  #clear messages
+      result = el.send("to_#{target}".to_sym, :log => log)
+      rd_code<< <<code
+===#{cl.name}#to_#{target}
+#{result.gsub(/^/, "  ")}
+code
+    logoutputter.flush.each{|message|
+      case message
+        when /(Missing output routine for .*)\(/
+          rd_code << "* No output routine defined for #{target} - use a dummy"
+          check_cr = false
+        when /No related document for tableofcontents/
+        when %r{ERROR log: :li/wiki: Unknown list type nil}
+        when /multicolumn without latex-position/  #Docgenerator::Tables::Multicolumn
+        else
+          $log.error("Uncatched message: #{message.strip} for #{cl.name}")
+      end
+    } #logoutputter.flush
+
+    #try different cr-commands
+    if check_cr
+      rd_code << <<code
+====:cr, :cR, :Cr, :CR for #{cl.name}#.to_#{target}
+<<START>> and <<END>> are not part of the output, but needed to illustrate the line breaks.
+
+Default:
+#{"<<START>>#{result}<<END>>".gsub(/^/, "  ")}
+code
+      [ :cr, :cR, :Cr, :CR ].each{| cr |
+        el2.send(cr)
+        result2 = el2.send("to_#{target}".to_sym, :log => log)
+        
+        if result == result2
+          rd_code << "* #{cl.name}##{cr} has no effect, same result as default"
+        else
+          rd_code << <<code
+* Result after #{cl.name}##{cr}:
+
+#{"<<START>>#{result2}<<END>>".gsub(/^/, "    ")}
+code
+        end
+      } #different cr-commands
+    end
+  } #targets    
+ rd_code
+end #mk_element_manpage
+
+def  mk_attr_overview(variant, attr, el)
+  tab = element(:tabular, columns: 10).Cr
+  tab << row = element(:row ).cr
+  row << element(:th, {}, 'Name')
+  row << element(:th, {}, 'required?')
+  row << element(:th, {}, 'HTML')
+  row << element(:th, {}, 'LaTeX')
+  row << element(:th, {}, '~keyval')
+  row << element(:th, {}, 'ConTeXt')
+  row << element(:th, {}, 'Text')
+  row << element(:th, {}, 'Wiki')
+  row << element(:th, {}, 'Creole')
+  row << element(:th, {}, 'Values')
+
+  tab_ascii = ['  ']  #two spaces to get a ASCII-Tabular layout
+  tab_ascii.last << '%-20s  ' % 'Attribute'
+  tab_ascii.last << "%-10s" % 'required?'
+  tab_ascii.last << "%-10s" % 'HTML'
+  tab_ascii.last << "%-10s" % 'LaTeX'
+  tab_ascii.last << "%-10s" % '~keyval'
+  tab_ascii.last << "%-10s" % 'ConTeXt'
+  tab_ascii.last << "%-10s" % 'Text'
+  tab_ascii.last << "%-10s" % 'Wiki'
+  tab_ascii.last << "%-10s" % 'Creole'
+  tab_ascii.last << "%-10s" % 'Values'
+  tab_ascii << '  ' + "=" * 100
+  
+  list = ['Attribute List:']
+
+  attr.sort_by{|k,a| a.sortkey }.each{|k,a|
+    ##fixme element(:radic) statt 'X'? -> http://www.google.de/url?sa=t&rct=j&q=rdoc%20table%20hanna&source=web&cd=1&ved=0CGoQFjAA&url=http%3A%2F%2Fforum.ruby-portal.de%2Fviewtopic.php%3Ff%3D6%26t%3D12387&ei=92PYT8COD4TFswah7fGeDw&usg=AFQjCNFw0KuMKykdsgCpASxRtvaybkG6GA
+    tab << row = element(:row).cr
+    row << element(:col, {}, k.inspect)
+    row << element(:col, {}, a.required? ? 'X' : '-' )
+    row << element(:col, {}, a.html? ? 'X' : '-' )
+    row << element(:col, {}, a.latex? ? 'X' : '-' )
+    row << element(:col, {}, a.texkeyval? ? 'X' : '-' )
+    row << element(:col, {}, a.context? ? 'X' : '-' )
+    row << element(:col, {}, a.text? ? 'X' : '-' )
+    row << element(:col, {}, a.wiki? ? 'X' : '-' )
+    row << element(:col, {}, a.creole? ? 'X' : '-' )
+    
+    list << "* #{k}:"
+    tab_ascii << "  %-20s: " % k
+    %w{required html latex texkeyval context text wiki creole}.each{|key|
+      list << "  * #{key}: #{ a.send("#{key}?".to_sym) ? 'X' : '-' } "
+      tab_ascii.last << " %-9s" % (a.send("#{key}?".to_sym) ? 'X' : '-')
+    }
+    
+    #~ rd_code  << "===Attribute #{k.inspect}"
+    if a.required?  
+      #this may give an error, if the attribute has wrong type/layout...
+      el[k] << "Value for #{k}"
+      #~ rd_code  << "* required"
+    #~ else
+      #~ rd_code  << "* optional"
+    end
+    #~ rd_code  << "* used for:"
+    #~ rd_code  << "  * HTML" if a.html?()
+    #~ rd_code  << "  * LaTeX" if a.latex?()
+    #~ rd_code  << "  * LaTeX as key-val parameter" if a.texkeyval?()
+    #~ rd_code  << "  * ConTeXt" if a.context?()
+    #~ rd_code  << "  * text" if a.text?()
+    #~ rd_code  << "  * wiki (wikimedia)" if a.wiki?()
+    #~ rd_code  << "  * wiki (creole)" if a.creole?()
+
+    row << col = element(:col)
+    if a.allowed_values
+      col << ul = element(:ul)
+      #~ rd_code  << "* Allowed values:"
+      a.allowed_values.each{|x|
+        ul << element(:li,{}, x.inspect)
+        #~ rd_code  << "  * #{x.inspect}"
+      } 
+    end
+  }
+  
+  case variant
+    when :tab
+      tab.to_html(:log=> log)# does not work correct
+    when :tab_ascii
+      tab_ascii
+    when :list
+      list  #very long
+    end
+  
+end #mk_attr_overview
+
+
+desc "Create all manpages"
+task :all_man_files
+#Build single file tasks
+#Create file task
+FILE_SEPARATION.each{|key, elementlist|
+  filename = File.join('manpages', key)
+  file filename do |tsk| mk_element_doc(elementlist, tsk.name); end #Create file task
+  task :all_man_files => filename #add file task as prerequisite to :all_man_files
+}
+
+task :force
+task :clean do
+  Rake.application[:all_man_files].prerequisites.each{|f| 
+    File.delete(f) if File.exist?(f)
+  } 
+end
+
+task :rdoc_manpages do
+  STDOUT.flush
+  FileUtils.rm_r('doc') if File.exist?('doc')
+  `rdoc -f hanna manpages/readme.rdoc manpages/*.rb  -m manpages/readme.rdoc -o doc -t "manpages for docgenerator"`
+end
+
+
+#~ task 'manpages/environments.rb' => :force
+#~ task :default => 'manpages/environments.rb'
+#~ task 'manpages/sectioning.rb' => :force
+#~ task :default => 'manpages/sectioning.rb'
+#~ task 'manpages/elements.rb' => :force
+#~ task :default => 'manpages/elements.rb'
+#~ task 'manpages/characters.rb' => :force
+#~ task :default => 'manpages/characters.rb'
+
+#~ task :default => :test
+task :default => :clean
+task :default => :all_man_files
+#~ task :default => :rdoc_manpages
+
+if $0 == __FILE__
+  app = Rake.application
+  app[:default].invoke
+end

data/meta_test_and_doc/build_test.rb

@@ -0,0 +1,251 @@
+#encoding: utf-8
+=begin
+Generates new versions for test.
+
+Generates:
+* loop over all elements
+* create an element
+* make a test output and create unit tests for the elemnt.
+
+The resultof this process is not a test for correctness,
+but a test of "state of the art".
+
+Effects of changes may be checked wih the result of this test.
+
+Approved tests may be transferred as real unit tests.
+=end
+
+#~ Dir['lib/**/wiki*/*'].each{|file| puts "require '#{file}'".sub(/lib\//,'') }
+#~ exit
+require_relative 'build__meta'
+$log = Log4r::Logger.new('testgenerator')
+$log.outputters << Log4r::StdoutOutputter.new('stdout')
+
+#Header for testfiles
+TESTHEAD = <<testhead
+#encoding: utf-8
+
+=begin rdoc
+Test generated by #{__FILE__} #{Date.today}
+
+This is not a 'real' test unit.
+The tests are created with #{__FILE__}:
+1) Each Element is taken and field.
+=end
+
+gem 'test-unit'
+require 'test/unit'
+
+if $0 == __FILE__
+  #Add lib, two insertions, depending on target directory level
+  $:.unshift("../lib")
+  $:.unshift("../../lib")
+end
+require 'docgenerator'
+#~ DOCGENERATOR_LOGGER.level = Log4r::DEBUG
+
+=begin rdoc
+Define a new outputter to catch data into an array
+=end
+class ArrayOutputter < Log4r::StdoutOutputter
+=begin rdoc
+Collect messages in array.
+=end
+  def write(message)
+    @messages ||= []  #create with first call
+    @messages  << message
+  end
+=begin rdoc
+Clear message array and return messages
+=end
+  def flush
+    @messages ||= []  #create with first call
+    messages = @messages.dup
+    @messages.clear
+    messages
+  end
+end #ArrayOutputter
+
+testhead
+
+=begin rdoc
+Create a unit-test file.
+=end
+def mk_element_test(elementlist, filename, requirements )
+  
+  testcode= []
+  elementlist.each{|cl|
+    $log.info("Create test for #{cl.name}")
+    testcode << mk_element_testcase(cl)
+  }
+
+  File.open(filename, 'w:utf-8'){|f_test|
+    puts "Create #{f_test.path}"
+    f_test << TESTHEAD
+    f_test << "require '#{requirements}'\n" if requirements
+    f_test << testcode.join("\n")
+  }
+  #~ puts testcode.join("\n")
+  
+end #mk_element_test
+
+=begin rdoc
+=end
+def mk_element_testcase(cl)
+    testclass = "Test_element_#{cl.name.downcase.gsub(/::/, '_')}"
+    testcode = []
+    case cl.name
+      when /::Characters::/
+        loglevel = Log4r::INFO
+      else
+        loglevel = Log4r::DEBUG
+    end
+    
+    @@log = Log4r::Logger.new(cl.element_ids.first.to_s, loglevel)
+    @@log.outputters = @@logoutputter = ArrayOutputter.new('xx')
+    @@el = cl.new(:log => @@log )
+    
+    testcode << <<code
+=begin rdoc
+Test #{cl.name}.
+=end
+class #{testclass} < Test::Unit::TestCase
+  def self.startup()
+    @@log = Log4r::Logger.new('#{cl.element_ids.first.to_s}', Log4r::#{Log4r::LNAMES[loglevel]})
+    @@log.outputters = @@logoutputter = ArrayOutputter.new('xx')
+    @@el = #{cl.name}.new(:log => @@log)
+code
+      @@el.attr.sort_by{|k,a| a.sortkey}.each{|k,a|
+        #this may give an error, if the attribute has wrong type/layout...
+        @@el[k] << "Attr_#{k}" if a.required? 
+        testcode  << "%s   @@el[%-10s] << %-20s #%s attribute" % [
+          a.required?  ? '  ' : '#~',#only as template for optional values
+          k.inspect,
+          "'Attr_#{k}'",  #Part of content
+          a.required?  ? 'required' : 'optional',
+        ]
+      }
+      
+      if @@el.content?
+        @@el << 'content'
+        testcode<< "    #fill content"
+        testcode<< "    @@el << 'content'"
+      else
+        testcode<< "    #element allows no content"
+      end
+      
+      testcode<< "    #Store log messages"
+      testcode<< "    @@messages = @@logoutputter.flush"
+    #test log-content
+    @@messages = @@log.outputters.first.flush
+    testname = "test_element_#{cl.name.downcase.gsub(/::/, '_')}_log"
+    
+    testcode<< <<code
+    end #self.startup()
+=begin rdoc
+Check messages from logger.
+This may include warnings for wrong content format...
+
+The following messages are expected:
+#{@@messages.to_yaml}
+=end
+  def #{testname}
+    assert_equal(
+      #{@@messages.inspect},
+      @@messages
+    )
+  end ##{testname}
+code
+    %w{latex html context text wiki creole}.each{|target|
+        testname = "test_element_#{cl.name.downcase.gsub(/::/, '_')}_#{target}"
+        result = @@el.send("to_#{target}".to_sym, :log => @@log)
+        
+#~ The target #{target} is #{@@el.send("#{target}?".to_sym) ? '' : 'not' } supported for #{cl.name}
+        testcode<< <<code
+=begin
+Test #{cl.name}#to_#{target}.
+=end
+  def #{testname}()
+    assert_equal(
+code
+        testcode.last.sub!(/\n$/,'') #remove newline of last entry
+        #Problem:
+        if result.count("\n") < 2 #one-line result  in short version
+          #\u (\url...) wird als Unicode-eingabe interpretiert. Desahlb muss \ maskiert werden.
+          testcode<< "      #{result.inspect.gsub(/\\/, '\\\\')}," 
+        else  #mehrzeilig
+=begin
+Problem: %{inhalt} macht Probleme bei Strings mit { und }
+<<<xx fügt leerzeichen ein, komma für nächste Parameter geht auch nicht.
+=end
+          testcode<< "      %Q{#{result.gsub(/\\/, '\\\\\\\\')}},"  #mehrzeilig
+          #~ testcode<< "#~ <<result" 
+          #~ testcode<< @@el.send("to_#{target}".to_sym).gsub(/\\/, '\\\\\\\\').gsub(/^/, '#~ ')
+          #~ testcode<< "#~ result"
+        end
+        testcode<< "      @@el.to_#{target}( :log => @@log).encode('utf-8')"
+        testcode<< "    )"
+        
+        messages = @@logoutputter.flush
+        if messages.empty?
+          testcode<< "    assert_equal([],@@logoutputter.flush, 'No messages expected')"
+        else
+          testcode<< <<code
+    #Check messages from #{cl.name}#to_#{target}. 
+    assert_equal([
+        #{messages.map{|m| m.inspect}.join(",\n        ")}
+      ], @@logoutputter.flush
+    )
+code
+        end
+        testcode<< "  end ##{testname}"
+    }
+      testcode<< "end ##{testclass}"
+      testcode
+end # mk_element_testcase(cl)    
+
+
+desc "Create all test files"
+task :all_test_files
+
+#Create file tasks
+FILE_SEPARATION.each{|key, elementlist|
+  filename = File.join('unittest', "unittest_#{key}")
+  file filename do |tsk| mk_element_test(elementlist, tsk.name, FILE_SEPARATION_REQUIREMENTS[key] ); end  #Create file task
+  task :all_test_files => filename  #add file task as prerequisite to :all_test_files
+}
+
+task :force
+task :clean do
+  Rake.application[:all_test_files].prerequisites.each{|f| 
+    File.delete(f) if File.exist?(f)
+  } 
+end
+
+require 'knut_tools/rake/testtask.rb'
+Rake::TestTask.new(:run_tests) do |t|
+    t.dir = 'unittest'
+    t.libs << '../lib'
+    t.libs << '../../lib'
+    t.test_files = FileList['unittest*.rb']
+    t.verbose = true
+end
+  
+task :default => :clean
+task :default => :all_test_files
+#~ task :default => :run_tests
+
+if $0 == __FILE__
+  app = Rake.application
+  app[:default].invoke
+end
+
+#~ puts_elements
+
+__END__
+fixme:
+- tests mit #cr...
+- optionale attribute
+- testdaten in DB? (verschiedene Attributesausprägungen?)
+
+