Re: [docbook] How to encode subfigures?

[Bob Stayton <bobs@sagehill.net>]

Hi Thibaut,
Regarding the schema side of this issue, the DocBook Technical Committee 
has never considered subfigures before as far as I know, so the schema 
does not directly support them.  In fact, although the RelaxNG schema 
seems to allow a figure to contain a figure, the Schematron rules that 
are part of the DocBook 5 standard specifically do not permit figure as 
a descendant:

 s:assert [
  test = "not(.//db:figure)"
   "figure must not occur among the children or descendants of figure"

So that rules out container solutions such as putting an informaltable 
inside figure to lay out more than one figure element, assuming you want 
valid DocBook.

If I had to solve this problem for a client using standard DocBook, I 
might recommend nesting informalfigures inside figure like this:

  <para>Ref: <xref linkend="fig"/>; <xref linkend="a"/>; <xref
    linkend="b"/></para>
  <figure xml:id="fig">
    <title>Main figure</title>
    <informalfigure role="subfigure" xml:id="a">
      <mediaobject>
        <textobject><simpara>figure</simpara></textobject>
        <caption><para>A</para></caption>
      </mediaobject>
    </informalfigure>
    <informalfigure role="subfigure" xml:id="b">
       <mediaobject>
        <textobject><simpara>figure</simpara></textobject>
        <caption><para>B</para></caption>
       </mediaobject>
    </informalfigure>
  </figure>

I used role="subfigure" on the informalfigures enhance their semantic 
meaning, and to give the stylesheet something to work with. I then added 
<caption> to the <mediaobject> elements to support the subfigure titles. 
I also moved the xml:id from mediaobject to informalfigure, since that 
is what you really want to reference. Not a perfect solution, but it is 
semantically close to what you want and does validate.

This would require stylesheet customizations to handle the formatting, 
add the numbering of subfigures, and support xrefs. I could supply 
additional hints for those if you decide to pursue this suggestion.

If you would like DocBook to directly support subfigures, you could file 
an Issue on the DocBook GitHub.  The DocBook TC considers all such requests.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net

On 7/8/2017 8:14 AM, Thibaut Cuvelier wrote:
> Dear list,
>
> I am trying to convert LaTeX subfigures into DocBook, but I cannot find 
> a way to do so. What I currently have is something like this:
>
> \begin{figure}
>      \centering
>      \begin{subfigure}[b]{0.45\textwidth}
>          \includegraphics[width=\textwidth]{A}
>          \caption{Caption A}
>      \end{subfigure}
>      ~
>      \begin{subfigure}[b]{0.45\textwidth}
>          \includegraphics[width=\textwidth]{B}
>          \caption{Caption B}
>      \end{subfigure}
>      \caption{Pictures}
> \end{figure}
>
> The result looks like this:
>
>      A                         B
>      Fig. 1.1: Caption A       Fig. 1.2: Caption B
>                  Fig 1: Pictures
>
> How can I encode something like this in proper DocBook? The only 
> reference I could find is 
> https://stackoverflow.com/questions/9177130/docbook-more-images-in-one-figure/39990292#39990292, 
> but that really looks like bad DocBook in my opinion… 
> Functionality-wise, I also have concerns about the way to make reference 
> to a subfigure. Indeed, when putting xml:id at the mediaobject level, I 
> cannot use xref in order to point to them:
>
> Don't know what gentext to create for xref to: "mediaobject"
>
> My DocBook example:
>
> <?xml version="1.0" encoding="UTF-8"?>
> <?xml-model href="http://docbook.org/xml/5.1/rng/docbook.rng"; 
> schematypens="http://relaxng.org/ns/structure/1.0";?>
> <?xml-model href="http://docbook.org/xml/5.1/sch/docbook.sch"; 
> type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron";?>
> <article xmlns="http://docbook.org/ns/docbook";
>      xmlns:xlink="http://www.w3.org/1999/xlink"; version="5.1">
>      <title>AE</title>
>      <para>Ref: <xref linkend="fig"/>; <xref linkend="a"/>; <xref 
> linkend="b"/></para>
>      <figure xml:id="fig">
>          <title>Main figure</title>
>          <mediaobject xml:id="a">
>              <textobject><simpara>A</simpara></textobject>
>          </mediaobject>
>          <mediaobject xml:id="b">
>              <textobject><simpara>B</simpara></textobject>
>          </mediaobject>
>      </figure>
> </article>
>
> My most natural solution would be to allow figure within figure, i.e. 
> things like this:
>
> <?xml version="1.0" encoding="UTF-8"?>
> <?xml-model href="http://docbook.org/xml/5.1/rng/docbook.rng"; 
> schematypens="http://relaxng.org/ns/structure/1.0";?>
> <?xml-model href="http://docbook.org/xml/5.1/sch/docbook.sch"; 
> type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron";?>
> <article xmlns="http://docbook.org/ns/docbook";
>      xmlns:xlink="http://www.w3.org/1999/xlink"; version="5.1">
>      <title>AE</title>
>      <para>Ref: <xref linkend="fig"/>; <xref linkend="a"/>; <xref 
> linkend="b"/></para>
>      <figure xml:id="fig">
>          <title>Main figure</title>
>          <figure>
>              <title>A</title>
>              <mediaobject xml:id="a">
>                  <textobject><simpara>figure</simpara></textobject>
>              </mediaobject>
>          </figure>
>          <figure>
>              <title>B</title>
>              <mediaobject xml:id="b">
>                  <textobject><simpara>figure</simpara></textobject>
>              </mediaobject>
>          </figure>
>      </figure>
> </article>
>
> Do you have a better way of encoding subfigures (with cross-referencing) 
> or is it completely out of scope for current DocBook (in which case I 
> can submit a PR for DocBook 5.2)?
>
> Thank you in advance!
> Thibaut Cuvelier