docgenerator 1.2.1 → 2.0.0

data/lib/docgenerator/element.rb

@@ -1,239 +1,46 @@
 #encoding: utf-8
-#This class defines possible elements of a document.
-#For each type of elements a class is defined.
-#The definition can be done explicite or generic with Element.create.
-#
-#All types of elements are stored in a hash, 
-#the elements can be created via the method Element.get (or element() ).
-#
-#Tracing
-#Often there is the problem, that you get an error when you write the element.
-#But the error is done, when the element is created.
-#When you redefine ELEMENTS_TRACE, some tracing information are stored during creation.
+
+# 
+
+module Docgenerator 
+=begin rdoc
+This class defines possible elements of a document.
+For each type of elements a class is defined.
+The definition can be done explicite or generic with Element.create.
+
+All types of elements are stored in a hash, 
+the elements can be created via the method Element.get (or element() ).
+
+Tracing
+Often there is the problem, that you get an error when you write the element.
+But the error is done, when the element is created.
+When you redefine ELEMENTS_TRACE, some tracing information are stored during creation.
+=end
 class Element
   include Docgenerator  #get VERSION
-  #Hash with all ids and their corresponding classes.
-  @@ids = Hash.new( )
-  #All attributes are stored in this hash.
-  #The key is the corresponding class.
-  @@attr  = { Element => {} }
-
-  #Flag, if the calling stack should be analysed for each Element
-  #Only for document debbuging
-  @@trace  = nil
-  #Set Element tracing on/off
-  def Element.trace=( val )
-    @@trace = val
-  end
 
   SUPPORTED_TARGETS = [ :latex, :html, :wiki, :text, :debug ]
   SUPPORTED_TARGETS << :context #Added later
   SUPPORTED_TARGETS << :creole #Added later
-  
 
-  #Return a element class.
-  def Element.get( name )
-    return @@ids[name]
-  end
-  #This method is called, when a subclass of this class is defined.
-  #This can happen via Element.create or in another programm.
-  #
-  #Add subclasses to the list of all element classes and initialize some internal hashes.
-  def Element.inherited( subclass )
-    DOCGENERATOR_LOGGER.debug("New subclass for 'Element' created: '#{subclass}'") if DOCGENERATOR_LOGGER.debug?
-    #All attributes of a class are collected in a hash.
-    @@attr[subclass]  = {}
-    #Fill @@ids
-    #There is no possibility to give a list of id's or names to a 'inherit'-method.
-    #So a special method Element.add is used.
-    Element.add( [subclass], subclass )
-  end
-  #Add a new element class or assign another name (synonym) for a class.
-  #The initial call is made by Element.inherited.
-  #
-  #Element.add( [:element],  Element )
-  def  Element.add( idlist, elementClass )
-    if ! elementClass.new.kind_of?( Element )
-      raise "Element.add get no Element-class #{elementClass}"
-    end
-    idlist = [ idlist ] if ! idlist.kind_of?( Array )
-    raise "Empty idlist for #{elementClass}" if idlist.empty?
-    
-    idlist.each{|id|
-      if @@ids[ id ] == nil
-        DOCGENERATOR_LOGGER.debug("Element class '#{id}' is new: #{elementClass}") if DOCGENERATOR_LOGGER.debug?
-        #All new ids are collected
-        @@ids[ id ] = elementClass
-      elsif  @@ids[ id ] == elementClass
-        DOCGENERATOR_LOGGER.warn("Element class '#{id}' is defined double: #{elementClass}") if DOCGENERATOR_LOGGER.warn?
-      else
-        DOCGENERATOR_LOGGER.error("Error: ID '#{id}' is redefined #{@@ids[id]} -> #{elementClass}") if DOCGENERATOR_LOGGER.error?
-        @@ids[id] = elementClass
-      end
-    }
-  end
-  
-  #Generic creation of a new class to define a new element.
-  #-  name must be defined.
-  #-  attr is a hash with all attributes.
-  #  For details see Element.add_attributes
-  #-  content is a flag, which defines if the element contains "content".
-  #  Valid values are:
-  #  -  true:  content available and necessary (e.g. <p>)
-  #  -  :empty_ok: content available, but not necessary (e.g. <td> or iframe)
-  #  -  false:  no content, no endtag, but tag closed with / (example: <br />)
-  #  -  nil:    no content, no endtag, no closing  (example: <br>)
-  #-  output contains a hash with logic, how to handle the output.
-  #  -:htmltag  Tag for html-output.
-  #  -:latex  Template for LaTeX-output
-  #  -:html    Template for HTML-output
-  def  Element.create( name, attr = {}, content = false, output = {} )
-    #First some checks
-    if ! attr.kind_of?( Hash )
-      raise "Type error Element.create: Expected Hash, get #{attr.class}"
-    end
-    #Generic class creation
-    elementclass = Class.new( Element )
-    #Add the id of the new class to central collection.
-    Element.add( name, elementclass )
-
-    #Set a flag, if the class can contain 'content'.
-    #-true:  content available and necessary (e.g. <p>)
-    #-:empty_ok: content available, but not necessary (e.g. <td>)
-    #-false:  no content, no endtag, but tag closed with / (example: <br />)
-    #-nil:    no content, no endtag, no closing  (example: <br>)
-    elementclass.class_eval( %Q|
-      def content?()
-        return #{content.inspect}
-      end|)
-    
-    output.each{ |k,v|
-      case k
-      when :latex
-        elementclass.add_output( :latex,  v )
-      when :context
-        elementclass.add_output( :context,  v )
-      when :html
-        elementclass.add_output( :html,  v )
-      when :text
-        elementclass.add_output( :text,  v )
-      when :wiki
-        elementclass.add_output( :wiki,  v )
-      when :creole
-        elementclass.add_output( :creole,  v )
-      when :htmltag
-        if v
-          elementclass.class_eval( "def htmltag()\n'#{v}'\nend" )
-        else
-          elementclass.class_eval( "def htmltag()\nnil\nend" )
-        end
-      else
-        puts "#{__FILE__}##{__LINE__}: Unknown format #{k} for #{name}"
-      end
-    }
-    elementclass.add_attributes( attr )
-    #Return the class.
-    return elementclass
-  end
-  #Return all id's of the class.
-  #@@ids is expanded in Element.add.
-  def ids( )
-    myids = []
-    @@ids.each{|k,v| myids << k if v == self.class and k.class != Class }
-    return myids
-  end
-  #Prepares an overview on all Elements.
-  #Can be used for some debugging.
-  def Element.overview( list = @@ids.values.uniq )
-    if ! list.kind_of?(Array)
-      list = [ list ]
-    end
-    result = '=' * 10 + "\nElement overview:"
-    list.each{ |k|
-      result += "\n#{k}\n"
-      result += "\tId's:\t\t"
-      result += k.new.ids.join("\n\t\t\t")
-      result += "\n\tAttributes:\t"
-      result += "can contain "
-      result += "no " if ! k.new.content?
-      result += "content\n\t\t\t"
-      @@attr[k].each{ |k2,v|
-        result += "#{k2}:\t#{v.inspect}\n\t\t\t"
-      }
-    }
-    return result
-  end
-  #Add possible attributes to an element class.
-  #Attributes are defined in a hash, each key get a array with values.
-  #The values can be:
-  #-  OBLIGATORY/OPTIONAL
-  #-  Alias (this allows the usage of a position and a name for a parameter).
-  #-  allowed elements ( e.g. list content only list items)
-  #Problem: Attributes are not inherited. See Element.get_attribute_list
-  #
-  #This method is called from a subclass. 
-  #Fixme: add_attributes overwrites everything.
-  def Element.add_attributes( attr )
-    elattr  = @@attr[self]  #self is the class 
-    attr.each{ |k,a |
-      elattr[k] = a
-    }
-  end
-  #Returns list of attributes.
-  #Can be used for copying attributes from one class to another class.
-  def Element.get_attribute_list( elementclass )
-    return @@attr[elementclass]
-  end
-  #Add an output routine.
-  def Element.add_output( target, string )
-    case target
-    when :latex
-      cmd = "def to_latex(options = {})\n"
-    when :context
-      cmd = "def to_context(options = {})\n"
-    when :html
-      cmd = "def to_html(options = {})\n"
-    when :text
-      cmd = "def to_text(options = {})\n"
-    when :wiki
-      cmd = "def to_wiki(options = {})\n"
-    when :creole
-      cmd = "def to_creole(options = {})\n"
-    else
-      puts "#{self}: Undefined target format #{target}"
-    end
-    if ! string.kind_of?( String )
-      puts "Error element <#{self.new.ids}>: #{string.inspect} is no String"
-    end
-    cmd << <<code
-    o = Docgenerator_logger.set_option_defaults(options)
-    o[:log].debug("enter to_doc(#{target}) for #{self.inspect}, options: \#{options.keys.inspect}") if o[:log].debug?
-code
-    template = string.gsub(/\\/, '\\\\\\')
-    template.gsub!(/"/, '\"')
-    template.gsub!(/@content\}/, "@content.to_doc(#{target.inspect}, o)}")
-    cmd << "    \"#{template}\"\n"
-    cmd << "end\n"
-    class_eval( cmd )
-    cmd #return cmd for unit test
-  end
-  #Defines an element.
-  #
-  #There are two ways to add values:
-  #-  "named" values in an hash.
-  #  This named values can be attributes of a HTML-Tag or Parameters of a TeX-Makro.
-  #  There is a check, if the attribute exist.
-  #-  Content. Values "inside" the element.
-  #  The content can be the content of a HTML-Tag or the content of a TeX-Environment.
-  #  There is a check, if this class allows content.
-  #:log is the default attribute for the logger.
-  #In Element#to_doc you can give another logger!
+=begin rdoc
+Defines an element.
+
+There are two ways to add values:
+-  "named" values in an hash.
+  This named values can be attributes of a HTML-Tag or Parameters of a TeX-Makro.
+  There is a check, if the attribute exist.
+-  Content. Values "inside" the element.
+  The content can be the content of a HTML-Tag or the content of a TeX-Environment.
+  There is a check, if this class allows content.
+:log is the default attribute for the logger.
+In Elementto_doc you can give another logger!
+=end
   def initialize( attr={}, content = nil)
     #@attr is a hash containing the values for each attribute.
     @attr = Hash.new(  )
-    #~ @log  = DOCGENERATOR_LOGGER
     #Attention! in to_doc another logger may be given.
-    @log  = attr[:log] ? attr[:log] : DOCGENERATOR_LOGGER
+    @log  = attr[:log] || DOCGENERATOR_DEFAULT_LOGGER
     attr.delete(:log) #remove from attr-interface
     #attr alias
     @attr_alias = Hash.new(  )
@@ -252,7 +59,7 @@ code
     @suppressed_targets = []
     
     #Initialize the attribute hash.
-    @@attr[self.class].each{ |k,a|
+    self.class.attributes.each{ |k,a|
       #type check on Attribute does not work .
       if a.kind_of?( Symbol )
         #Filled in the second run
@@ -264,7 +71,7 @@ code
       end
     }
     #Assign Alias-Attributes
-    @@attr[self.class].each{ |k,a|
+    self.class.attributes.each{ |k,a|
       next if !a.kind_of?( Symbol )
       if @attr[a]
         @attr_alias[k] = @attr[a]
@@ -279,20 +86,59 @@ code
       elsif @attr_alias[k]
         @attr_alias[k] << v
       else
-        @log.warn("Usage of unknown attribute '#{k}' in '#{self.ids.join(',')}'") if @log.warn?
+        @log.warn("Usage of unknown attribute '#{k}' in #{self.inspect}") if @log.warn?
+        #~ @log.debug(caller) if @log.debug?
       end
     }
-    @called_by = prepare_tracing_info( @@trace )
+    #store info, where the element was created 
+    @creation_caller = prepare_tracing_info() if Docgenerator.trace_on?
     self << content if  content 
   end
-  #List (array) of targets, where the element can be used.
-  #Default are all supported targets.
-  #
-  #With restrictions of this attribute, elements can be restricted on special documents.
+=begin rdoc  
+Only for debbuging reasons.
+
+This method analyse the caller-stack and provides 
+the first "no lib/docgenerator-place".
+This should be the location, where the element is created.
+
+Via Element#inspect you get access to this information.
+=end  
+  def prepare_tracing_info()
+    caller().each{|c|
+      next if ( /lib\/(docgenerator|creole|wiki2doc)/ =~  c )
+      return c
+    }
+    #--> No calling stack outside lib/docgenerator found --> Error    
+    @log.error('Element#prepare_tracing_info: Found no starting place in caller stack') if @log.error?
+    caller().each{|c| @log.debug("\t#{c}") } if @log.debug?
+    return caller()
+  end
+=begin rdoc
+Set a text for the inspect command.
+
+Nil if the information was not collected at Element#new.
+=end
+  def inspect_creation_caller
+    if @creation_caller
+      ", created at #{@creation_caller}"
+    else
+      nil #'unknown. Please set Elements.trace if needed'
+    end
+  end
+  def inspect()
+    return "<#{self.class}#{inspect_creation_caller}>"
+  end
+
+=begin rdoc  
+List (array) of targets, where the element can be used.
+Default are all supported targets.
+
+With restrictions of this attribute, elements can be restricted on special documents.
+=end  
   def restrict_to( *argv )
     @targets = []
     @suppressed_targets = SUPPORTED_TARGETS.dup
-    @log.warn("Element#restrict_to: #{self.inspect} restrict to #{argv.inspect}") if @log.warn?
+    @log.info("Element#restrict_to: #{self.inspect} restrict to #{argv.inspect}") if @log.warn?
     argv.each{ |arg|
       #~ if ! SUPPORTED_TARGETS.include?( arg )
       if ! @suppressed_targets.delete( arg )
@@ -302,149 +148,176 @@ code
     }
     self
   end
-  #Only for debbuging reasons.
-  #Should contain the first "no docgenerator.rb-place, where part is called
-  #if @@trace is on, some tracing information is stored during creation.
-  def prepare_tracing_info( doit = @@trace )
-    return nil if ! doit
-    caller().each{|c|
-      next if ( /DocumentGenerator/ =~  c )
-      return c
-    }
-    #--> No calling stack found --> Error    
-    puts '----'*10
-    puts 'Element#prepare_tracing_info: Found no starting place in caller stack'
-    caller().each{|c| puts c }
-    puts '----'*10
-    return caller()
-  end
-  def inspect()
-    if @@trace
-      called_by  = ", Created in #{@called_by}"
-    else
-      called_by  = nil #'unknown. Please set Elements.trace if needed'
-    end
-    return "<Class Element(#{self.ids.join(',')})#{called_by}>"
-    #~ if @content
-      #~ return "<Class Element(#{self.ids.join(',')}) @content=#{@content.inspect}>"
-    #~ else
-      #~ return "<Class Element(#{self.ids.join(',')}) @attr=#{@attr.inspect}>"
-    #~ end
-  end
   #Accessor on content
   attr_reader :content
-  #Add something to the content.
-  #Only possible on elements, which supports "content".
+  #Logger of the element
+  attr_reader :log
+=begin rdoc  
+Add something to the content.
+Only possible on elements, which supports "content".
+=end
   def << ( content )
     if @content
       @content << content
     else
-      @log.warn("Add content to an element without this feature #{self.ids.inspect}, #{content.inspect}") if @log.warn?
+      @log.warn("Add content to an element without this feature #{self.inspect}, #{content.inspect}") if @log.warn?
     end
   end
 
-  #Add content after a target (other content)
-  #  insertafter(target,*obj)
-  #Requires the ability of "content".
-  def insertafter(target,*obj)
-    self.insert(target, 1, obj)
-  end
-  #Add content before a target (other content)
-  #  insertbefore(target,*obj)
-  #Requires the ability of "content".
-  def insertbefore(target,*obj)
-    self.insert(target, 0, obj)
-  end
-  #Insert content relative to a given target.
-  #The target must exist, pos defines the relative position (0=before, 1=one after the element).
-  #Method called by Element#insertbefore and Element#insertafter.
+=begin rdoc
+Add content after a target (other content)
+  insertafter(target,*obj)
+Requires the ability of "content".
+=end
+  def insertafter(target,*obj)
+    self.insert(target, 1, obj)
+  end
+=begin rdoc  
+Add content before a target (other content)
+  insertbefore(target,*obj)
+Requires the ability of "content".
+=end
+  def insertbefore(target,*obj)
+    self.insert(target, 0, obj)
+  end
+=begin rdoc  
+Insert content relative to a given target.
+The target must exist, pos defines the relative position (0=before, 1=one after the element).
+Method called by Element#insertbefore and Element#insertafter.
+=end
   def insert(target,pos,*obj )
     if @content
       if @content.include?( target )
         @content[@content.index(target)+pos ,0] = obj
       else
         @log.warn("Insert content not possible. Reference object does not exist (#{target.inspect})") if @log.warn?
-      end
+      end
     else
       @log.warn("Add content to an element without this feature") if @log.warn?
     end    
-    self
+    self
   end
-  #Delete the given object.
+=begin rdoc
+Delete the given object from content.
+=end
   def delete(target )
     if @content
       @content.delete( target )
     else
       @log.warn("Delete content of an element without this feature") if @log.warn?
     end    
-    self
+    self
   end
-  #Insert an empty line after the last entry
+=begin rdoc  
+Insert an empty line after the last entry.
+
+Example:
+  <tag>content</tag>[CR]
+=end
   def cr()
     @crafter  = true
     self
   end
-  #Insert an empty line before and after the last entry
+=begin rdoc
+Insert an empty line before and after the last entry.
+
+Example:
+  [CR]<tag>content</tag>[CR]
+=end
   def Cr()
     @crbefore  = true
     @crafter  = true
     self
   end
-  #Insert an empty line after the last entry and after the opening of the tag.
-  #This feature has it reason for lists, when each :li-tag gets a cr.
-  #The first item gets also a cr.
+=begin rdoc  
+Insert an empty line after the last entry and after the opening of the tag.
+
+Example:
+  <tag>[CR]content</tag>[CR]
+
+This feature has it reason for lists, when each :li-tag gets a cr.
+The first item gets also a cR.
+
+Example:
+  <ul>
+  <li>item with cR</li>
+  <li>item with cr</li>
+  </ul>
+=end
   def cR()
     @crbefore  = false
     @crmid  = true
     @crafter  = true
     self
   end
-  #Insert an empty line before and after the last entry and after the opening of the tag.
+=begin rdoc
+Insert an empty line before and after the last entry and after the opening of the tag.
+
+Example:
+  [CR]<tag>[CR]content</tag>[CR]
+=end
   def CR()
     @crbefore  = true
     @crmid  = true
     @crafter  = true
     self
   end
-  #Accessor on attribute list
+=begin rdoc
+Accessor on attribute list
+=end
   attr_reader :attr
-  #Return an attribute to add content.
+=begin rdoc  
+Return an attribute to add content.
+
+Example:
+  sec = element(:section, {}, 'title' )
+  sec[:shorttitle] << 'shorttitle'
+
+Normally, this is the better solution:
+  sec = element(:section, { :shorttitle => 'shorttitle'}, 'title' )
+=end
   def [] (key)
     attr = @attr[key]
     #If Attribute does not exist, take a look, if it is an alias-name.
     attr = @attr_alias[key] if !attr
-    if !attr
-      puts "Request unknown attribute '#{key}', return a dummy"
+    if ! attr
+      @log.warn("Request unknown attribute '#{key}', return a dummy (#{self.inspect})") if @log.warn?
       attr = Attribute.create( ).new(key, self)
     end
     return attr
   end
-  #Default setting, each element class may contain contents.
-  #Can be redefined by Elements.create.
-  #-true:  content available and necessary (e.g. <p>)
-  #-:empty_ok: content available, but not necessary (e.g. <td>)
-  #-false:  no content, no endtag, but tag closed with / (example: <br />)
-  #-nil:    no content, no endtag, no closing  (example: <br>)
+=begin rdoc  
+Default setting, each element class may contain contents.
+Can be redefined by meta-method Elements.has_no_content
+- true:  content available and necessary (e.g. Docgenerator::Elements::Paragraph)
+- :empty_ok: content available, but not necessary (e.g. Docgenerator::Tables::Column)
+- false:  no content, no endtag, but tag closed with / (example: Docgenerator::Elements::Newline as < br/>)
+- nil:    no content, no endtag, no closing  (example: Docgenerator::Elements::Newline as < br>)
+=end
   def content?()
     return true
   end
-  #check if there is content assigned.
+=begin rdoc
+check if there is content assigned.
+=end
   def empty?()
     return @content.empty?
   end
   @@level = 0
-  #Build a String to be used for the target document.
-  #Calls 
-  #-Element#to_latex (target :latex), 
-  #-Element#to_context (target :context) 
-  #-Element#to_html (target :html)
-  #-Element#to_wiki (target :wiki) (support stopped)
-  #-Element#to_creole (target :creole)  (not really good results)
-  #-Element#to_text (target :text) (not really good results)
-  #
-  #Via the options-hash, you can transport additional information.
+=begin rdoc  
+Build a String to be used for the target document.
+Calls 
+* Element#to_latex (target :latex), 
+* Element#to_context (target :context) 
+* Element#to_html (target :html)
+* Element#to_wiki (target :wiki) (support stopped)
+* Element#to_creole (target :creole)  (not really good results)
+* Element#to_text (target :text) (not really good results)
+
+Via the options-hash, you can transport additional information.
+=end
   def to_doc( target, options = {} )
-    o = Docgenerator_logger.set_option_defaults(options)
+    o = set_option_defaults(options)
     o[:log].debug("enter to_doc(#{target}) for #{self.inspect}, options: #{options.keys.inspect}") if o[:log].debug?
     #Return empty string, if target is not requested.
     if ! @targets.include?( target )
@@ -458,7 +331,7 @@ code
     #Some checks
     @attr.each{|k,v|
       if v.required? and v.to_s == '' and v.settings.include?(target)
-        o[:log].error "#{self.ids}: Attribut '#{k}' without required value" if o[:log].error?
+        o[:log].error "#{self.inspect}: Attribut '#{k}' without required value" if o[:log].error?
       end
     }
     #Build the string.
@@ -485,82 +358,131 @@ code
     #~ result << "\n"       if @crafter
     return result
   end
-  #This is a dummy method, called from Element#to_s for the target format LaTeX.
-  #This method must be overwritten from the element class.
-  #
-  #By default, the concatenation of all ids and the content is taken.
+=begin rdoc  
+This is a dummy method, called from Element#to_s for the target format LaTeX.
+This method must be overwritten from the element class.
+
+By default, the concatenation of all ids and the content is taken.
+=end
   def to_latex(options = {})
-    o = Docgenerator_logger.set_option_defaults(options)
-    o[:log].error("Missing output routine for LaTeX (#{self.ids.join(',')}) [#{@called_by}]") if o[:log].error?
+    o = set_option_defaults(options)
     makroname = 'dummy'
-    self.ids.each{|id|
+    self.element_ids.each{|id|
       makroname = id if id.is_a?(Symbol) or id.is_a?(String)
     }
+    o[:log].error("Missing output routine for LaTeX, use \\#{makroname} (#{self.inspect})")
     cmd  =  ''
     cmd  <<  "\n" if @crbefore
-    cmd  <<  "\\#{makroname}{#{@content}}"
+    cmd  <<  "\\#{makroname}{#{@content.to_latex(options)}}"
     cmd  <<  "\n" if @crafter
     return cmd
   end
-  #Create context-output.
-  #
-  #ConTeXt-support is added later and there are a lot of gaps (2009-07-01)
+=begin rdoc  
+Create context-output.
+
+ConTeXt-support is added later and there are a lot of gaps (2009-07-01)
+=end
   def to_context(options = {})
-    o = Docgenerator_logger.set_option_defaults(options)
-    o[:log].error("Missing output routine for ConTeXt (#{self.ids.join(',')}) [#{@called_by}]") if o[:log].error?
+    o = set_option_defaults(options)
     makroname = 'dummy'
-    self.ids.each{|id|
+    self.element_ids.each{|id|
       makroname = id if id.is_a?(Symbol) or id.is_a?(String)
     }
+    o[:log].error("Missing output routine for ConTeXt, use \\#{makroname} (#{self.inspect})")
+    
     cmd  =  ''
     cmd  <<  "\n" if @crbefore
-    cmd  <<  "\\#{makroname}{#{@content}}"
+    cmd  <<  "\\#{makroname}{#{@content.to_context(options)}}"
     cmd  <<  "\n" if @crafter
     return cmd
   end
-  #Method for definition inside Element.create.
+=begin rdoc
+Method for definition inside Element.create.
+=end
   def linebreak( flag = true )
     flag ? "\n" : ''
   end
-  #Prints the optional attribut key inside []. If empty, nil is returned
+=begin rdoc  
+Prints the optional attribut key inside []. If empty, nil is returned
+=end
   def texoptional(key)
-    return nil if ! @attr[key].filled?
+    return nil unless @attr[key].filled?
     return "[#{@attr[key]}]"
   end
-  #Build key-val options from attributs.
-  #Used e.g. by includegraphics.
+=begin rdoc  
+Build key-val options from attributs.
+Used e.g. by includegraphics.
+
+If the value is true, the value is added without '='.
+false-values are ignored.
+
+If you need a "value=true", then add 'true' as a string.
+
+Example (Packages::IncludePDF):
+  class IncludePDF < Element
+    add_attribute    :pages,  Attribute.create( [ :texkeyval], [ String ] )
+    add_attribute    :nup,  Attribute.create( [ :texkeyval], [ /\d+x\d+/ ] )  #multiple logical pages onto each sheet of paper. 
+    add_attribute    :landscape,  Attribute.create( [ :texkeyval], [ true, false ] )  #multiple logical pages onto each sheet of paper. 
+    #...
+    add_output( :latex,  '#{linebreak(@crbefore)}\includepdf[#{texkeyval()}]{#{@content}}#{linebreak(@crafter)}')
+  end
+
+  x = element(:includepdf, { :pages => '1-5', :nup => '2x2', :landscape => true }, 'filename')
+  puts x.texkeyval  #pages={1-5}, nup={2x2}, landscape
+  
+  x = element(:includepdf, { :pages => '1-5', :nup => '2x2', :landscape => false }, 'filename')
+  puts x.texkeyval  #pages={1-5}, nup={2x2}
+  
+  
+=end
   def texkeyval()
     keyval = []
     @attr.sort_by{|k,v| v.sortkey  }.each{|k,v|
-      keyval << "#{k}={#{v}}" if v.to_s != '' and v.texkeyval?
+      next unless v.texkeyval?
+      case v.content
+        when true, [true];   keyval << "#{k}" 
+        when false, [false]  #ignore
+        else  #take the value
+          keyval << "#{k}={#{v}}" unless v.to_s.empty?
+        end
     }
     return keyval.join(', ')
   end
-  #Method for html-output.
-  #If the method is redefined, the result is taken as a tag.
+=begin rdoc  
+Define the tag for html-output.
+
+If the method is redefined, the result is taken as a tag.
+Redfinition is made by Element.add_html_tag.
+
+htmltag nil/false supress the output.
+=end
   def htmltag()
     ''
   end
-  #This is a dummy method, called from Element#to_doc for the target format HTML.
-  #The tag from Element.htmltag is taken and all attributes and the content are used.
-  #
-  #This method can be overwritten from the element class.
+=begin rdoc  
+This is a dummy method, called from Element#to_doc for the target format HTML.
+
+The tag from Element#htmltag is taken and all attributes and the content are used.
+If Element#htmltag is nil/false, nothing '' is returned.
+
+This method can be overwritten from the element class.
+=end
   def to_html(options = {})
-    o = Docgenerator_logger.set_option_defaults(options)
+    o = set_option_defaults(options)
     tag = htmltag()
     if ! tag 
-      o[:log].error("No HTML element available (#{self.ids.join(',')})") if o[:log].error?
+      o[:log].error("No HTML element available (#{self.inspect})") if o[:log].error?
       return ''
     elsif tag == ''
       tag = 'span' 
-      o[:log].error("Missing output routine for HTML (#{self.ids.join(',')}) [#{@called_by}]") if o[:log].error?
+      o[:log].error("Missing output routine for HTML (#{self.inspect})") if o[:log].error?
     end
     #Test if the HTML-Tag should contain something, but there is nothing.
     #If :empty_ok it is ok, that there is no content (e.g <td>)
     #May make problems, if an empty tag is used to set a id-mark.
     if content?() and content? != :empty_ok and
       ( ! @content or @content == [] or @content == [nil] )
-      o[:log].warn("HTML-Tag #{tag} without content -> ignored #{self.inspect if @@trace}")  if o[:log].warn?
+      o[:log].warn("HTML-Tag #{tag} without content -> ignored #{self.inspect}")  if o[:log].warn?
       return ''
     end
     html  = String.new()
@@ -583,19 +505,29 @@ code
     html  <<  "\n" if @crafter
     return html
   end  #to_html
+=begin rdoc
+Return content in Wikimedia-Syntax.
+Support stopped.
+=end
   def to_wiki(options = {})
-    o = Docgenerator_logger.set_option_defaults(options)
-    o[:log].error("Missing output routine for Wiki (#{self.ids.join(',')}) [#{@called_by}]") if o[:log].error?
+    o = set_option_defaults(options)
+    o[:log].error("Missing output routine for Wiki (#{self.inspect})") if o[:log].error?
     return "#{@content.to_wiki(options)}\n"
   end
+=begin rdoc
+Return content in creole-Syntax.
+=end
   def to_creole(options = {})
-    o = Docgenerator_logger.set_option_defaults(options)
-    o[:log].error("Missing output routine for creole (#{self.ids.join(',')}) [#{@called_by}]") if o[:log].error?
+    o = set_option_defaults(options)
+    o[:log].error("Missing output routine for creole (#{self.inspect})") if o[:log].error?
     return "#{@content.to_creole(options)}\n"
   end
+=begin rdoc
+Make an Text-Representation of the content.
+=end
   def to_text(options = {})
-    o = Docgenerator_logger.set_option_defaults(options)
-    o[:log].error("Missing output routine for Text (#{self.ids.join(',')}) [#{@called_by}]") if o[:log].error?
+    o = set_option_defaults(options)
+    o[:log].error("Missing output routine for Text (#{self.inspect})") if o[:log].error?
     text = String.new()
     text  <<  "\n" if @crbefore
     text = "#{@content.to_text(options)}".strip
@@ -605,4 +537,25 @@ code
   def to_s()
     return self.inspect
   end
-end #Element
+end #Element
+end #module Docgenerator
+
+=begin rdoc
+Returns an element of a type "name".
+Attributes and content are optional parameter.
+
+This method is defined global (outside Docgenerator-module)
+
+If you call element with an undefined 'name',
+you get an error message and an anonymous dummy class is created.
+=end
+def element( name, attr = {}, content = nil )
+	elementclass = Docgenerator::Element.get( name )
+	if ! elementclass #Create a dummy element.
+		#~ element = Docgenerator::Element.create( name, {}, true  ).new(attr, content )
+		Docgenerator::DOCGENERATOR_LOGGER.error( "Usage of undefined element #{name}. Create an anonymous class")
+		elementclass = Class.new(Docgenerator::Element)
+    elementclass.add_id name
+	end
+	return elementclass.new(attr, content )
+end