docgenerator 1.1.1 → 1.2.1

data/lib/docgenerator/document.rb

@@ -0,0 +1,588 @@
+#encoding: utf-8
+=begin rdoc
+Container for a document.
+
+Each document contains a header and a body. Both are special Element classes.
+=end
+class Document
+  include Docgenerator  #get VERSION
+  
+  #Valid meta tags, used for HTML
+  #
+  #This meta-tags are used by sitegenerator
+  VALID_META_TAGS = %w{
+    keywords
+    description
+    id
+    altlang
+    toc
+    pdf
+    odp
+    amazon
+    forum
+    feed
+  }
+  class << VALID_META_TAGS
+    # Return true if self is part of the given parameter.
+    def ===(o)
+        return self.include?(o)
+    end
+ end
+    
+  #Create a new document.
+  #There are different document templates supported. 
+  #The templates refer to the corresponding TeX-classes.
+  #-  article
+  #-  report
+  #-  book
+  def initialize( settings = {} )
+    #Set template defaults
+    @template  = {
+      :html    => DocumentTemplate[:html],
+      :latex  => DocumentTemplate[:article],
+      :text    => DocumentTemplate[:text],
+      :wiki    => DocumentTemplate[:wiki],
+    }
+    @language  = 'ngerman' #default
+    @date  = nil
+
+    ##>>>>temporary check, old interface
+    #~ puts settings.inspect
+    if ! settings.is_a?(Hash)
+      #Make an exception to correct data
+      raise "Old interface for Document#new, use :template => "
+      settings = { :template => settings }
+    end
+    ##<<<<temporary check, old interface
+    
+    @log = settings[:log]
+    if ! @log
+      @log = Log4r::Logger.new( 'Doc', Log4r::WARN )
+      @log.outputters = Log4r::StdoutOutputter.new('log_xxx')
+    end
+    @meta  = {}  #some meta-Tags for HTML
+    @body  = element( :body, { :log => @log } )
+    @head  = element( :head, { :log => @log } )
+    #~ @body.part_of << self
+    #~ @head.part_of << self
+    @options  = []
+    #Flag to avoid double definition of docinfo()
+    @docinfo_called = false
+    @creator  = nil
+
+    settings.each{|key, value|
+      case key
+        when :title, :shorttitle, :author, :date, :keywords, :description, :creator, :language
+          self.send("#{key}=".to_sym, value)
+        #~ when :odp, :pdf, :amazon  #VALID_META_TAGS
+        when *VALID_META_TAGS.map{|mkey|mkey.to_sym}
+          self.meta( key, value )
+        when :template
+           [value].flatten.each{|template|
+                case template
+                  when DocumentTemplate
+                    @template[template.target] = template
+                  when Symbol
+                    templ = DocumentTemplate[template]
+                    if ! templ.is_a?( DocumentTemplate )
+                      @log.fatal("Unknown template #{template}, valid:\n\t#{DocumentTemplate.keys.join("\n\t")}") if @log.fatal?
+                    else
+                      @template[templ.target] = templ
+                    end
+                end 
+          } #templates
+        when :css
+          if ! File.exist?(value)
+            @log.warn("CSS-Reference not found (#{value})") if @log.warn?
+          end
+          #~ @head << element(:htmlonly,{}, <<css
+#~ <meta http-equiv="Content-Style-Type" content="text/css">
+#~ css
+#~ <link rel="stylesheet" type="text/css" href="#{value}">
+                    #~ ).cr
+          @head << element( :link, { 
+                      :href    => value,
+                      :rel    => 'stylesheet',
+                      :type  => "text/css" } ).cr. restrict_to(:html)
+        when :maketitle
+          #:maketitle is defined, but we have also to check, if it is true
+          @body << element(:maketitle ).cr if settings[key]
+        when :log
+        else
+          @log.warn("Document.new: Unknown setting #{key.inspect} (=#{value.inspect})") if @log.warn?
+      end
+    } #settings
+
+  end
+  #body and head are lists, containing elements.
+  attr_reader  :body, :head
+  attr_reader  :template
+  #Logger for the document
+  attr_reader  :log
+  #Document title
+  attr_accessor  :title, :shorttitle
+  #Set document description
+  attr_writer  :author, :date, :keywords, :description, :creator
+  attr_writer  :language
+  #Flag, if tex should be started immediate after document creation.
+  attr_writer  :runtex
+  #Add more keywords
+  def keyword_add( keyword )
+    @keywords << ", #{keyword}"
+  end
+
+  #Constant to detect the generated header
+  PREFIX_ENDFLAG = 'Generation-Info-End'
+  #
+  #Define, if there should be a message in case of:
+  #-:change  Document changed
+  #-:nochange  Document existed, but is unchanged
+  #Give an array with the wanted values.
+  def Document.givemessage=( value = [:change, :nochange] )
+    @@givemessage = value
+  end
+  @@givemessage = [:change, :nochange]
+  def Document.givemessage();  @@givemessage;  end
+  #Add a meta-tag-information for the HTML-Output.
+  def meta( key, content )
+    key  = key.to_s
+    
+    if ! VALID_META_TAGS.include?(key)
+      @log.warn("Unknown meta-tag #{key} (#{content})") if @log.warn?
+      @log.info("\tAllowed meta-tags: #{VALID_META_TAGS.join(', ')}") if @log.info?
+    end
+    if @meta[key]
+      @log.warn("Double definition meta-tag #{key} (old: #{@meta[key]}, new: #{content})") if @log.warn? and @meta[key] != content
+    end
+    
+    @meta[key] = content
+  end
+  #Prepare the docinfo.
+  #May be called only once.
+  #
+  #If the title should change (e.g. when you save the document twice in different versions)
+  #you can do it via the parameter.
+  def docinfo()
+    #If this method is called twice (e.g. with save to tex and html),
+    #then the title is doubled in the second output.
+    #(Elements are added to @head)
+    return nil if @docinfo_called
+    @docinfo_called = true
+    
+    #Build docinfo.
+    result = []
+    result << element( :title, {:short => shorttitle }, @title).CR if @title
+    result << element( :author, {}, @author).cr if @author
+    result << element( :date, {}, @date).cr if @date
+    result << element( :keywords, {}, @keywords).cr if @keywords
+    result << element( :metadescription, {}, @description).cr if @description
+    result << element( :creator, {}, @creator).cr if @creator
+    @meta.each{ |key, content|
+      result << element( :meta, { :name => key, :content => content } ).cr
+    }
+    return result
+  end
+  def add_option( option)
+    @options << option
+  end
+  #Prepare a table of content.
+  #
+  #There is no sense to use it with LaTeX, better you use \tableofcontents
+  #
+  #Options:
+  #- id: Id of div, needed for CSS-formatting
+  #- tocfilename: Added as prefix to link. 
+  #   can be used to make toc for in another file (cross-referencing)
+  #- level: Depth of toc
+  #The document should be filled before you add the toc.
+  #You an use Element#insertbefore:
+  #  doc.body.insertbefore(start, doc.toc)
+  def toc( options = {} )
+    opt = {
+      :id => 'toc',
+      :tocfilename => nil,  #Can be used to build cross references
+      :level  => 3,
+      :log  => @log
+    }.update(options)    
+
+    opt[:level] = 3 unless opt[:level]
+    opt[:log].info("Prepare Table of contents, options: #{options.keys.inspect}") if opt[:log].info?
+    opt[:log].debug("Options: #{[:id, :level, :tocfilename].map{|k| "#{k}: #{opt[k].inspect}"}.join(',')}") if opt[:log].debug?
+    
+    toc = element(:div, { :id => opt[:id] }).cR    
+    opt[:pre].is_a?(String) ? toc << element(:p, {}, opt[:pre] ).cr : toc << opt[:pre]
+    
+    toc_uls = [ toc ]
+
+    #fixme
+    #It would be nicer to get something like 1-1-1 instead of a counter.
+    toccnt  = 0
+    toc_ids = [ :chapter, :section,:subsection, :subsubsection, :paragraph, :subparagraph,:minisec]
+    @body.content.flatten.each{|el|
+if ! el.respond_to?(:ids)
+  #e.g. Wikitext. Has a to_doc, but doesn't react on flatten.
+  opt[:log].error("Toc: Element ohne :ids #{el.class}") if opt[:log].error?
+  next
+end  
+      depth = toc_ids.index((el.ids & toc_ids)[0])
+      next if ! depth #Element is no header
+      
+      opt[:log].debug("Toc: Found entry on level #{depth}: <#{el.content}>") if opt[:log].debug?
+      #Create an id if not already defined
+      if el[:id].content.empty?
+        el[:id] << "toc#{toccnt += 1}"
+      end
+      if depth > opt[:level]
+        opt[:log].debug("Toc: Reject by level #{el.content}") if opt[:log].debug?
+        next 
+      end
+
+      #Check missing levels
+      (depth - toc_uls.size).times{|i|
+        opt[:log].warn("Toc: Jump over section level #{depth-1+i} (#{opt[:tocfilename]})") if opt[:log].warn?
+        toc_uls << element(:ul, {}, element(:li ).cr ).cR
+        if toc_uls.size == 2 #First entry
+          toc_uls.first << toc_uls.last
+        else
+          toc_uls[-2].content.last << toc_uls.last
+        end
+      }
+      
+      #Build new toc-list and deletet bigger ones
+      if ! toc_uls[depth]
+        opt[:log].debug("Toc: Start new level #{depth}") if opt[:log].debug?
+        toc_uls << element(:ul).cR
+        if depth == 1
+          toc << toc_uls[depth]
+        else
+          toc_uls[depth -1 ].content.last << toc_uls[depth]
+        end
+      else  #delete levels under actual level
+        if toc_uls.slice!(depth+1..toc_uls.size+1)
+          opt[:log].debug("Toc: Stop level > #{depth}") if opt[:log].debug?
+        end
+      end
+      toc_uls[depth] << element(:li, {}, element(:a, {:href => "#{opt[:tocfilename]}##{el[:id]}" }, el.content ) ).cr
+    }
+    opt[:post].is_a?(String) ? toc << element(:p, {}, opt[:post] ).cr : toc << opt[:post]
+    
+    return toc
+  end #toc
+=begin rdoc
+Save the file.
+The type of the document is determined by the file extensison.
+Supported document types are:
+-  tex
+-  html
+-  (wiki)
+-  (text)
+Depending on a template, different results are created.
+
+There is a comparison between an already existing file and the new one.
+To write a new version, the document must change and overwrite must be true.
+
+Valid options:
+- :replacements
+   It is possible to give pairs of RegExp (pattern) and replacements to the result.
+- overwrite [true]
+   allows to overwrite 
+- target
+   In most cases this is defined by the extension.
+   Main usage will be for ConTeXt (shares the extension with LaTeX)
+- :additional_options 
+   List of options.
+   If you want to give parameters to specific 'Element'-objects you can define the keys here.
+   If you don't make it, you get warnings about undefined options.
+=end
+  def save( filename, options = {} )
+    #check old interface before 1.1.0
+    case options
+      when true, false
+        @log.warn( "Old interface for Document.save, use :overwrite => true/false" ) if @log.error?
+        options = { :overwrite => options }
+      end    
+      
+    options = {
+      :overwrite      => true, 
+      :replacements => {} ,
+      :additional_options => [],
+      :target   => nil,   #Will be set by extension
+      :runtex   => @runtex,
+    }.update(options)
+    
+    #Check valid options
+    options.each{|key,value|
+      case key
+        when :overwrite, :replacements, :target
+        when :additional_options
+        else
+          if options[:additional_options].include?(key)
+            @log.warn( "unknown option #{key.inspect} for Document.save" ) if @log.warn?
+          else
+            @log.debug( "Save-Specific option #{key.inspect} in Document.save" ) if @log.debug?
+          end
+      end
+    }
+    
+    if ! @template
+      @log.error( "No template available to create #{filename}" ) if @log.error?
+      return false
+    end
+    
+    prefix = [   nil, 
+        "Build by\t#{__FILE__}",
+        "Dir:\t\t#{Dir.pwd}",
+        "Creator:\t#{$0}",
+        "Target:\t\t#{filename}",
+        "#{Time.now.strftime('%Y/%m/%d %H:%M:%S')}",
+        nil,
+        "#{PREFIX_ENDFLAG}"
+      ].join("\n\t")
+    
+    #Determine the target document type, depending on extension.
+    extension = File.basename( filename ).split( /\./).last
+    case extension
+    when /tex/i
+      target  = :latex
+      #Take context if requested.
+      target  = :context if options[:target] == :context
+    when /miv/i #Mark IV
+      target  = :context
+    when /htm[l]?/i
+      target  = :html
+    when /txt/
+      target  = :text
+    when /wiki/
+      target = :wiki
+      target  = :creole if options[:target] == :creole
+    when /creole/
+      target  = :creole
+    else
+      @log.fatal( "Unknown Extension #{extension} for #{File.basename( filename )}" ) if @log.fatal?
+      raise "Unknown Extension #{extension}"
+    end
+    
+    #Check if the wanted target makes sense
+    case options[:target]
+      when nil #nothing predefined -> no check necessary
+      when target #Same as determined by extension -> no check necessary
+      else  #Requested target is another one.
+        @log.warn( "Target #{options[:target]} doesn't match extension. Recommended: #{target}" ) if @log.warn?
+        target = options[:target]
+    end
+    
+    #Create new version.
+    new = to_doc( target, {
+                    :template=> @template[target],
+                    :filename => filename,
+                    :replacements => options[:replacements],
+                    :log  => @log
+                    })
+    #Get previous content if available
+    old = nil
+    if File.exist?( filename )
+        #read the file. We expect to have the same encoding.
+        File.open(filename, 'r', :external_encoding => new.encoding){|f| old = f.read }
+        old = File.read(filename) unless old.valid_encoding?  #
+    end
+    prefix.encode!(new.encoding)  #for later sub...
+    case target
+    when :latex, :context
+      prefix.gsub!( /^/, '%' )
+      old.sub!(/\A.*#{PREFIX_ENDFLAG}/m, '<<prefix>>' ) if old
+    when :html
+      #Delete prefix (with generation time) for later compare.
+      old.sub!(/\A.*#{PREFIX_ENDFLAG}/m, "<!--\n<<prefix>>" ) if old
+    when :text
+    when :wiki
+    when :creole
+      #~ new.squeeze!("\n")
+    else
+      @log.fatal( "Unknown target #{target} for #{File.basename( filename )}" ) if @log.fatal?
+      raise "Unknown target #{target}"
+    end
+    #Make it a bit more compact.
+    #TeX requires at least 2 \n for paragraph changes
+    new.gsub!(/\n+\n\n/, "\n\n")
+    
+    if ! new.kind_of?( String )
+      @log.error( "New is wrong type: #{new.inspect}" ) if @log.error?
+    end
+    
+    if new != old
+      new.sub!( '<<prefix>>',  prefix)
+      if ( File.exist?( filename ) and ! options[:overwrite] )
+        puts "Datei #{filename} exist already \nContinue [yn]?"
+        answer = $stdin.gets()  if $stdin.tty? #only when called in a shell
+        if ! ( answer =~ /[YyjJ].*/ )
+          puts "Bye"
+          @log.info( "Overwrite #{filename} after confirmation" ) if @log.info?
+          return false
+        end
+      end  
+      File.open( filename, 'w', :external_encoding => new.encoding ){|f|
+        f << new
+      }
+      @log.info( "Save changed\t#{filename}") if @log.info?
+      puts "Save changed\t#{filename}"  if @@givemessage.include?(:change)
+      #Save copy of old version (attention, *.bak makes no control on tex or html)
+      #~ f = File.new( filename.sub( extension, 'bak'), 'w' )
+      #~ f << old
+      #~ f.close
+      Document.runtex( filename, options[:runtex] ) if options[:runtex] and [:latex, :context].include?(target)
+      return true
+    elsif old
+      @log.info("Unchanged\t#{filename}") if @log.info?
+      puts "Unchanged\t#{filename}" if @@givemessage.include?(:nochange)
+      return false
+    end    
+  end #Document#save
+=begin rdoc  
+Build the content for the target format.
+Supported target formats are:
+-  :latex
+-  :html
+-  :text
+If the standard templates are used, there is a <<prefix>> left 
+(used from Document#save to include some additional information).
+
+If the method is called directly to prepare document snipplets, you can use:
+  puts Document#to_doc( :latex, '<<body>>')
+
+It is possible to give pairs of RegExp (pattern) and a replacement to the result.
+=end
+  def to_doc( target, options )
+    #~ o = Docgenerator_logger.set_option_defaults(options)
+    options[:log].info( "Build document for #{target.inspect}" ) if options[:log].info?
+    template  = options[:template]
+    if ! template
+      options[:log].error( "No template available to create #{target.inspect} #{self.class}" ) if options[:log].error?
+      return ''
+    end
+    replacements = options[:replacements] || {}
+    options[:log].warn( "No filename given " ) if options[:log].warn? and ! options[:filename]
+
+    new = template.template
+    encoding = template.template.encoding
+    case target
+    when :latex
+      add_option( @language )
+    when :context
+      options[:log].warn( "Support for #{target} under development" ) if options[:log].warn?    
+    when :html
+    when :text
+    when :wiki
+    when :creole
+      options[:log].warn( "Support for #{target} under development" ) if options[:log].warn?
+    else
+      options[:log].fatal( "Unknown target #{target} for #{options[:filename]}" ) if options[:log].fatal?
+      return ''
+    end
+    if ! new.kind_of?( String )
+      options[:log].error( "New is wrong type: #{new.inspect}") if options[:log].error?
+    end
+
+    options[:document] = self
+    @head  << self.docinfo()
+    options[:log].debug( "Build header data") if options[:log].debug?
+    new.sub!( '<<head>>',  @head.to_doc(target, options ).encode(encoding))
+    options[:log].debug( "Build body") if options[:log].debug?
+    new.sub!( '<<body>>',  @body.to_doc(target, options).encode(encoding))
+    new.sub!( '<<classoptions>>',  @options.uniq.join(',').encode(encoding))
+    
+    
+    replacements.each{|pattern, replace |
+      options[:log].info("Replace text #{pattern.source} with #{replace}" ) if options[:log].info?
+      new.gsub!( pattern, replace ) if replace
+    }
+    return new
+  end  #Document#to_doc
+  #Return the actual target type.
+  #Needed by Element#to_s to decide which method is used to prepare the output.
+  #
+  #The usage of this technic makes similar processing unposibble.
+  #Set in Document#save.
+  attr_reader :target
+=begin rdoc
+Call rake4latex to translate the file.
+=end
+  def Document.runtex( filename, options = [:touch, :statistic, :clean])
+    if ! defined? Rake4LaTeX
+      puts <<warning
+Rake4LaTeX not loaded!
+Please use one of the following commands:
+  require 'rake4latex'
+  require 'rake4latex_latex'
+  require 'rake4latex_pdflatex'
+  require 'rake4latex_xelatex'
+  ...
+  Document.save(
+      :runtex => [:statistic, :clean]
+      #or with more options:
+      #:runtex => [:touch, :texerrors_allowed, :statistic, :clean]
+    )
+warning
+      begin
+        #interprete old interface before 1.2.0
+        gem 'rake4latex', '>= 0.1.2'
+        case options
+          when :latex; require 'rake4latex_latex'
+          when :pdflatex; require 'rake4latex_pdflatex'
+          when :xelatex; require 'rake4latex_xelatex'
+          else;  require 'rake4latex'
+        end #format
+        options = [:touch, :statistic, :clean]
+      rescue LoadError
+        puts "Sorry, I didn't find the rake4latex to translate #{filename}"
+        puts "I try to use the old 'RunTeX'"
+        runtex_old( filename, options[:format] )
+        return false
+      end unless defined? Rake4LaTeX
+    end # ! defined? Rake4LaTeX
+    
+    case options
+      when Array  #ok
+      when true; options = [:touch, :statistic, :clean]
+      else
+        options = [:touch, :statistic, :clean]
+        puts "Please change runtex-options to: #{options.inspect}"
+    end
+    #Taskname must be uniq for this file.
+    runtex = "Define TeX-task #{filename.ext('pdf')}"
+    rake4latex = Rake4LaTeX::Basefile.set(filename)#needed for clean...
+    rake4latex [:texerrors_allowed] = true  if options.delete(:texerrors_allowed)
+    rake4latex[:loglevel] = Log4r::WARN
+    
+    if options.delete(:touch)
+      task :touch => filename.ext('tex')
+      task runtex => :touch   
+    end   #if options.delete(:touch)
+    task runtex => filename.ext('pdf')
+    task runtex => options
+    
+    Rake.application[runtex].invoke
+    options.each{|option| Rake.application[option].reenable }
+  end
+=begin rdoc
+Make some basic replacements for TeX.
+There is no sense to use it with HTML.
+
+Better solution: Puts String into \path, \verb or similar.
+=end
+  def Document.texify( input )
+    out = input.strip
+    #~ out.gsub!( /&/, '\\\&')  #geht schief. erzeugt <<body>>...
+    #~ out.gsub!( /\\/, '\\\\')
+    out.gsub!( /%/, '\%')
+    out.gsub!( /\$/, '\$')
+    out.gsub!( /&/, '\\\\&')
+    out.gsub!( /_/, '\_')
+    out.gsub!( /#/, '\#')
+    out.gsub!( /€/, '\euro ')
+    return out
+  end
+  def inspect()
+    return "#<Document '#{@title}'>"
+    #~ return "#<Document '#{@title} #{@body.inspect}>'"
+  end
+end  #Document