asciidoctor 2.0.12 → 2.0.16

data/lib/asciidoctor.rb

@@ -53,12 +53,12 @@ module Asciidoctor
   module SafeMode
     # A safe mode level that disables any of the security features enforced
     # by Asciidoctor (Ruby is still subject to its own restrictions).
-    UNSAFE = 0;
+    UNSAFE = 0
 
     # A safe mode level that closely parallels safe mode in AsciiDoc. This value
     # prevents access to files which reside outside of the parent directory of
     # the source file and disables any macro other than the include::[] directive.
-    SAFE = 1;
+    SAFE = 1
 
     # A safe mode level that disallows the document from setting attributes
     # that would affect the conversion of the document, in addition to all the
@@ -66,19 +66,19 @@ module Asciidoctor
     # changing the backend or source-highlighter using an attribute defined
     # in the source document header. This is the most fundamental level of
     # security for server deployments (hence the name).
-    SERVER = 10;
+    SERVER = 10
 
     # A safe mode level that disallows the document from attempting to read
     # files from the file system and including the contents of them into the
     # document, in additional to all the security features of SafeMode::SERVER.
     # For instance, this level disallows use of the include::[] directive and the
     # embedding of binary content (data uri), stylesheets and JavaScripts
-    # referenced by the document.(Asciidoctor and trusted extensions may still
+    # referenced by the document. (Asciidoctor and trusted extensions may still
     # be allowed to embed trusted content into the document).
     #
     # Since Asciidoctor is aiming for wide adoption, this level is the default
     # and is recommended for server deployments.
-    SECURE = 20;
+    SECURE = 20
 
     # A planned safe mode level that disallows the use of passthrough macros and
     # prevents the document from setting any known attributes, in addition to all
@@ -86,9 +86,9 @@ module Asciidoctor
     #
     # Please note that this level is not currently implemented (and therefore not
     # enforced)!
-    #PARANOID = 100;
+    #PARANOID = 100
 
-    @names_by_value = {}.tap {|accum| (constants false).each {|sym| accum[const_get sym, false] = sym.to_s.downcase } }
+    @names_by_value = (constants false).map {|sym| [(const_get sym), sym.to_s.downcase] }.sort {|(a), (b)| a <=> b }.to_h
 
     def self.value_for_name name
       const_get name.upcase, false
@@ -136,8 +136,8 @@ module Asciidoctor
     # Compliance value: true
     define :underline_style_section_titles, true
 
-    # Asciidoctor will unwrap the content in a preamble
-    # if the document has a title and no sections.
+    # Asciidoctor will unwrap the content in a preamble if the document has a
+    # title and no sections, then discard the empty preamble.
     # Compliance value: false
     define :unwrap_standalone_preamble, true
 
@@ -332,7 +332,7 @@ module Asciidoctor
 
   LIST_CONTINUATION = '+'
 
-  # NOTE AsciiDoc Python allows + to be preceded by TAB; Asciidoctor does not
+  # NOTE AsciiDoc.py allows + to be preceded by TAB; Asciidoctor does not
   HARD_LINE_BREAK = ' +'
 
   LINE_CONTINUATION = ' \\'
@@ -459,9 +459,9 @@ module Asciidoctor
       [:emphasis, :unconstrained, /\\?(?:\[([^\]]+)\])?__(#{CC_ALL}+?)__/m],
       # _emphasis_
       [:emphasis, :constrained, /(^|[^#{CC_WORD};:}])(?:\[([^\]]+)\])?_(\S|\S#{CC_ALL}*?\S)_(?!#{CG_WORD})/m],
-      # ##mark## (referred to in AsciiDoc Python as unquoted)
+      # ##mark## (referred to in AsciiDoc.py as unquoted)
       [:mark, :unconstrained, /\\?(?:\[([^\]]+)\])?##(#{CC_ALL}+?)##/m],
-      # #mark# (referred to in AsciiDoc Python as unquoted)
+      # #mark# (referred to in AsciiDoc.py as unquoted)
       [:mark, :constrained, /(^|[^#{CC_WORD}&;:}])(?:\[([^\]]+)\])?#(\S|\S#{CC_ALL}*?\S)#(?!#{CG_WORD})/m],
       # ^superscript^
       [:superscript, :unconstrained, /\\?(?:\[([^\]]+)\])?\^(\S+?)\^/],

data/lib/asciidoctor/abstract_block.rb

@@ -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
@@ -296,7 +296,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 +480,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 +505,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
@@ -216,11 +217,11 @@ class AbstractNode
     (val = @attributes['role']) ? (%( #{val} ).include? %( #{name} )) : false
   end
 
-  # Public: Sets the value of the role attribute on this ndoe.
+  # Public: Sets the value of the role attribute on this node.
   #
   # 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

@@ -27,7 +27,7 @@ class AttributeList
   QUOT = '"'
 
   # Public: Regular expressions for detecting the boundary of a value
-  BoundaryRxs = {
+  BoundaryRx = {
     QUOT => /.*?[^\\](?=")/,
     APOS => /.*?[^\\](?=')/,
     ',' => /.*?(?=[ \t]*(,|$))/
@@ -46,7 +46,7 @@ class AttributeList
   BlankRx = /[ \t]+/
 
   # Public: Regular expressions for skipping delimiters
-  SkipRxs = {
+  SkipRx = {
     ',' => /[ \t]*(,|$)/
   }
 
@@ -54,8 +54,8 @@ class AttributeList
     @scanner = ::StringScanner.new source
     @block = block
     @delimiter = delimiter
-    @delimiter_skip_pattern = SkipRxs[delimiter]
-    @delimiter_boundary_pattern = BoundaryRxs[delimiter]
+    @delimiter_skip_pattern = SkipRx[delimiter]
+    @delimiter_boundary_pattern = BoundaryRx[delimiter]
     @attributes = nil
   end
 
@@ -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?
@@ -214,7 +214,7 @@ class AttributeList
   end
 
   def scan_to_quote quote
-    @scanner.scan BoundaryRxs[quote]
+    @scanner.scan BoundaryRx[quote]
   end
 end
 end

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

data/lib/asciidoctor/cli/options.rb

@@ -39,19 +39,20 @@ module Asciidoctor
           # NOTE don't use squiggly heredoc to maintain compatibility with Ruby < 2.3
           opts.banner = <<-'EOS'.gsub '          ', ''
           Usage: asciidoctor [OPTION]... FILE...
-          Translate the AsciiDoc source FILE or FILE(s) into the backend output format (e.g., HTML 5, DocBook 5, etc.)
-          By default, the output is written to a file with the basename of the source file and the appropriate extension.
-          Example: asciidoctor -b html5 source.asciidoc
+          Convert the AsciiDoc input FILE(s) to the backend output format (e.g., HTML 5, DocBook 5, etc.)
+          Unless specified otherwise, the output is written to a file whose name is derived from the input file.
+          Application log messages are printed to STDERR.
+          Example: asciidoctor input.adoc
 
           EOS
 
-          opts.on('-b', '--backend BACKEND', 'set output format backend: [html5, xhtml5, docbook5, manpage] (default: html5)',
-                  'additional backends are supported via extensions (e.g., pdf, latex)') do |backend|
+          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|
             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
@@ -60,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
@@ -77,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]
@@ -120,21 +121,21 @@ module Asciidoctor
           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|
             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', 'enable verbose mode (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',
@@ -160,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
@@ -248,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
@@ -289,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.rb

@@ -366,15 +366,17 @@ module Converter
   # into - The Class into which the {Converter} module is being included.
   #
   # Returns nothing.
-  private_class_method def self.included into
+  def self.included into
     into.send :include, BackendTraits
     into.extend Config
-  end || :included
+  end
+  private_class_method :included # use separate declaration for Ruby 2.0.x
 
   # An abstract base class for defining converters that can be used to convert {AbstractNode} objects in a parsed
   # AsciiDoc document to a backend format such as HTML or DocBook.
   class Base
-    include Converter, Logging
+    include Logging
+    include Converter
 
     # Public: Converts an {AbstractNode} by delegating to a method that matches the transform value.
     #

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>)