asciidoctor 2.0.13 → 2.0.17

data/data/stylesheets/coderay-asciidoctor.css

@@ -1,15 +1,15 @@
-/* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
+/*! Stylesheet for CodeRay to loosely match GitHub themes | MIT License */
 pre.CodeRay{background:#f7f7f8}
-.CodeRay .line-numbers{border-right:1px solid currentColor;opacity:.35;padding:0 .5em 0 0}
+.CodeRay .line-numbers{border-right:1px solid;opacity:.35;padding:0 .5em 0 0;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
 .CodeRay span.line-numbers{display:inline-block;margin-right:.75em}
 .CodeRay .line-numbers strong{color:#000}
 table.CodeRay{border-collapse:separate;border:0;margin-bottom:0;background:none}
 table.CodeRay td{vertical-align:top;line-height:inherit}
 table.CodeRay td.line-numbers{text-align:right}
 table.CodeRay td.code{padding:0 0 0 .75em}
-.CodeRay .debug{color:#fff !important;background:#000080 !important}
+.CodeRay .debug{color:#fff!important;background:navy!important}
 .CodeRay .annotation{color:#007}
-.CodeRay .attribute-name{color:#000080}
+.CodeRay .attribute-name{color:navy}
 .CodeRay .attribute-value{color:#700}
 .CodeRay .binary{color:#509}
 .CodeRay .comment{color:#998;font-style:italic}
@@ -18,7 +18,7 @@ table.CodeRay td.code{padding:0 0 0 .75em}
 .CodeRay .char .delimiter{color:#039}
 .CodeRay .class{color:#458;font-weight:bold}
 .CodeRay .complex{color:#a08}
-.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
+.CodeRay .constant,.CodeRay .predefined-constant{color:teal}
 .CodeRay .color{color:#099}
 .CodeRay .class-variable{color:#369}
 .CodeRay .decorator{color:#b0b}
@@ -33,7 +33,7 @@ table.CodeRay td.code{padding:0 0 0 .75em}
 .CodeRay .exception{color:inherit}
 .CodeRay .filename{color:#099}
 .CodeRay .function{color:#900;font-weight:bold}
-.CodeRay .global-variable{color:#008080}
+.CodeRay .global-variable{color:teal}
 .CodeRay .hex{color:#058}
 .CodeRay .integer,.CodeRay .float{color:#099}
 .CodeRay .include{color:#555}
@@ -44,7 +44,7 @@ table.CodeRay td.code{padding:0 0 0 .75em}
 .CodeRay .inline-delimiter{color:#d14}
 .CodeRay .important{color:#555;font-weight:bold}
 .CodeRay .interpreted{color:#b2b}
-.CodeRay .instance-variable{color:#008080}
+.CodeRay .instance-variable{color:teal}
 .CodeRay .label{color:#970}
 .CodeRay .local-variable{color:#963}
 .CodeRay .octal{color:#40e}
@@ -54,7 +54,7 @@ table.CodeRay td.code{padding:0 0 0 .75em}
 .CodeRay .directive{font-weight:bold}
 .CodeRay .type{font-weight:bold}
 .CodeRay .predefined-type{color:inherit}
-.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
+.CodeRay .reserved,.CodeRay .keyword{color:#000;font-weight:bold}
 .CodeRay .key{color:#808}
 .CodeRay .key .delimiter{color:#606}
 .CodeRay .key .char{color:#80f}
@@ -74,7 +74,7 @@ table.CodeRay td.code{padding:0 0 0 .75em}
 .CodeRay .symbol{color:#990073}
 .CodeRay .symbol .content{color:#a60}
 .CodeRay .symbol .delimiter{color:#630}
-.CodeRay .tag{color:#008080}
+.CodeRay .tag{color:teal}
 .CodeRay .tag-special{color:#d70}
 .CodeRay .variable{color:#036}
 .CodeRay .insert{background:#afa}

data/lib/asciidoctor/abstract_block.rb

@@ -11,7 +11,7 @@ class AbstractBlock < AbstractNode
   # * :compound - this block contains other blocks
   # * :simple - this block holds a paragraph of prose that receives normal substitutions
   # * :verbatim - this block holds verbatim text (displayed "as is") that receives verbatim substitutions
-  # * :raw - this block holds unprocessed content passed directly to the output with no sustitutions applied
+  # * :raw - this block holds unprocessed content passed directly to the output with no substitutions applied
   # * :empty - this block has no content
   attr_accessor :content_model
 
@@ -90,7 +90,7 @@ class AbstractBlock < AbstractNode
   #
   # context - the context Symbol context to assign to this block
   #
-  # Returns the new context Symbol assigned to this block
+  # Returns the specified Symbol context
   def context= context
     @node_name = (@context = context).to_s
   end
@@ -129,11 +129,13 @@ class AbstractBlock < AbstractNode
 
   # Public: Check whether this block has any child Section objects.
   #
-  # Only applies to Document and Section instances
+  # Acts an an abstract method that always returns false unless this block is an
+  # instance of Document or Section.
+  # Both Document and Section provide overrides for this method.
   #
-  # Returns A [Boolean] to indicate whether this block has child Section objects
+  # Returns false
   def sections?
-    @next_section_index > 0
+    false
   end
 
   # Deprecated: Legacy property to get the String or Integer numeral of this section.
@@ -269,7 +271,7 @@ class AbstractBlock < AbstractNode
     ORDERED_LIST_KEYWORDS[list_type || @style]
   end
 
-  # Public: Get the String title of this Block with title substitions applied
+  # Public: Get the String title of this Block with title substitutions applied
   #
   # The following substitutions are applied to block and section titles:
   #
@@ -296,7 +298,7 @@ class AbstractBlock < AbstractNode
 
   # Public: Set the String block title.
   #
-  # Returns the new String title assigned to this Block
+  # Returns the specified String title
   def title= val
     @converted_title = nil
     @title = val
@@ -480,7 +482,7 @@ class AbstractBlock < AbstractNode
           @header.find_by_internal selector, result, &block
         end
         @blocks.each do |b|
-          next if (context_selector == :section && b.context != :section) # optimization
+          next if context_selector == :section && b.context != :section # optimization
           b.find_by_internal selector, result, &block
         end
       end
@@ -505,7 +507,7 @@ class AbstractBlock < AbstractNode
       end
     else
       @blocks.each do |b|
-        next if (context_selector == :section && b.context != :section) # optimization
+        next if context_selector == :section && b.context != :section # optimization
         b.find_by_internal selector, result, &block
       end
     end

data/lib/asciidoctor/abstract_node.rb

@@ -4,7 +4,8 @@ module Asciidoctor
 # node of AsciiDoc content. The state and methods on this class are common to
 # all content segments in an AsciiDoc document.
 class AbstractNode
-  include Substitutors, Logging
+  include Logging
+  include Substitutors
 
   # Public: Get the Hash of attributes for this node
   attr_reader :attributes
@@ -65,7 +66,7 @@ class AbstractNode
   #
   # parent - The Block to set as the parent of this Block
   #
-  # Returns the value of the parent argument
+  # Returns the the specified Block parent
   def parent= parent
     @parent, @document = parent, parent.document
   end
@@ -155,7 +156,7 @@ class AbstractNode
   #
   # name - the String name of the option
   #
-  # Returns Nothing
+  # Returns nothing
   def set_option name
     @attributes[%(#{name}-option)] = ''
     nil
@@ -220,7 +221,7 @@ class AbstractNode
   #
   # names - A single role name, a space-separated String of role names, or an Array of role names
   #
-  # Returns the value of the names argument
+  # Returns the specified String role name or Array of role names
   def role= names
     @attributes['role'] = (::Array === names) ? (names.join ' ') : names
   end
@@ -462,8 +463,8 @@ class AbstractNode
         start = doc.base_dir
       end
     else
-      start = doc.base_dir unless start
-      jail = doc.base_dir unless jail
+      start ||= doc.base_dir
+      jail ||= doc.base_dir
     end
     doc.path_resolver.system_path target, start, jail, opts
   end
@@ -542,8 +543,8 @@ class AbstractNode
         rescue
           logger.warn %(could not retrieve contents of #{opts[:label] || 'asset'} at URI: #{target}) if opts.fetch :warn_on_failure, true
         end
-      else
-        logger.warn %(cannot retrieve contents of #{opts[:label] || 'asset'} at URI: #{target} (allow-uri-read attribute not enabled)) if opts.fetch :warn_on_failure, true
+      elsif opts.fetch :warn_on_failure, true
+        logger.warn %(cannot retrieve contents of #{opts[:label] || 'asset'} at URI: #{target} (allow-uri-read attribute not enabled))
       end
     else
       target = normalize_system_path target, opts[:start], nil, target_name: (opts[:label] || 'asset')

data/lib/asciidoctor/attribute_list.rb

@@ -173,7 +173,7 @@ class AttributeList
       end
     else
       name = @block.apply_subs name if single_quoted && @block
-      if (positional_attr_name = positional_attrs[index])
+      if (positional_attr_name = positional_attrs[index]) && name
         @attributes[positional_attr_name] = name
       end
       # QUESTION should we assign the positional key even when it's claimed by a positional attribute?

data/lib/asciidoctor/block.rb

@@ -54,21 +54,21 @@ class Block < AbstractBlock
       # FIXME feels funky; we have to be defensive to get commit_subs to honor override
       # FIXME does not resolve substitution groups inside Array (e.g., [:normal])
       if (subs = opts[:subs])
-        # e.g., subs: :defult
+        case subs
+        # e.g., subs: :default
         # subs attribute is honored; falls back to opts[:default_subs], then built-in defaults based on context
-        if subs == :default
+        when :default
           @default_subs = opts[:default_subs]
         # e.g., subs: [:quotes]
         # subs attribute is not honored
-        elsif ::Array === subs
+        when ::Array
           @default_subs = subs.drop 0
           @attributes.delete 'subs'
         # e.g., subs: :normal or subs: 'normal'
         # subs attribute is not honored
         else
           @default_subs = nil
-          # interpolation is the fastest way to dup subs as a string
-          @attributes['subs'] = %(#{subs})
+          @attributes['subs'] = subs.to_s
         end
         # resolve the subs eagerly only if subs option is specified
         # QUESTION should we skip subsequent calls to commit_subs?
@@ -123,7 +123,7 @@ class Block < AbstractBlock
         result.join LF
       end
     else
-      logger.warn %(Unknown content model '#{@content_model}' for block: #{to_s}) unless @content_model == :empty
+      logger.warn %(Unknown content model '#{@content_model}' for block: #{self}) unless @content_model == :empty
       nil
     end
   end

data/lib/asciidoctor/cli/invoker.rb

@@ -88,7 +88,6 @@ module Asciidoctor
         end
 
         if outfile == '-'
-          # NOTE set_encoding returns nil on JRuby 9.1
           (tofile = @out) || ((tofile = $stdout).set_encoding UTF_8)
         elsif outfile
           opts[:mkdirs] = true
@@ -143,7 +142,7 @@ module Asciidoctor
             raise e
           else
             err.puts ::RuntimeError === e ? %(#{e.message} (#{e.class})) : e.message
-            err.puts '  Use --trace for backtrace'
+            err.puts '  Use --trace to show backtrace'
           end
         end
         nil

data/lib/asciidoctor/cli/options.rb

@@ -47,12 +47,12 @@ module Asciidoctor
           EOS
 
           opts.on('-b', '--backend BACKEND', 'set backend output format: [html5, xhtml5, docbook5, manpage] (default: html5)',
-                  'additional backends are supported via extended converters (e.g., pdf, epub3)') do |backend|
+              'additional backends are supported via extended converters (e.g., pdf, epub3)') do |backend|
             self[:attributes]['backend'] = backend
           end
           opts.on('-d', '--doctype DOCTYPE', ['article', 'book', 'manpage', 'inline'],
-                  'document type to use when converting document: [article, book, manpage, inline] (default: article)') do |doc_type|
-            self[:attributes]['doctype'] = doc_type
+              'document type to use when converting document: [article, book, manpage, inline] (default: article)') do |doctype|
+            self[:attributes]['doctype'] = doctype
           end
           opts.on('-e', '--embedded', 'suppress enclosing document structure and output an embedded document (default: false)') do
             self[:standalone] = false
@@ -61,14 +61,14 @@ module Asciidoctor
             self[:output_file] = output_file
           end
           opts.on('--safe',
-                  'set safe mode level to safe (default: unsafe)',
-                  'enables include directives, but prevents access to ancestor paths of source file',
-                  'provided for compatibility with the asciidoc command') do
+              'set safe mode level to safe (default: unsafe)',
+              'enables include directives, but prevents access to ancestor paths of source file',
+              'provided for compatibility with the asciidoc command') do
             self[:safe] = SafeMode::SAFE
           end
           opts.on('-S', '--safe-mode SAFE_MODE', (safe_mode_names = SafeMode.names),
-                  %(set safe mode level explicitly: [#{safe_mode_names.join ', '}] (default: unsafe)),
-                  'disables potentially dangerous macros in source files, such as include::[]') do |name|
+              %(set safe mode level explicitly: [#{safe_mode_names.join ', '}] (default: unsafe)),
+              'disables potentially dangerous macros in source files, such as include::[]') do |name|
             self[:safe] = SafeMode.value_for_name name
           end
           opts.on('-s', '--no-header-footer', 'suppress enclosing document structure and output an embedded document (default: false)') do
@@ -78,19 +78,19 @@ module Asciidoctor
             self[:attributes]['sectnums'] = ''
           end
           opts.on('--eruby ERUBY', ['erb', 'erubi', 'erubis'],
-                  'specify eRuby implementation to use when rendering custom ERB templates: [erb, erubi, erubis] (default: erb)') do |eruby|
+              'specify eRuby implementation to use when rendering custom ERB templates: [erb, erubi, erubis] (default: erb)') do |eruby|
             self[:eruby] = eruby
           end
           opts.on('-a', '--attribute name[=value]', 'a document attribute to set in the form of name, name!, or name=value pair',
-                  'this attribute takes precedence over the same attribute defined in the source document',
-                  'unless either the name or value ends in @ (i.e., name@=value or name=value@)') do |attr|
+              'this attribute takes precedence over the same attribute defined in the source document',
+              'unless either the name or value ends in @ (i.e., name@=value or name=value@)') do |attr|
             next if (attr = attr.rstrip).empty? || attr == '='
             attr = attr.encode UTF_8 unless attr.encoding == UTF_8
             name, _, val = attr.partition '='
             self[:attributes][name] = val
           end
           opts.on('-T', '--template-dir DIR', 'a directory containing custom converter templates that override the built-in converter (requires tilt gem)',
-                  'may be specified multiple times') do |template_dir|
+              'may be specified multiple times') do |template_dir|
             if self[:template_dirs].nil?
               self[:template_dirs] = [template_dir]
             elsif ::Array === self[:template_dirs]
@@ -119,23 +119,23 @@ module Asciidoctor
               'may be specified more than once') do |path|
             (self[:requires] ||= []).concat(path.split ',')
           end
-          opts.on('--failure-level LEVEL', %w(warning WARNING error ERROR info INFO), 'set minimum logging level that triggers non-zero exit code: [WARN, ERROR, INFO] (default: FATAL)') do |level|
+          opts.on('--failure-level LEVEL', %w(info INFO warning WARNING error ERROR fatal FATAL), 'set minimum log level that yields a non-zero exit code: [INFO, WARN, ERROR, FATAL] (default: FATAL)') do |level|
             level = 'WARN' if (level = level.upcase) == 'WARNING'
-            self[:failure_level] = ::Logger::Severity.const_get level, false
+            self[:failure_level] = ::Logger::Severity.const_get level
           end
-          opts.on('-q', '--quiet', 'silence application log messages and script warnings (default: false)') do |verbose|
+          opts.on('-q', '--quiet', 'silence application log messages and script warnings (default: false)') do
             self[:verbose] = 0
           end
-          opts.on('--trace', 'include backtrace information when reporting errors (default: false)') do |trace|
+          opts.on('--trace', 'include backtrace information when reporting errors (default: false)') do
             self[:trace] = true
           end
-          opts.on('-v', '--verbose', 'directs application messages logged at DEBUG or INFO level to STDERR (default: false)') do |verbose|
+          opts.on('-v', '--verbose', 'directs application messages logged at DEBUG or INFO level to STDERR (default: false)') do
             self[:verbose] = 2
           end
-          opts.on('-w', '--warnings', 'turn on script warnings (default: false)') do |warnings|
+          opts.on('-w', '--warnings', 'turn on script warnings (default: false)') do
             self[:warnings] = true
           end
-          opts.on('-t', '--timings', 'print timings report (default: false)') do |timing|
+          opts.on('-t', '--timings', 'print timings report (default: false)') do
             self[:timings] = true
           end
           opts.on_tail('-h', '--help [TOPIC]', 'print a help message',
@@ -161,7 +161,7 @@ module Asciidoctor
               elsif ::File.exist? (manpage_path = (::File.join ROOT_DIR, 'man', 'asciidoctor.1'))
                 $stdout.puts ::File.read manpage_path
               else
-                manpage_path = `man -w asciidoctor`.chop rescue ''
+                manpage_path = %x(man -w asciidoctor).chop rescue ''
                 if manpage_path.empty?
                   $stderr.puts 'asciidoctor: FAILED: manual page not found; try `man asciidoctor`'
                   return 1
@@ -249,7 +249,7 @@ module Asciidoctor
 
         self[:input_files] = infiles
 
-        self.delete :attributes if self[:attributes].empty?
+        delete :attributes if self[:attributes].empty?
 
         if self[:template_dirs]
           begin
@@ -258,7 +258,7 @@ module Asciidoctor
             raise $! if self[:trace]
             $stderr.puts 'asciidoctor: FAILED: \'tilt\' could not be loaded'
             $stderr.puts '  You must have the tilt gem installed (gem install tilt) to use custom backend templates'
-            $stderr.puts '  Use --trace for backtrace'
+            $stderr.puts '  Use --trace to show backtrace'
             return 1
           rescue ::SystemExit
             # not permitted here
@@ -278,7 +278,7 @@ module Asciidoctor
             rescue ::LoadError
               raise $! if self[:trace]
               $stderr.puts %(asciidoctor: FAILED: '#{path}' could not be loaded)
-              $stderr.puts '  Use --trace for backtrace'
+              $stderr.puts '  Use --trace to show backtrace'
               return 1
             rescue ::SystemExit
               # not permitted here
@@ -290,11 +290,11 @@ module Asciidoctor
       rescue ::OptionParser::MissingArgument
         $stderr.puts %(asciidoctor: option #{$!.message})
         $stdout.puts opts_parser
-        return 1
+        1
       rescue ::OptionParser::InvalidOption, ::OptionParser::InvalidArgument
         $stderr.puts %(asciidoctor: #{$!.message})
         $stdout.puts opts_parser
-        return 1
+        1
       ensure
         $VERBOSE = old_verbose
       end

data/lib/asciidoctor/convert.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Asciidoctor
   class << self
     # Public: Parse the AsciiDoc source input into an Asciidoctor::Document and

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)
@@ -374,19 +378,19 @@ class Converter::DocBook5Converter < Converter::Base
     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|
@@ -474,10 +478,16 @@ 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
@@ -533,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>
@@ -544,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
 
@@ -710,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>)