asciidoctor 2.0.10 → 2.0.17

data/lib/asciidoctor/convert.rb

@@ -1,193 +1,199 @@
+# frozen_string_literal: true
 module Asciidoctor
-  module_function
+  class << self
+    # Public: Parse the AsciiDoc source input into an Asciidoctor::Document and
+    # convert it to the specified backend format.
+    #
+    # Accepts input as an IO (or StringIO), String or String Array object. If the
+    # input is a File, the object is expected to be opened for reading and is not
+    # closed afterwards by this method. Information about the file (filename,
+    # directory name, etc) gets assigned to attributes on the Document object.
+    #
+    # If the :to_file option is true, and the input is a File, the output is
+    # written to a file adjacent to the input file, having an extension that
+    # corresponds to the backend format. Otherwise, if the :to_file option is
+    # specified, the file is written to that file. If :to_file is not an absolute
+    # path, it is resolved relative to :to_dir, if given, otherwise the
+    # Document#base_dir. If the target directory does not exist, it will not be
+    # created unless the :mkdirs option is set to true. If the file cannot be
+    # written because the target directory does not exist, or because it falls
+    # outside of the Document#base_dir in safe mode, an IOError is raised.
+    #
+    # If the output is going to be written to a file, the header and footer are
+    # included unless specified otherwise (writing to a file implies creating a
+    # standalone document). Otherwise, the header and footer are not included by
+    # default and the converted result is returned.
+    #
+    # input   - the String AsciiDoc source filename
+    # options - a String, Array or Hash of options to control processing (default: {})
+    #           String and Array values are converted into a Hash.
+    #           See Asciidoctor::Document#initialize for details about options.
+    #
+    # Returns the Document object if the converted String is written to a
+    # file, otherwise the converted String
+    def convert input, options = {}
+      (options = options.merge).delete :parse
+      to_dir = options.delete :to_dir
+      mkdirs = options.delete :mkdirs
 
-  # Public: Parse the AsciiDoc source input into an Asciidoctor::Document and
-  # convert it to the specified backend format.
-  #
-  # Accepts input as an IO (or StringIO), String or String Array object. If the
-  # input is a File, the object is expected to be opened for reading and is not
-  # closed afterwards by this method. Information about the file (filename,
-  # directory name, etc) gets assigned to attributes on the Document object.
-  #
-  # If the :to_file option is true, and the input is a File, the output is
-  # written to a file adjacent to the input file, having an extension that
-  # corresponds to the backend format. Otherwise, if the :to_file option is
-  # specified, the file is written to that file. If :to_file is not an absolute
-  # path, it is resolved relative to :to_dir, if given, otherwise the
-  # Document#base_dir. If the target directory does not exist, it will not be
-  # created unless the :mkdirs option is set to true. If the file cannot be
-  # written because the target directory does not exist, or because it falls
-  # outside of the Document#base_dir in safe mode, an IOError is raised.
-  #
-  # If the output is going to be written to a file, the header and footer are
-  # included unless specified otherwise (writing to a file implies creating a
-  # standalone document). Otherwise, the header and footer are not included by
-  # default and the converted result is returned.
-  #
-  # input   - the String AsciiDoc source filename
-  # options - a String, Array or Hash of options to control processing (default: {})
-  #           String and Array values are converted into a Hash.
-  #           See Asciidoctor::Document#initialize for details about options.
-  #
-  # Returns the Document object if the converted String is written to a
-  # file, otherwise the converted String
-  def convert input, options = {}
-    (options = options.merge).delete :parse
-    to_dir = options.delete :to_dir
-    mkdirs = options.delete :mkdirs
-
-    case (to_file = options.delete :to_file)
-    when true, nil
-      unless (write_to_target = to_dir)
-        sibling_path = ::File.absolute_path input.path if ::File === input
+      case (to_file = options.delete :to_file)
+      when true, nil
+        unless (write_to_target = to_dir)
+          sibling_path = ::File.absolute_path input.path if ::File === input
+        end
+        to_file = nil
+      when false
+        to_file = nil
+      when '/dev/null'
+        return load input, options
+      else
+        options[:to_file] = write_to_target = to_file unless (stream_output = to_file.respond_to? :write)
       end
-      to_file = nil
-    when false
-      to_file = nil
-    when '/dev/null'
-      return load input, options
-    else
-      options[:to_file] = write_to_target = to_file unless (stream_output = to_file.respond_to? :write)
-    end
 
-    unless options.key? :standalone
-      if sibling_path || write_to_target
-        options[:standalone] = options.fetch :header_footer, true
-      elsif options.key? :header_footer
-        options[:standalone] = options[:header_footer]
+      unless options.key? :standalone
+        if sibling_path || write_to_target
+          options[:standalone] = options.fetch :header_footer, true
+        elsif options.key? :header_footer
+          options[:standalone] = options[:header_footer]
+        end
       end
-    end
 
-    # NOTE outfile may be controlled by document attributes, so resolve outfile after loading
-    if sibling_path
-      options[:to_dir] = outdir = ::File.dirname sibling_path
-    elsif write_to_target
-      if to_dir
-        if to_file
-          options[:to_dir] = ::File.dirname ::File.expand_path ::File.join to_dir, to_file
-        else
-          options[:to_dir] = ::File.expand_path to_dir
+      # NOTE outfile may be controlled by document attributes, so resolve outfile after loading
+      if sibling_path
+        options[:to_dir] = outdir = ::File.dirname sibling_path
+      elsif write_to_target
+        if to_dir
+          if to_file
+            options[:to_dir] = ::File.dirname ::File.expand_path to_file, to_dir
+          else
+            options[:to_dir] = ::File.expand_path to_dir
+          end
+        elsif to_file
+          options[:to_dir] = ::File.dirname ::File.expand_path to_file
         end
-      elsif to_file
-        options[:to_dir] = ::File.dirname ::File.expand_path to_file
       end
-    end
 
-    # NOTE :to_dir is always set when outputting to a file
-    # NOTE :to_file option only passed if assigned an explicit path
-    doc = load input, options
+      # NOTE :to_dir is always set when outputting to a file
+      # NOTE :to_file option only passed if assigned an explicit path
+      doc = load input, options
 
-    if sibling_path # write to file in same directory
-      outfile = ::File.join outdir, %(#{doc.attributes['docname']}#{doc.outfilesuffix})
-      raise ::IOError, %(input file and output file cannot be the same: #{outfile}) if outfile == sibling_path
-    elsif write_to_target # write to explicit file or directory
-      working_dir = (options.key? :base_dir) ? (::File.expand_path options[:base_dir]) : ::Dir.pwd
-      # QUESTION should the jail be the working_dir or doc.base_dir???
-      jail = doc.safe >= SafeMode::SAFE ? working_dir : nil
-      if to_dir
-        outdir = doc.normalize_system_path(to_dir, working_dir, jail, target_name: 'to_dir', recover: false)
-        if to_file
-          outfile = doc.normalize_system_path(to_file, outdir, nil, target_name: 'to_dir', recover: false)
-          # reestablish outdir as the final target directory (in the case to_file had directory segments)
+      if sibling_path # write to file in same directory
+        outfile = ::File.join outdir, %(#{doc.attributes['docname']}#{doc.outfilesuffix})
+        raise ::IOError, %(input file and output file cannot be the same: #{outfile}) if outfile == sibling_path
+      elsif write_to_target # write to explicit file or directory
+        working_dir = (options.key? :base_dir) ? (::File.expand_path options[:base_dir]) : ::Dir.pwd
+        # QUESTION should the jail be the working_dir or doc.base_dir???
+        jail = doc.safe >= SafeMode::SAFE ? working_dir : nil
+        if to_dir
+          outdir = doc.normalize_system_path(to_dir, working_dir, jail, target_name: 'to_dir', recover: false)
+          if to_file
+            outfile = doc.normalize_system_path(to_file, outdir, nil, target_name: 'to_dir', recover: false)
+            # reestablish outdir as the final target directory (in the case to_file had directory segments)
+            outdir = ::File.dirname outfile
+          else
+            outfile = ::File.join outdir, %(#{doc.attributes['docname']}#{doc.outfilesuffix})
+          end
+        elsif to_file
+          outfile = doc.normalize_system_path(to_file, working_dir, jail, target_name: 'to_dir', recover: false)
+          # establish outdir as the final target directory (in the case to_file had directory segments)
           outdir = ::File.dirname outfile
-        else
-          outfile = ::File.join outdir, %(#{doc.attributes['docname']}#{doc.outfilesuffix})
         end
-      elsif to_file
-        outfile = doc.normalize_system_path(to_file, working_dir, jail, target_name: 'to_dir', recover: false)
-        # establish outdir as the final target directory (in the case to_file had directory segments)
-        outdir = ::File.dirname outfile
-      end
 
-      if ::File === input && outfile == (::File.absolute_path input.path)
-        raise ::IOError, %(input file and output file cannot be the same: #{outfile})
+        if ::File === input && outfile == (::File.absolute_path input.path)
+          raise ::IOError, %(input file and output file cannot be the same: #{outfile})
+        end
+
+        if mkdirs
+          Helpers.mkdir_p outdir
+        else
+          # NOTE we intentionally refer to the directory as it was passed to the API
+          raise ::IOError, %(target directory does not exist: #{to_dir} (hint: set :mkdirs option)) unless ::File.directory? outdir
+        end
+      else # write to stream
+        outfile = to_file
+        outdir = nil
       end
 
-      if mkdirs
-        Helpers.mkdir_p outdir
+      if outfile && !stream_output
+        output = doc.convert 'outfile' => outfile, 'outdir' => outdir
       else
-        # NOTE we intentionally refer to the directory as it was passed to the API
-        raise ::IOError, %(target directory does not exist: #{to_dir} (hint: set :mkdirs option)) unless ::File.directory? outdir
+        output = doc.convert
       end
-    else # write to stream
-      outfile = to_file
-      outdir = nil
-    end
-
-    if outfile && !stream_output
-      output = doc.convert 'outfile' => outfile, 'outdir' => outdir
-    else
-      output = doc.convert
-    end
 
-    if outfile
-      doc.write output, outfile
+      if outfile
+        doc.write output, outfile
 
-      # NOTE document cannot control this behavior if safe >= SafeMode::SERVER
-      # NOTE skip if stylesdir is a URI
-      if !stream_output && doc.safe < SafeMode::SECURE && (doc.attr? 'linkcss') && (doc.attr? 'copycss') &&
-          (doc.basebackend? 'html') && !((stylesdir = (doc.attr 'stylesdir')) && (Helpers.uriish? stylesdir))
-        if (stylesheet = doc.attr 'stylesheet')
-          if DEFAULT_STYLESHEET_KEYS.include? stylesheet
-            copy_asciidoctor_stylesheet = true
-          elsif !(Helpers.uriish? stylesheet)
-            copy_user_stylesheet = true
-          end
-        end
-        copy_syntax_hl_stylesheet = (syntax_hl = doc.syntax_highlighter) && (syntax_hl.write_stylesheet? doc)
-        if copy_asciidoctor_stylesheet || copy_user_stylesheet || copy_syntax_hl_stylesheet
-          stylesoutdir = doc.normalize_system_path(stylesdir, outdir, doc.safe >= SafeMode::SAFE ? outdir : nil)
-          if mkdirs
-            Helpers.mkdir_p stylesoutdir
-          else
-            raise ::IOError, %(target stylesheet directory does not exist: #{stylesoutdir} (hint: set :mkdirs option)) unless ::File.directory? stylesoutdir
+        # NOTE document cannot control this behavior if safe >= SafeMode::SERVER
+        # NOTE skip if stylesdir is a URI
+        if !stream_output && doc.safe < SafeMode::SECURE && (doc.attr? 'linkcss') && (doc.attr? 'copycss') &&
+            (doc.basebackend? 'html') && !((stylesdir = (doc.attr 'stylesdir')) && (Helpers.uriish? stylesdir))
+          if (stylesheet = doc.attr 'stylesheet')
+            if DEFAULT_STYLESHEET_KEYS.include? stylesheet
+              copy_asciidoctor_stylesheet = true
+            elsif !(Helpers.uriish? stylesheet)
+              copy_user_stylesheet = true
+            end
           end
-
-          if copy_asciidoctor_stylesheet
-            Stylesheets.instance.write_primary_stylesheet stylesoutdir
-          # FIXME should Stylesheets also handle the user stylesheet?
-          elsif copy_user_stylesheet
-            if (stylesheet_src = doc.attr 'copycss').empty?
-              stylesheet_src = doc.normalize_system_path stylesheet
+          copy_syntax_hl_stylesheet = (syntax_hl = doc.syntax_highlighter) && (syntax_hl.write_stylesheet? doc)
+          if copy_asciidoctor_stylesheet || copy_user_stylesheet || copy_syntax_hl_stylesheet
+            stylesoutdir = doc.normalize_system_path(stylesdir, outdir, doc.safe >= SafeMode::SAFE ? outdir : nil)
+            if mkdirs
+              Helpers.mkdir_p stylesoutdir
             else
-              # NOTE in this case, copycss is a source location (but cannot be a URI)
-              stylesheet_src = doc.normalize_system_path stylesheet_src
+              raise ::IOError, %(target stylesheet directory does not exist: #{stylesoutdir} (hint: set :mkdirs option)) unless ::File.directory? stylesoutdir
             end
-            stylesheet_dest = doc.normalize_system_path stylesheet, stylesoutdir, (doc.safe >= SafeMode::SAFE ? outdir : nil)
-            # NOTE don't warn if src can't be read and dest already exists (see #2323)
-            if stylesheet_src != stylesheet_dest && (stylesheet_data = doc.read_asset stylesheet_src,
-                warn_on_failure: !(::File.file? stylesheet_dest), label: 'stylesheet')
-              ::File.write stylesheet_dest, stylesheet_data, mode: FILE_WRITE_MODE
+
+            if copy_asciidoctor_stylesheet
+              Stylesheets.instance.write_primary_stylesheet stylesoutdir
+            # FIXME should Stylesheets also handle the user stylesheet?
+            elsif copy_user_stylesheet
+              if (stylesheet_src = doc.attr 'copycss') == '' || stylesheet_src == true
+                stylesheet_src = doc.normalize_system_path stylesheet
+              else
+                # NOTE in this case, copycss is a source location (but cannot be a URI)
+                stylesheet_src = doc.normalize_system_path stylesheet_src.to_s
+              end
+              stylesheet_dest = doc.normalize_system_path stylesheet, stylesoutdir, (doc.safe >= SafeMode::SAFE ? outdir : nil)
+              # NOTE don't warn if src can't be read and dest already exists (see #2323)
+              if stylesheet_src != stylesheet_dest && (stylesheet_data = doc.read_asset stylesheet_src,
+                  warn_on_failure: !(::File.file? stylesheet_dest), label: 'stylesheet')
+                if (stylesheet_outdir = ::File.dirname stylesheet_dest) != stylesoutdir && !(::File.directory? stylesheet_outdir)
+                  if mkdirs
+                    Helpers.mkdir_p stylesheet_outdir
+                  else
+                    raise ::IOError, %(target stylesheet directory does not exist: #{stylesheet_outdir} (hint: set :mkdirs option))
+                  end
+                end
+                ::File.write stylesheet_dest, stylesheet_data, mode: FILE_WRITE_MODE
+              end
             end
+            syntax_hl.write_stylesheet doc, stylesoutdir if copy_syntax_hl_stylesheet
           end
-          syntax_hl.write_stylesheet doc, stylesoutdir if copy_syntax_hl_stylesheet
         end
+        doc
+      else
+        output
       end
-      doc
-    else
-      output
     end
-  end
 
-  # Public: Parse the contents of the AsciiDoc source file into an
-  # Asciidoctor::Document and convert it to the specified backend format.
-  #
-  # input   - the String AsciiDoc source filename
-  # options - a String, Array or Hash of options to control processing (default: {})
-  #           String and Array values are converted into a Hash.
-  #           See Asciidoctor::Document#initialize for details about options.
-  #
-  # Returns the Document object if the converted String is written to a
-  # file, otherwise the converted String
-  def convert_file filename, options = {}
-    ::File.open(filename, FILE_READ_MODE) {|file| convert file, options }
-  end
+    # Public: Parse the contents of the AsciiDoc source file into an
+    # Asciidoctor::Document and convert it to the specified backend format.
+    #
+    # input   - the String AsciiDoc source filename
+    # options - a String, Array or Hash of options to control processing (default: {})
+    #           String and Array values are converted into a Hash.
+    #           See Asciidoctor::Document#initialize for details about options.
+    #
+    # Returns the Document object if the converted String is written to a
+    # file, otherwise the converted String
+    def convert_file filename, options = {}
+      ::File.open(filename, FILE_READ_MODE) {|file| convert file, options }
+    end
 
-  # Deprecated: Use {Asciidoctor.convert} instead.
-  alias render convert
-  module_function :render
+    # Deprecated: Use {Asciidoctor.convert} instead.
+    alias render convert
 
-  # Deprecated: Use {Asciidoctor.convert_file} instead.
-  alias render_file convert_file
-  module_function :render_file
+    # Deprecated: Use {Asciidoctor.convert_file} instead.
+    alias render_file convert_file
+  end
 end

data/lib/asciidoctor/converter/docbook5.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 module Asciidoctor
 # A built-in {Converter} implementation that generates DocBook 5 output. The output is inspired by the output produced
-# by the docbook45 backend from AsciiDoc Python, except it has been migrated to the DocBook 5 specification.
+# by the docbook45 backend from AsciiDoc.py, except it has been migrated to the DocBook 5 specification.
 class Converter::DocBook5Converter < Converter::Base
   register_for 'docbook5'
 
   # default represents variablelist
   (DLIST_TAGS = {
-    'qanda' => { list:  'qandaset', entry: 'qandaentry', label: 'question', term:  'simpara', item:  'answer' },
-    'glossary' => { list:  nil, entry: 'glossentry', term:  'glossterm', item:  'glossdef' },
-  }).default = { list:  'variablelist', entry: 'varlistentry', term: 'term', item:  'listitem' }
+    'qanda' => { list: 'qandaset', entry: 'qandaentry', label: 'question', term: 'simpara', item: 'answer' },
+    'glossary' => { list: nil, entry: 'glossentry', term: 'glossterm', item: 'glossdef' },
+  }).default = { list: 'variablelist', entry: 'varlistentry', term: 'term', item: 'listitem' }
 
   (QUOTE_TAGS = {
     monospaced:  ['<literal>', '</literal>'],
@@ -25,7 +25,7 @@ class Converter::DocBook5Converter < Converter::Base
   MANPAGE_SECTION_TAGS = { 'section' => 'refsection', 'synopsis' => 'refsynopsisdiv' }
   TABLE_PI_NAMES = ['dbhtml', 'dbfo', 'dblatex']
 
-  CopyrightRx = /^(#{CC_ANY}+?)(?: ((?:\d{4}\-)?\d{4}))?$/
+  CopyrightRx = /^(#{CC_ANY}+?)(?: ((?:\d{4}-)?\d{4}))?$/
   ImageMacroRx = /^image::?(\S|\S#{CC_ANY}*?\S)\[(#{CC_ANY}+)?\]$/
 
   def initialize backend, opts = {}
@@ -41,7 +41,8 @@ class Converter::DocBook5Converter < Converter::Base
     if (root_tag_name = node.doctype) == 'manpage'
       root_tag_name = 'refentry'
     end
-    result << %(<#{root_tag_name} xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0"#{lang_attribute}#{common_attributes node.id}>)
+    root_tag_idx = result.size
+    id = node.id
     result << (document_info_tag node) unless node.noheader
     unless (docinfo_content = node.docinfo :header).empty?
       result << docinfo_content
@@ -50,6 +51,9 @@ class Converter::DocBook5Converter < Converter::Base
     unless (docinfo_content = node.docinfo :footer).empty?
       result << docinfo_content
     end
+    id, node.id = node.id, nil unless id
+    # defer adding root tag in case document ID is auto-generated on demand
+    result.insert root_tag_idx, %(<#{root_tag_name} xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0"#{lang_attribute}#{common_attributes id}>)
     result << %(</#{root_tag_name}>)
     result.join LF
   end
@@ -298,13 +302,13 @@ class Converter::DocBook5Converter < Converter::Base
 </abstract>)
       end
     when 'partintro'
-      unless node.level == 0 && node.parent.context == :section && node.document.doctype == 'book'
-        logger.error 'partintro block can only be used when doctype is book and must be a child of a book part. Excluding block content.'
-        ''
-      else
+      if node.level == 0 && node.parent.context == :section && node.document.doctype == 'book'
         %(<partintro#{common_attributes node.id, node.role, node.reftext}>
 #{title_tag node}#{enclose_content node}
 </partintro>)
+      else
+        logger.error 'partintro block can only be used when doctype is book and must be a child of a book part. Excluding block content.'
+        ''
       end
     else
       reftext = node.reftext if (id = node.id)
@@ -371,24 +375,22 @@ class Converter::DocBook5Converter < Converter::Base
     has_body = false
     result = []
     pgwide_attribute = (node.option? 'pgwide') ? ' pgwide="1"' : ''
-    if (frame = node.attr 'frame', 'all', 'table-frame') == 'ends'
-      frame = 'topbot'
-    end
+    frame = 'topbot' if (frame = node.attr 'frame', 'all', 'table-frame') == 'ends'
     grid = node.attr 'grid', nil, 'table-grid'
     result << %(<#{tag_name = node.title? ? 'table' : 'informaltable'}#{common_attributes node.id, node.role, node.reftext}#{pgwide_attribute} frame="#{frame}" rowsep="#{['none', 'cols'].include?(grid) ? 0 : 1}" colsep="#{['none', 'rows'].include?(grid) ? 0 : 1}"#{(node.attr? 'orientation', 'landscape', 'table-orientation') ? ' orient="land"' : ''}>)
-    if (node.option? 'unbreakable')
+    if node.option? 'unbreakable'
       result << '<?dbfo keep-together="always"?>'
-    elsif (node.option? 'breakable')
+    elsif node.option? 'breakable'
       result << '<?dbfo keep-together="auto"?>'
     end
     result << %(<title>#{node.title}</title>) if tag_name == 'table'
-    col_width_key = if (width = (node.attr? 'width') ? (node.attr 'width') : nil)
+    if (width = (node.attr? 'width') ? (node.attr 'width') : nil)
       TABLE_PI_NAMES.each do |pi_name|
         result << %(<?#{pi_name} table-width="#{width}"?>)
       end
-      'colabswidth'
+      col_width_key = 'colabswidth'
     else
-      'colpcwidth'
+      col_width_key = 'colpcwidth'
     end
     result << %(<tgroup cols="#{node.attr 'colcount'}">)
     node.columns.each do |col|
@@ -401,12 +403,10 @@ class Converter::DocBook5Converter < Converter::Base
       rows.each do |row|
         result << '<row>'
         row.each do |cell|
-          halign_attribute = (cell.attr? 'halign') ? %( align="#{cell.attr 'halign'}") : ''
-          valign_attribute = (cell.attr? 'valign') ? %( valign="#{cell.attr 'valign'}") : ''
           colspan_attribute = cell.colspan ? %( namest="col_#{colnum = cell.column.attr 'colnumber'}" nameend="col_#{colnum + cell.colspan - 1}") : ''
           rowspan_attribute = cell.rowspan ? %( morerows="#{cell.rowspan - 1}") : ''
           # NOTE <entry> may not have whitespace (e.g., line breaks) as a direct descendant according to DocBook rules
-          entry_start = %(<entry#{halign_attribute}#{valign_attribute}#{colspan_attribute}#{rowspan_attribute}>)
+          entry_start = %(<entry align="#{cell.attr 'halign'}" valign="#{cell.attr 'valign'}"#{colspan_attribute}#{rowspan_attribute}>)
           if tsec == :head
             cell_content = cell.text
           else
@@ -478,16 +478,22 @@ class Converter::DocBook5Converter < Converter::Base
       %(<anchor#{common_attributes((id = node.id), nil, node.reftext || %([#{id}]))}/>)
     when :xref
       if (path = node.attributes['path'])
-        # QUESTION should we use refid as fallback text instead? (like the html5 backend?)
         %(<link xl:href="#{node.target}">#{node.text || path}</link>)
       else
-        linkend = node.attributes['fragment'] || node.target
+        if (linkend = node.attributes['refid']).nil_or_empty?
+          root_doc = get_root_document node
+          # Q: should we warn instead of generating a document ID on demand?
+          linkend = (root_doc.id ||= generate_document_id root_doc)
+        end
+        # NOTE the xref tag in DocBook does not support explicit link text, so the link tag must be used instead
+        # The section at http://www.sagehill.net/docbookxsl/CrossRefs.html#IdrefLinks gives an explanation for this choice
+        # "link - a cross reference where you supply the text of the reference as the content of the link element."
         (text = node.text) ? %(<link linkend="#{linkend}">#{text}</link>) : %(<xref linkend="#{linkend}"/>)
       end
     when :link
       %(<link xl:href="#{node.target}">#{node.text}</link>)
     when :bibref
-      %(<anchor#{common_attributes node.id, nil, "[#{node.reftext || node.id}]"}/>#{text})
+      %(<anchor#{common_attributes node.id, nil, (text = "[#{node.reftext || node.id}]")}/>#{text})
     else
       logger.warn %(unknown anchor type: #{node.type.inspect})
       nil
@@ -517,7 +523,7 @@ class Converter::DocBook5Converter < Converter::Base
   def convert_inline_image node
     width_attribute = (node.attr? 'width') ? %( contentwidth="#{node.attr 'width'}") : ''
     depth_attribute = (node.attr? 'height') ? %( contentdepth="#{node.attr 'height'}") : ''
-    %(<inlinemediaobject>
+    %(<inlinemediaobject#{common_attributes nil, node.role}>
 <imageobject>
 <imagedata fileref="#{node.type == 'icon' ? (node.icon_uri node.target) : (node.image_uri node.target)}"#{width_attribute}#{depth_attribute}/>
 </imageobject>
@@ -537,9 +543,8 @@ class Converter::DocBook5Converter < Converter::Base
       %(<indexterm>
 <primary>#{node.text}</primary>#{rel}
 </indexterm>#{node.text})
-    else
-      if (numterms = (terms = node.attr 'terms').size) > 2
-        %(<indexterm>
+    elsif (numterms = (terms = node.attr 'terms').size) > 2
+      %(<indexterm>
 <primary>#{terms[0]}</primary><secondary>#{terms[1]}</secondary><tertiary>#{terms[2]}</tertiary>#{rel}
 </indexterm>#{(node.document.option? 'indexterm-promotion') ? %[
 <indexterm>
@@ -548,18 +553,17 @@ class Converter::DocBook5Converter < Converter::Base
 <indexterm>
 <primary>#{terms[2]}</primary>
 </indexterm>] : ''})
-      elsif numterms > 1
-        %(<indexterm>
+    elsif numterms > 1
+      %(<indexterm>
 <primary>#{terms[0]}</primary><secondary>#{terms[1]}</secondary>#{rel}
-</indexterm>#{(node.document.option?  'indexterm-promotion') ? %[
+</indexterm>#{(node.document.option? 'indexterm-promotion') ? %[
 <indexterm>
 <primary>#{terms[1]}</primary>
 </indexterm>] : ''})
-      else
-        %(<indexterm>
+    else
+      %(<indexterm>
 <primary>#{terms[0]}</primary>#{rel}
 </indexterm>)
-      end
     end
   end
 
@@ -714,6 +718,17 @@ class Converter::DocBook5Converter < Converter::Base
     result.join LF
   end
 
+  def get_root_document node
+    while (node = node.document).nested?
+      node = node.parent_document
+    end
+    node
+  end
+
+  def generate_document_id doc
+    %(__#{doc.doctype}-root__)
+  end
+
   # FIXME this should be handled through a template mechanism
   def enclose_content node
     node.content_model == :compound ? node.content : %(<simpara>#{node.content}</simpara>)