class DocbookFiles::Docbook

Analyzes a DocBook 5 file for included and referenced files.

Constants

DOCBOOK_NS

The DocBook 5 namespace URL

XINCLUDE_NS

The XInclude namespace URL

Attributes

fd_tree[R]

The FileData tree representing the file hierarchy

Public Class Methods

new(fname) click to toggle source

Initialize vars and quiet the libxml error handler. See libxml.rubyforge.org/rdoc/classes/LibXML/XML/Error.html

# File lib/docbook_files/docbook.rb, line 20
def initialize(fname)
  @main_name = fname
  @fd_tree = nil
  XML::Error.set_handler(&XML::Error::QUIET_HANDLER)
end

Public Instance Methods

list() click to toggle source

Return the FileData tree representing the include hierarchy.

# File lib/docbook_files/docbook.rb, line 29
def list
  @fd_tree ||= analyze_file(@main_name,File.dirname(@main_name))
  @fd_tree
end
list_as_table(props) click to toggle source

Return a flat array of FileDatas, a table with level indicator. The format is easier for tabular output.

# File lib/docbook_files/docbook.rb, line 43
def list_as_table(props)
  tree = self.list()
  tree.traverse_as_table(props)
end
list_names() click to toggle source

Return all file names in a tree

# File lib/docbook_files/docbook.rb, line 35
def list_names
  fl = self.list()
  fl.names
end

Private Instance Methods

analyze_file(fname, parent_dir, parent_fd=nil) click to toggle source

Opens a XML document and looks for included or referenced files. Returns a FileData object with its include-tree

# File lib/docbook_files/docbook.rb, line 117
def analyze_file(fname, parent_dir, parent_fd=nil)
  fl = FileRef.new(fname, parent_dir, parent_fd)
  if fl.exists?
    begin
      doc = XML::Document.file(fl.full_name)      
      fl.namespace = namespace(doc)
      fl.docbook = true if docbook?(doc)
      fl.version = version(doc) if fl.docbook
      fl.tag = start_tag(doc)
      files = find_xincludes(doc)
      fl.refs = find_referenced_files(doc,parent_dir,fl)
    rescue Exception => e
      fl.error_string = e.to_s
      fl.status = FileData::STATUS_ERR
      files = []
    end
    fl.includes = files.map {|f| analyze_file(f,parent_dir,fl)}
  end
  fl
end
docbook?(doc) click to toggle source

Check whether the document has a DocBook default namespace

# File lib/docbook_files/docbook.rb, line 50
def docbook?(doc)
 dbns = doc.root.namespaces.default
 (!dbns.nil? && (dbns.href.casecmp(DOCBOOK_NS) == 0))
end
find_referenced_files(doc,parent_dir,parent_fd) click to toggle source

Finds and returns all external files referenced in a DocBook document. Referenced files are mostly non-XML files needed for mediaobjects etc. They can be searched via the fileref attribute.

# File lib/docbook_files/docbook.rb, line 106
def find_referenced_files(doc,parent_dir,parent_fd)
  refs = doc.find('//db:*[@fileref!=""]',:db => DOCBOOK_NS)
  refs.map {|r|
    fname = r.attributes['fileref']
    FileRef.new(fname,parent_dir,parent_fd)
  }
end
find_xincludes(doc) click to toggle source

Finds and returns all XInclude files/URLs in a document.

OPTIMIZE implement xpointer and fallback handling for xi:include? see www.w3.org/TR/xinclude/

# File lib/docbook_files/docbook.rb, line 94
def find_xincludes(doc)
 if has_xinclude?(doc)
   xincs = doc.find('//xi:include', "xi:"+XINCLUDE_NS)
   xincs.map {|x| x.attributes['href'] }
 else
   []
 end
end
has_xinclude?(doc) click to toggle source

Check whether the document has a XInclude namespace

# File lib/docbook_files/docbook.rb, line 78
def has_xinclude?(doc)
 ret = false
 doc.root.namespaces.each do |ns|
   if (ns.href.casecmp(XINCLUDE_NS) == 0)
     ret = true
     break
   end
 end
 ret
end
namespace(doc) click to toggle source

Get the default namespace string for the document, or an empty string if there is none

# File lib/docbook_files/docbook.rb, line 57
def namespace(doc)
  ns = doc.root.namespaces.default
  unless ns.nil?
    ns.href
  else
    ""
  end
end
start_tag(doc) click to toggle source

Returns the start tag of the XML document

# File lib/docbook_files/docbook.rb, line 67
def start_tag(doc)
  doc.root.name
end
version(doc) click to toggle source

Reads the version attribute of the root node, mainly for DocBook 5+

# File lib/docbook_files/docbook.rb, line 73
def version(doc)
  doc.root['version']
end