asciidoctor 1.5.5 → 1.5.6

data/data/stylesheets/asciidoctor-default.css

@@ -79,13 +79,12 @@ strong,b{font-weight:bold;line-height:inherit}
 small{font-size:60%;line-height:inherit}
 code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
 ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
-ul,ol,ul.no-bullet,ol.no-bullet{margin-left:1.5em}
+ul,ol{margin-left:1.5em}
 ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
 ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
 ul.square{list-style-type:square}
 ul.circle{list-style-type:circle}
 ul.disc{list-style-type:disc}
-ul.no-bullet{list-style:none}
 ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
 dl dt{margin-bottom:.3125em;font-weight:bold}
 dl dd{margin-bottom:1.25em}
@@ -121,7 +120,11 @@ strong strong{font-weight:400}
 kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
 .keyseq kbd:first-child{margin-left:0}
 .keyseq kbd:last-child{margin-right:0}
-.menuseq,.menu{color:rgba(0,0,0,.8)}
+.menuseq,.menuref{color:#000}
+.menuseq b:not(.caret),.menuref{font-weight:inherit}
+.menuseq{word-spacing:-.02em}
+.menuseq b.caret{font-size:1.25em;line-height:.8}
+.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
 b.button:before,b.button:after{position:relative;top:-1px;font-weight:400}
 b.button:before{content:"[";padding:0 3px 0 2px}
 b.button:after{content:"]";padding:0 2px 0 3px}
@@ -188,7 +191,7 @@ table.tableblock>caption.title{white-space:nowrap;overflow:visible;max-width:0}
 table.tableblock #preamble>.sectionbody>.paragraph:first-of-type p{font-size:inherit}
 .admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
 .admonitionblock>table td.icon{text-align:center;width:80px}
-.admonitionblock>table td.icon img{max-width:none}
+.admonitionblock>table td.icon img{max-width:initial}
 .admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
 .admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #ddddd8;color:rgba(0,0,0,.6)}
 .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
@@ -244,13 +247,13 @@ table.pyhltable .linenodiv{background:none!important;padding-right:0!important}
 table.tableblock{max-width:100%;border-collapse:separate}
 table.tableblock td>.paragraph:last-child p>p:last-child,table.tableblock th>p:last-child,table.tableblock td>p:last-child{margin-bottom:0}
 table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
-table.grid-all th.tableblock,table.grid-all td.tableblock{border-width:0 1px 1px 0}
-table.grid-all tfoot>tr>th.tableblock,table.grid-all tfoot>tr>td.tableblock{border-width:1px 1px 0 0}
-table.grid-cols th.tableblock,table.grid-cols td.tableblock{border-width:0 1px 0 0}
-table.grid-all *>tr>.tableblock:last-child,table.grid-cols *>tr>.tableblock:last-child{border-right-width:0}
-table.grid-rows th.tableblock,table.grid-rows td.tableblock{border-width:0 0 1px 0}
-table.grid-all tbody>tr:last-child>th.tableblock,table.grid-all tbody>tr:last-child>td.tableblock,table.grid-all thead:last-child>tr>th.tableblock,table.grid-rows tbody>tr:last-child>th.tableblock,table.grid-rows tbody>tr:last-child>td.tableblock,table.grid-rows thead:last-child>tr>th.tableblock{border-bottom-width:0}
-table.grid-rows tfoot>tr>th.tableblock,table.grid-rows tfoot>tr>td.tableblock{border-width:1px 0 0 0}
+table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}
+table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}
+table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}
+table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px 0}
+table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0 0}
+table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}
+table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0}
 table.frame-all{border-width:1px}
 table.frame-sides{border-width:0 1px}
 table.frame-topbot{border-width:1px 0}
@@ -271,10 +274,12 @@ ul li ol{margin-left:1.5em}
 dl dd{margin-left:1.125em}
 dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
 ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
-ul.unstyled,ol.unnumbered,ul.checklist,ul.none{list-style-type:none}
-ul.unstyled,ol.unnumbered,ul.checklist{margin-left:.625em}
-ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1em;font-size:.85em}
-ul.checklist li>p:first-child>input[type="checkbox"]:first-child{width:1em;position:relative;top:1px}
+ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
+ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
+ul.unstyled,ol.unstyled{margin-left:0}
+ul.checklist{margin-left:.625em}
+ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
+ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em}
 ul.inline{margin:0 auto .625em auto;margin-left:-1.375em;margin-right:0;padding:0;list-style:none;overflow:hidden}
 ul.inline>li{list-style:none;float:left;margin-left:1.375em;display:block}
 ul.inline>li>*{display:block}
@@ -291,7 +296,8 @@ ol.lowergreek{list-style-type:lower-greek}
 td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
 td.hdlist1{font-weight:bold;padding-bottom:1.25em}
 .literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
-.colist>table tr>td:first-of-type{padding:0 .75em;line-height:1}
+.colist>table tr>td:first-of-type{padding:.4em .75em 0 .75em;line-height:1;vertical-align:top}
+.colist>table tr>td:first-of-type img{max-width:initial}
 .colist>table tr>td:last-of-type{padding:.25em 0}
 .thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}
 .imageblock.left,.imageblock[style*="float: left"]{margin:.25em .625em 1.25em 0}
@@ -354,6 +360,7 @@ div.unbreakable{page-break-inside:avoid}
 .yellow{color:#bfbf00}
 .yellow-background{background-color:#fafa00}
 span.icon>.fa{cursor:default}
+a span.icon>.fa{cursor:inherit}
 .admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
 .admonitionblock td.icon .icon-note:before{content:"\f05a";color:#19407c}
 .admonitionblock td.icon .icon-tip:before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}

data/features/step_definitions.rb

@@ -20,7 +20,7 @@ end
 
 When /it is converted to html/ do
   @output = Asciidoctor.convert @source
-  #File.open('/tmp/test.adoc', 'w') {|f| f.write @source }
+  #IO.write '/tmp/test.adoc', @source
   #@output = %x{asciidoc -f compat/asciidoc.conf -o - -s /tmp/test.adoc | XMLLINT_INDENT='' xmllint --format - | tail -n +2}.rstrip
   ##@output = %x{asciidoc -f compat/asciidoc.conf -o - -s /tmp/test.adoc}
 end
@@ -29,25 +29,21 @@ When /it is converted to docbook/ do
   @output = Asciidoctor.convert @source, :backend => :docbook
 end
 
-Then /the result should match the (HTML|XML) source/ do |format, expect|
-  @output.should == expect
+Then /the result should (match|contain) the (HTML|XML) source/ do |matcher, format, expected|
+  match_expectation = matcher == 'match' ? (eq expected) : (include expected)
+  (expect @output).to match_expectation
 end
 
-Then /the result should match the (HTML|XML) structure/ do |format, expect|
-  case format
-  when 'HTML'
-    options = {:format => :html5}
-  when 'XML'
-    options = {:format => :xhtml}
-  else
-    options = {}
+Then /the result should (match|contain) the (HTML|XML) structure/ do |matcher, format, expected|
+  result = @output
+  if format == 'HTML'
+    options = { :format => :html, :disable_escape => true, :sort_attrs => false }
+  else # format == 'XML'
+    options = { :format => :xhtml, :disable_escape => true, :sort_attrs => false }
+    result = result.gsub '"/>', '" />' if result.include? '"/>'
   end
-  slim_friendly_output = @output.lines.entries.map {|line|
-    if line.start_with? '<'
-      line
-    else
-      %(|#{line})
-    end
-  }.join
-  Slim::Template.new(options) { slim_friendly_output }.render.should == Slim::Template.new(options) { expect }.render
+  result = Slim::Template.new(options) { result.each_line.map {|l| (l.start_with? '<') ? l : %(|#{l}) }.join }.render
+  expected = Slim::Template.new(options) { expected }.render
+  match_expectation = matcher == 'match' ? (eq expected) : (include expected)
+  (expect result).to match_expectation
 end

data/features/xref.feature

@@ -1,9 +1,567 @@
 # language: en
 Feature: Cross References
-  In order to create links to other sections
+  In order to create cross references between sections and blocks in the current or neighboring document
   As a writer
-  I want to be able to use a cross reference macro
+  I want to be able to use the cross reference macro to compose these references
 
+  Scenario: Create a cross reference to a block that has explicit reftext
+  Given the AsciiDoc source
+    """
+    :xrefstyle: full
+
+    See <<param-type-t>> to learn how it works.
+
+    .Parameterized Type <T>
+    [[param-type-t,that "<T>" thing]]
+    ****
+    This sidebar describes what that <T> thing is all about.
+    ****
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#param-type-t' that "&lt;T&gt;" thing
+    |to learn how it works.
+    """
+  When it is converted to docbook
+  Then the result should match the XML structure
+    """
+    simpara
+      |See
+      xref<> linkend='param-type-t'/
+      |to learn how it works.
+    sidebar xml:id='param-type-t' xreflabel='that &quot;&lt;T&gt;&quot; thing'
+      title Parameterized Type &lt;T&gt;
+      simpara This sidebar describes what that &lt;T&gt; thing is all about.
+    """
+
+  Scenario: Create a cross reference to a block that has explicit reftext with formatting
+  Given the AsciiDoc source
+    """
+    :xrefstyle: full
+
+    There are cats, then there are the <<big-cats>>.
+
+    [[big-cats,*big* cats]]
+    == Big Cats
+
+    So ferocious.
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |There are cats, then there are the
+    a< href='#big-cats' <strong>big</strong> cats
+    |.
+    """
+  When it is converted to docbook
+  Then the result should match the XML structure
+    """
+    simpara
+      |There are cats, then there are the
+      xref< linkend='big-cats'/
+      |.
+    section xml:id='big-cats' xreflabel='big cats'
+      title Big Cats
+      simpara So ferocious.
+    """
+
+  Scenario: Create a full cross reference to a numbered section
+  Given the AsciiDoc source
+    """
+    :sectnums:
+    :xrefstyle: full
+
+    See <<sect-features>> to find a complete list of features.
+
+    == About
+
+    [#sect-features]
+    === Features
+
+    All the features are listed in this section.
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#sect-features' Section 1.1, &#8220;Features&#8221;
+    |to find a complete list of features.
+    """
+
+  Scenario: Create a short cross reference to a numbered section
+  Given the AsciiDoc source
+    """
+    :sectnums:
+    :xrefstyle: short
+
+    See <<sect-features>> to find a complete list of features.
+
+    [#sect-features]
+    == Features
+
+    All the features are listed in this section.
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#sect-features' Section 1
+    |to find a complete list of features.
+    """
+
+  Scenario: Create a basic cross reference to an unnumbered section
+  Given the AsciiDoc source
+    """
+    :xrefstyle: full
+
+    See <<sect-features>> to find a complete list of features.
+
+    [#sect-features]
+    == Features
+
+    All the features are listed in this section.
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#sect-features' Features
+    |to find a complete list of features.
+    """
+
+  Scenario: Create a basic cross reference to a numbered section when the section reference signifier is disabled
+  Given the AsciiDoc source
+    """
+    :sectnums:
+    :xrefstyle: full
+    :!section-refsig:
+
+    See <<sect-features>> to find a complete list of features.
+
+    [#sect-features]
+    == Features
+
+    All the features are listed in this section.
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#sect-features' 1, &#8220;Features&#8221;
+    |to find a complete list of features.
+    """
+
+  Scenario: Create a full cross reference to a numbered chapter
+  Given the AsciiDoc source
+    """
+    :doctype: book
+    :sectnums:
+    :xrefstyle: full
+
+    See <<chap-features>> to find a complete list of features.
+
+    [#chap-features]
+    == Features
+
+    All the features are listed in this chapter.
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#chap-features' Chapter 1, <em>Features</em>
+    |to find a complete list of features.
+    """
+
+  Scenario: Create a short cross reference to a numbered chapter
+  Given the AsciiDoc source
+    """
+    :doctype: book
+    :sectnums:
+    :xrefstyle: short
+
+    See <<chap-features>> to find a complete list of features.
+
+    [#chap-features]
+    == Features
+
+    All the features are listed in this chapter.
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#chap-features' Chapter 1
+    |to find a complete list of features.
+    """
+
+  Scenario: Create a basic cross reference to a numbered chapter
+  Given the AsciiDoc source
+    """
+    :doctype: book
+    :sectnums:
+    :xrefstyle: basic
+
+    See <<chap-features>> to find a complete list of features.
+
+    [#chap-features]
+    == Features
+
+    All the features are listed in this chapter.
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#chap-features' <em>Features</em>
+    |to find a complete list of features.
+    """
+
+  Scenario: Create a basic cross reference to an unnumbered chapter
+  Given the AsciiDoc source
+    """
+    :doctype: book
+    :xrefstyle: full
+
+    See <<chap-features>> to find a complete list of features.
+
+    [#chap-features]
+    == Features
+
+    All the features are listed in this chapter.
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#chap-features' <em>Features</em>
+    |to find a complete list of features.
+    """
+
+  Scenario: Create a cross reference to a chapter using a custom chapter reference signifier
+  Given the AsciiDoc source
+    """
+    :doctype: book
+    :sectnums:
+    :xrefstyle: full
+    :chapter-refsig: Ch
+
+    See <<chap-features>> to find a complete list of features.
+
+    [#chap-features]
+    == Features
+
+    All the features are listed in this chapter.
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#chap-features' Ch 1, <em>Features</em>
+    |to find a complete list of features.
+    """
+
+  Scenario: Create a full cross reference to a numbered appendix
+  Given the AsciiDoc source
+    """
+    :sectnums:
+    :xrefstyle: full
+
+    See <<app-features>> to find a complete list of features.
+
+    [appendix#app-features]
+    == Features
+
+    All the features are listed in this appendix.
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#app-features' Appendix A, <em>Features</em>
+    |to find a complete list of features.
+    """
+
+  Scenario: Create a short cross reference to a numbered appendix
+  Given the AsciiDoc source
+    """
+    :sectnums:
+    :xrefstyle: short
+
+    See <<app-features>> to find a complete list of features.
+
+    [appendix#app-features]
+    == Features
+
+    All the features are listed in this appendix.
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#app-features' Appendix A
+    |to find a complete list of features.
+    """
+
+  Scenario: Create a full cross reference to an appendix even when section numbering is disabled
+  Given the AsciiDoc source
+    """
+    :xrefstyle: full
+
+    See <<app-features>> to find a complete list of features.
+
+    [appendix#app-features]
+    == Features
+
+    All the features are listed in this appendix.
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#app-features' Appendix A, <em>Features</em>
+    |to find a complete list of features.
+    """
+
+  Scenario: Create a full cross reference to a numbered formal block
+  Given the AsciiDoc source
+    """
+    :xrefstyle: full
+
+    See <<tbl-features>> to find a table of features.
+
+    .Features
+    [#tbl-features%autowidth]
+    |===
+    |Text formatting |Formats text for display.
+    |===
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#tbl-features' Table 1, &#8220;Features&#8221;
+    |to find a table of features.
+    """
+
+  Scenario: Create a short cross reference to a numbered formal block
+  Given the AsciiDoc source
+    """
+    :xrefstyle: short
+
+    See <<tbl-features>> to find a table of features.
+
+    .Features
+    [#tbl-features%autowidth]
+    |===
+    |Text formatting |Formats text for display.
+    |===
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#tbl-features' Table 1
+    |to find a table of features.
+    """
+
+  Scenario: Create a basic cross reference to a numbered formal block when the caption prefix is disabled
+  Given the AsciiDoc source
+    """
+    :xrefstyle: full
+    :!table-caption:
+
+    See <<tbl-features>> to find a table of features.
+
+    .Features
+    [#tbl-features%autowidth]
+    |===
+    |Text formatting |Formats text for display.
+    |===
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#tbl-features' Features
+    |to find a table of features.
+    """
+
+  Scenario: Create a cross reference to a numbered formal block with a custom caption prefix
+  Given the AsciiDoc source
+    """
+    :xrefstyle: full
+    :table-caption: Tbl
+
+    See <<tbl-features>> to find a table of features.
+
+    .Features
+    [#tbl-features%autowidth]
+    |===
+    |Text formatting |Formats text for display.
+    |===
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#tbl-features' Tbl 1, &#8220;Features&#8221;
+    |to find a table of features.
+    """
+
+  Scenario: Create a full cross reference to a formal image block
+  Given the AsciiDoc source
+    """
+    :xrefstyle: full
+
+    Behold, <<tiger>>!
+
+    .The ferocious Ghostscript tiger
+    [#tiger]
+    image::tiger.svg[Ghostscript tiger]
+    """
+  When it is converted to html
+  Then the result should match the HTML structure
+    """
+    .paragraph: p
+      |Behold,
+      a< href='#tiger' Figure 1, &#8220;The ferocious Ghostscript tiger&#8221;
+      |!
+    #tiger.imageblock
+      .content: img src='tiger.svg' alt='Ghostscript tiger'
+      .title Figure 1. The ferocious Ghostscript tiger
+    """
+
+  Scenario: Create a short cross reference to a formal image block
+  Given the AsciiDoc source
+    """
+    :xrefstyle: short
+
+    Behold, <<tiger>>!
+
+    .The ferocious Ghostscript tiger
+    [#tiger]
+    image::tiger.svg[Ghostscript tiger]
+    """
+  When it is converted to html
+  Then the result should match the HTML structure
+    """
+    .paragraph: p
+      |Behold,
+      a< href='#tiger' Figure 1
+      |!
+    #tiger.imageblock
+      .content: img src='tiger.svg' alt='Ghostscript tiger'
+      .title Figure 1. The ferocious Ghostscript tiger
+    """
+
+  Scenario: Create a full cross reference to a block with an explicit caption
+  Given the AsciiDoc source
+    """
+    :xrefstyle: full
+
+    See <<diagram-1>> and <<diagram-2>>.
+
+    .Managing Orders
+    [#diagram-1,caption="Diagram {counter:diag-number}. "]
+    image::managing-orders.png[Managing Orders]
+
+    .Managing Inventory
+    [#diagram-2,caption="Diagram {counter:diag-number}. "]
+    image::managing-inventory.png[Managing Inventory]
+    """
+  When it is converted to html
+  Then the result should match the HTML structure
+    """
+    .paragraph: p
+      |See
+      a<> href='#diagram-1' Diagram 1, &#8220;Managing Orders&#8221;
+      |and
+      a< href='#diagram-2' Diagram 2, &#8220;Managing Inventory&#8221;
+      |.
+    #diagram-1.imageblock
+      .content: img src='managing-orders.png' alt='Managing Orders'
+      .title Diagram 1. Managing Orders
+    #diagram-2.imageblock
+      .content: img src='managing-inventory.png' alt='Managing Inventory'
+      .title Diagram 2. Managing Inventory
+    """
+
+  Scenario: Create a short cross reference to a block with an explicit caption
+  Given the AsciiDoc source
+    """
+    :xrefstyle: short
+
+    See <<diagram-1>> and <<diagram-2>>.
+
+    .Managing Orders
+    [#diagram-1,caption="Diagram {counter:diag-number}. "]
+    image::managing-orders.png[Managing Orders]
+
+    .Managing Inventory
+    [#diagram-2,caption="Diagram {counter:diag-number}. "]
+    image::managing-inventory.png[Managing Inventory]
+    """
+  When it is converted to html
+  Then the result should match the HTML structure
+    """
+    .paragraph: p
+      |See
+      a<> href='#diagram-1' Diagram 1
+      |and
+      a< href='#diagram-2' Diagram 2
+      |.
+    #diagram-1.imageblock
+      .content: img src='managing-orders.png' alt='Managing Orders'
+      .title Diagram 1. Managing Orders
+    #diagram-2.imageblock
+      .content: img src='managing-inventory.png' alt='Managing Inventory'
+      .title Diagram 2. Managing Inventory
+    """
+
+  Scenario: Create a basic cross reference to an unnumbered formal block
+  Given the AsciiDoc source
+    """
+    :xrefstyle: full
+
+    See <<data>> to find the data used in this report.
+
+    .Data
+    [#data]
+    ....
+    a
+    b
+    c
+    ....
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |See
+    a<> href='#data' Data
+    |to find the data used in this report.
+    """
+
+  Scenario: Use title as cross reference text to refer to a formal admonition block
+  Given the AsciiDoc source
+    """
+    :xrefstyle: full
+
+    Recall in <<essential-tip-1>>, we told you how to speed up this process.
+
+    .Essential tip #1
+    [#essential-tip-1]
+    TIP: You can speed up this process by pressing the turbo button.
+    """
+  When it is converted to html
+  Then the result should contain the HTML structure
+    """
+    |Recall in
+    a< href='#essential-tip-1' Essential tip #1
+    |, we told you how to speed up this process.
+    """
 
   Scenario: Create a cross reference from an AsciiDoc cell to a section
   Given the AsciiDoc source
@@ -11,9 +569,9 @@ Feature: Cross References
     |===
     a|See <<_install>>
     |===
-    
+
     == Install
-    
+
     Instructions go here.
     """
   When it is converted to html
@@ -27,15 +585,14 @@ Feature: Cross References
           td.tableblock.halign-left.valign-top
             div
               .paragraph: p
-                'See
-                a href='#_install' Install
+                |See
+                a< href='#_install' Install
     .sect1
       h2#_install Install
       .sectionbody
         .paragraph: p Instructions go here.
     """
 
-
     Scenario: Create a cross reference using the target section title
     Given the AsciiDoc source
       """
@@ -56,12 +613,11 @@ Feature: Cross References
       .sect1
         h2#_section_two Section Two
         .sectionbody: .paragraph: p
-          'refer to
-          a href='#_section_one' Section One
+          |refer to
+          a< href='#_section_one' Section One
       """
 
-
-    Scenario: Create a cross reference using the target reftext
+    Scenario: Create a natural cross reference using the reftext of the target section
     Given the AsciiDoc source
       """
       [reftext="the first section"]
@@ -82,10 +638,21 @@ Feature: Cross References
       .sect1
         h2#_section_two Section Two
         .sectionbody: .paragraph: p
-          'refer to
-          a href='#_section_one' the first section
+          |refer to
+          a< href='#_section_one' the first section
+      """
+    When it is converted to docbook
+    Then the result should match the XML structure
+      """
+      section xml:id='_section_one' xreflabel='the first section'
+        title Section One
+        simpara content
+      section xml:id='_section_two'
+        title Section Two
+        simpara
+          |refer to
+          xref< linkend='_section_one'/
       """
-
 
     Scenario: Create a cross reference using the formatted target title
     Given the AsciiDoc source
@@ -103,14 +670,11 @@ Feature: Cross References
       """
       .sect1
         h2#_section_strong_one_strong
-          'Section
-          strong One
+          |Section <strong>One</strong>
         .sectionbody: .paragraph: p content
       .sect1
         h2#_section_two Section Two
         .sectionbody: .paragraph: p
-          'refer to
-          a href='#_section_strong_one_strong'
-            'Section
-            strong One
+          |refer to
+          a< href='#_section_strong_one_strong' Section <strong>One</strong>
       """