From 3dc327fd05882b2dc27e77a7922f5c275a7e2b25 Mon Sep 17 00:00:00 2001
From: Cynthia Shang <cynthia.shang@crunchydata.com>
Date: Thu, 20 Dec 2018 23:20:54 +0200
Subject: [PATCH] Add optional table captions.

All renderers now support table captions, when requested.

Contributed by Cynthia Shang.
---
 doc/lib/BackRestDoc/Html/DocHtmlElement.pm    |  2 ++
 doc/lib/BackRestDoc/Html/DocHtmlPage.pm       | 11 ++++++++++
 doc/lib/BackRestDoc/Latex/DocLatexSection.pm  | 21 +++++++++++--------
 .../BackRestDoc/Markdown/DocMarkdownRender.pm |  2 +-
 doc/resource/html/default.css                 |  9 ++++++++
 doc/xml/dtd/doc.dtd                           |  1 +
 doc/xml/release.xml                           |  2 +-
 7 files changed, 37 insertions(+), 11 deletions(-)

diff --git a/doc/lib/BackRestDoc/Html/DocHtmlElement.pm b/doc/lib/BackRestDoc/Html/DocHtmlElement.pm
index e484b0c8c..a5d7cf88b 100644
--- a/doc/lib/BackRestDoc/Html/DocHtmlElement.pm
+++ b/doc/lib/BackRestDoc/Html/DocHtmlElement.pm
@@ -28,6 +28,8 @@ use constant HTML_SPAN                                              => 'span';
     push @EXPORT, qw(HTML_SPAN);
 use constant HTML_TABLE                                             => 'table';
     push @EXPORT, qw(HTML_TABLE);
+use constant HTML_TABLE_CAPTION                                     => 'caption';
+    push @EXPORT, qw(HTML_TABLE_CAPTION);
 use constant HTML_TD                                                => 'td';
     push @EXPORT, qw(HTML_TD);
 use constant HTML_TH                                                => 'th';
diff --git a/doc/lib/BackRestDoc/Html/DocHtmlPage.pm b/doc/lib/BackRestDoc/Html/DocHtmlPage.pm
index e457e819c..eab95ac28 100644
--- a/doc/lib/BackRestDoc/Html/DocHtmlPage.pm
+++ b/doc/lib/BackRestDoc/Html/DocHtmlPage.pm
@@ -406,6 +406,17 @@ sub sectionProcess
             my $oTableElement = $oSectionBodyElement->addNew(HTML_TABLE, 'table');
             my @oyColumn;
 
+            # If there is a title element then add it as the caption for the table
+            if (defined($oTableTitle))
+            {
+                # Print the label (e.g. Table 1:) in front of the title if one exists
+                my $strTableTitle = $oTableTitle->paramTest('label') ?
+                    ($oTableTitle->paramGet('label') . ': '. $self->processText($oTableTitle->textGet())) :
+                    $self->processText($oTableTitle->textGet());
+
+                $oTableElement->addNew(HTML_TABLE_CAPTION, 'table-caption', {strContent => $strTableTitle});
+            }
+
             # Build the header
             if ($oChild->nodeTest('table-header'))
             {
diff --git a/doc/lib/BackRestDoc/Latex/DocLatexSection.pm b/doc/lib/BackRestDoc/Latex/DocLatexSection.pm
index 4affa6fd4..1f5609afa 100644
--- a/doc/lib/BackRestDoc/Latex/DocLatexSection.pm
+++ b/doc/lib/BackRestDoc/Latex/DocLatexSection.pm
@@ -241,11 +241,10 @@ sub sectionProcess
                 '{' . (defined($oHeader) && $oHeader->paramTest('width') ? ($oHeader->paramGet('width') / 100) .
                 '\textwidth' : '\textwidth') . '}';
 
+            # Build the table
+            $strLatex .= "\\vspace{1em}\\newline\n\\begin{table}\n\\begin{tabularx}${strWidth}{|";
+
             # Build the table header
-            $strLatex .= "\\vspace{1em}\\newline\n";
-
-            $strLatex .= "\\begin{tabularx}${strWidth}{|";
-
             foreach my $oColumn (@oyColumn)
             {
                 my $strAlignCode;
@@ -307,11 +306,6 @@ sub sectionProcess
 
             $strLatex .= "}\n";
 
-            if ($oChild->nodeGet("title", false))
-            {
-                $strLatex .= "\\caption{" . $self->processText($oChild->nodeGet("title")->textGet()) . ":}\\\\\n";
-            }
-
             my $strLine;
 
             if (defined($oHeader))
@@ -342,6 +336,15 @@ sub sectionProcess
             }
 
             $strLatex .= "\\hline\n\\end{tabularx}\n";
+
+            # If there is a title for the table, add it. Ignore the label since LaTex will automatically generate numbered labels.
+            # e.g. Table 1:
+            if ($oChild->nodeGet("title", false))
+            {
+                $strLatex .= "\\caption{" . $self->processText($oChild->nodeGet("title")->textGet()) . "}\n";
+            }
+
+            $strLatex .= "\\end{table}\n";
         }
         # Add descriptive text
         elsif ($oChild->nameGet() eq 'p')
diff --git a/doc/lib/BackRestDoc/Markdown/DocMarkdownRender.pm b/doc/lib/BackRestDoc/Markdown/DocMarkdownRender.pm
index acd6462aa..654194936 100644
--- a/doc/lib/BackRestDoc/Markdown/DocMarkdownRender.pm
+++ b/doc/lib/BackRestDoc/Markdown/DocMarkdownRender.pm
@@ -378,7 +378,7 @@ sub sectionProcess
             {
                 # Print the label (e.g. Table 1:) in front of the title if one exists
                 $strMarkdown .= "\n\n**" . ($oTableTitle->paramTest('label') ?
-                    ($oTableTitle->paramGet('label') . $self->processText($oTableTitle->textGet())) :
+                    ($oTableTitle->paramGet('label') . ': ' . $self->processText($oTableTitle->textGet())) :
                     $self->processText($oTableTitle->textGet())) . "**\n\n";
             }
             else
diff --git a/doc/resource/html/default.css b/doc/resource/html/default.css
index 1f3732db9..45c442c1c 100644
--- a/doc/resource/html/default.css
+++ b/doc/resource/html/default.css
@@ -303,6 +303,15 @@ Table Elements
 *******************************************************************************/
 .table
 {
+    margin-top: .5em;
+}
+
+.table-caption
+{
+    text-align: left;
+    font-size: 12pt;
+    font-weight: bold;
+    color: #396a93;
 }
 
 .table-header-row
diff --git a/doc/xml/dtd/doc.dtd b/doc/xml/dtd/doc.dtd
index ee9e72ad3..28589c715 100644
--- a/doc/xml/dtd/doc.dtd
+++ b/doc/xml/dtd/doc.dtd
@@ -207,6 +207,7 @@
 
 <!-- Table elements -->
 <!ELEMENT table (title?, table-header?, table-data)>
+    <!ATTLIST title label CDATA "">
 
 <!ELEMENT table-header (table-column+)>
     <!ATTLIST table-header width CDATA "">
diff --git a/doc/xml/release.xml b/doc/xml/release.xml
index 7f7aea243..e87e40309 100644
--- a/doc/xml/release.xml
+++ b/doc/xml/release.xml
@@ -248,7 +248,7 @@
                             <release-item-contributor id="cynthia.shang"/>
                         </release-item-contributor-list>
 
-                        <p>Add HTML table rendering and update PDF/Markdown renderers to support header-less tables.</p>
+                        <p>Add HTML table rendering and update PDF/Markdown renderers to support header-less tables. Add optional table captions.</p>
                     </release-item>
 
                     <release-item>