From c51274d1b6a85aeb8ecf1dfffcdc68a503ac3de9 Mon Sep 17 00:00:00 2001
From: David Steele <david@pgmasters.net>
Date: Thu, 16 May 2019 08:32:02 -0400
Subject: [PATCH] Add user guides for CentOS/RHEL 6/7.

It would be better if the documentation could be generated on multiple operating systems all in one go, but the doc system currently does not allow vars to be changed once they are set.

The solution is to run the docs for each required OS and stitch the documentation together.  It's not pretty but it works and the automation in release.pl should at least make it easy to use.
---
 doc/manifest.xml             |  4 +++-
 doc/release.pl               | 35 ++++++++++++++++++++++++++++++-----
 doc/xml/index.xml            |  4 ++--
 doc/xml/metric.xml           |  2 +-
 doc/xml/release.xml          |  6 ++++++
 doc/xml/user-guide-index.xml | 15 +++++++++++++++
 doc/xml/user-guide.xml       | 24 +++++++++++++++++-------
 7 files changed, 74 insertions(+), 16 deletions(-)
 create mode 100644 doc/xml/user-guide-index.xml

diff --git a/doc/manifest.xml b/doc/manifest.xml
index d8f58548d..5bca4ebed 100644
--- a/doc/manifest.xml
+++ b/doc/manifest.xml
@@ -81,6 +81,7 @@
 
     <source-list>
         <source key="index"/>
+        <source key="user-guide-index"/>
         <source key="user-guide"/>
         <source key="reference" type="custom"/>
         <source key="release" type="custom"/>
@@ -93,7 +94,8 @@
     <render-list>
         <render type="html">
             <render-source key="index" menu="Home"/>
-            <render-source key="user-guide" menu="User Guide"/>
+            <render-source key="user-guide-index" menu="User Guides"/>
+            <render-source key="user-guide"/>
             <render-source key="release" menu="Releases"/>
             <render-source key="configuration" source="reference" menu="Configuration"/>
             <render-source key="command" source="reference" menu="Commands"/>
diff --git a/doc/release.pl b/doc/release.pl
index 9f8e2314f..a79690280 100755
--- a/doc/release.pl
+++ b/doc/release.pl
@@ -164,7 +164,20 @@ eval
         &log(INFO, "Generate Debian/Ubuntu documentation");
 
         executeTest("${strDocExe} --deploy", {bShowOutputAsync => true});
-        executeTest("${strDocExe} --deploy --cache-only --out=man --out=html --var=project-url-root=index.html");
+
+        # Generate a full copy of the docs for review
+        &log(INFO, "Generate full documentation for review");
+
+        executeTest(
+            "${strDocExe} --deploy --cache-only --key-var=os-type=centos7 --include=user-guide --out=html" .
+                " --var=project-url-root=index.html");
+        $oStorageDoc->move("$strDocHtml/user-guide.html", "$strDocHtml/user-guide-centos7.html");
+        executeTest(
+            "${strDocExe} --deploy --out-preserve --cache-only --key-var=os-type=centos6 --out=html --include=user-guide" .
+                " --var=project-url-root=index.html");
+        $oStorageDoc->move("$strDocHtml/user-guide.html", "$strDocHtml/user-guide-centos6.html");
+
+        executeTest("${strDocExe} --deploy --out-preserve --cache-only --out=man --out=html --var=project-url-root=index.html");
     }
 
     if ($bDeploy)
@@ -174,9 +187,16 @@ eval
         # Generate docs for the website history
         &log(INFO, 'Generate website ' . ($bDev ? 'dev' : 'history') . ' documentation');
 
-        executeTest(
-            $strDocExe . ($bDev ? '' : ' --deploy --cache-only') . ' --out=html --var=project-url-root=index.html' .
-            ($bDev ? ' --dev --no-exe' :  ' --exclude=release'));
+        my $strDocExeVersion =
+            ${strDocExe} . ($bDev ? ' --dev' : ' --deploy --cache-only') . ' --var=project-url-root=index.html --out=html';
+
+        executeTest("${strDocExeVersion} --key-var=os-type=centos7 --include=user-guide");
+        $oStorageDoc->move("$strDocHtml/user-guide.html", "$strDocHtml/user-guide-centos7.html");
+        executeTest("${strDocExeVersion} --out-preserve --key-var=os-type=centos6 --include=user-guide");
+        $oStorageDoc->move("$strDocHtml/user-guide.html", "$strDocHtml/user-guide-centos6.html");
+
+        $oStorageDoc->remove("$strDocHtml/release.html");
+        executeTest("${strDocExeVersion} --out-preserve --exclude=release");
 
         # Deploy to repository
         &log(INFO, '...Deploy to repository');
@@ -189,7 +209,12 @@ eval
         {
             &log(INFO, "Generate website documentation");
 
-            executeTest("${strDocExe} --deploy --cache-only --out=html");
+            executeTest("${strDocExe} --deploy --cache-only --key-var=os-type=centos7 --include=user-guide --out=html");
+            $oStorageDoc->move("$strDocHtml/user-guide.html", "$strDocHtml/user-guide-centos7.html");
+            executeTest(
+                "${strDocExe} --deploy --out-preserve --cache-only --key-var=os-type=centos6 --include=user-guide --out=html");
+            $oStorageDoc->move("$strDocHtml/user-guide.html", "$strDocHtml/user-guide-centos6.html");
+            executeTest("${strDocExe} --deploy --out-preserve --cache-only --out=html");
 
             # Deploy to repository
             &log(INFO, '...Deploy to repository');
diff --git a/doc/xml/index.xml b/doc/xml/index.xml
index 32c61b6f0..98330a3f2 100644
--- a/doc/xml/index.xml
+++ b/doc/xml/index.xml
@@ -15,7 +15,7 @@
         <variable key="github-url-wiki-backlog">{[github-url-wiki]}#backlog</variable>
 
         <variable key="backrest-url-base">http://www.pgbackrest.org</variable>
-        <variable key="backrest-page-user-guide">user-guide</variable>
+        <variable key="backrest-page-user-guide-index">user-guide-index</variable>
         <variable key="backrest-page-configuration">configuration</variable>
         <variable key="backrest-page-command">command</variable>
         <variable key="backrest-page-release">release</variable>
@@ -150,7 +150,7 @@
         <p><backrest/> strives to be easy to configure and operate:</p>
 
         <list>
-          <list-item><link page="{[backrest-page-user-guide]}">User guide</link> for {[user-guide-subtitle]} / <postgres/> {[pg-version]}.</list-item>
+          <list-item><link page="{[backrest-page-user-guide-index]}">User guides</link> for various operating systems and <postgres/> versions.</list-item>
           <list-item><link page="{[backrest-page-command]}">Command reference</link> for command-line operations.</list-item>
           <list-item><link page="{[backrest-page-configuration]}">Configuration reference</link> for creating <backrest/> configurations.</list-item>
       </list>
diff --git a/doc/xml/metric.xml b/doc/xml/metric.xml
index b83020acb..2eb49b74b 100644
--- a/doc/xml/metric.xml
+++ b/doc/xml/metric.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE doc SYSTEM "doc.dtd" [<!ENTITY metricCoverageReport SYSTEM "auto/metric-coverage-report.auto.xml">]>
 <doc title="{[project]}" subtitle="Metrics">
-    <description>!!!</description>
+    <description>{[project]} project metrics.</description>
 
     <section id="code-coverage">
         <title>Code Coverage</title>
diff --git a/doc/xml/release.xml b/doc/xml/release.xml
index 28b8d5063..0f310246c 100644
--- a/doc/xml/release.xml
+++ b/doc/xml/release.xml
@@ -195,6 +195,12 @@
             </release-core-list>
 
             <release-doc-list>
+                <release-feature-list>
+                    <release-item>
+                        <p>Add user guides for <proper>CentOS</proper>/<proper>RHEL</proper> <proper>6</proper>/<proper>7</proper>.</p>
+                    </release-item>
+                </release-feature-list>
+
                 <release-development-list>
                     <release-item>
                         <p>Automate coverage summary report generation.</p>
diff --git a/doc/xml/user-guide-index.xml b/doc/xml/user-guide-index.xml
new file mode 100644
index 000000000..0fa5b1e67
--- /dev/null
+++ b/doc/xml/user-guide-index.xml
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE doc SYSTEM "doc.dtd">
+<doc title="{[project]}" subtitle="User Guides" toc="n">
+    <description>List of available {[project]} user guides.</description>
+
+    <section id="index">
+        <title>Available User Guides</title>
+
+        <list>
+            <list-item><link url="user-guide.html">{[os-debian-title]} / PostgreSQL {[os-debian-pg-version]}</link></list-item>
+            <list-item><link url="user-guide-centos7.html">{[os-centos7-title]} / PostgreSQL {[os-centos7-pg-version]}</link></list-item>
+            <list-item><link url="user-guide-centos6.html">{[os-centos6-title]} / PostgreSQL {[os-centos6-pg-version]}</link></list-item>
+        </list>
+    </section>
+</doc>
diff --git a/doc/xml/user-guide.xml b/doc/xml/user-guide.xml
index d3266c5a8..9edf3276d 100644
--- a/doc/xml/user-guide.xml
+++ b/doc/xml/user-guide.xml
@@ -10,6 +10,16 @@
         <variable key="os-centos6">centos6</variable>
         <variable key="os-centos7">centos7</variable>
 
+        <!-- OS titles -->
+        <variable key="os-debian-title">Debian &amp; Ubuntu</variable>
+        <variable key="os-centos6-title">RHEL &amp; CentOS 6</variable>
+        <variable key="os-centos7-title">RHEL &amp; CentOS 7</variable>
+
+        <!-- Base PostgreSQL versions -->
+        <variable key="os-debian-pg-version">10</variable>
+        <variable key="os-centos6-pg-version">9.5</variable>
+        <variable key="os-centos7-pg-version">9.6</variable>
+
         <!-- User-defined package to use in documentation (use "apt" to install the current pgpd apt package) -->
         <variable key="package">none</variable>
 
@@ -27,9 +37,9 @@
         <variable key="os-image" if="{[os-type-is-centos6]}">centos:6</variable>
         <variable key="os-image" if="{[os-type-is-centos7]}">centos:7</variable>
 
-        <variable key="user-guide-subtitle" if="{[os-type-is-debian]}">Debian &amp; Ubuntu</variable>
-        <variable key="user-guide-subtitle" if="{[os-type-is-centos6]}">RHEL &amp; CentOS 6</variable>
-        <variable key="user-guide-subtitle" if="{[os-type-is-centos7]}">RHEL &amp; CentOS 7</variable>
+        <variable key="user-guide-subtitle" if="{[os-type-is-debian]}">{[os-debian-title]}</variable>
+        <variable key="user-guide-subtitle" if="{[os-type-is-centos6]}">{[os-centos6-title]}</variable>
+        <variable key="user-guide-subtitle" if="{[os-type-is-centos7]}">{[os-centos7-title]}</variable>
 
         <variable key="user-guide-os" if="{[os-type-is-debian]}">Debian/Ubuntu</variable>
         <variable key="user-guide-os" if="{[os-type-is-centos6]}">RHEL/CentOS 6</variable>
@@ -44,9 +54,9 @@
 
         <variable key="pgbackrest-repo-path">/pgbackrest</variable>
 
-        <variable key="pg-version" if="{[os-type-is-debian]}">10</variable>
-        <variable key="pg-version" if="{[os-type-is-centos6]}">9.5</variable>
-        <variable key="pg-version" if="{[os-type-is-centos7]}">9.6</variable>
+        <variable key="pg-version" if="{[os-type-is-debian]}">{[os-debian-pg-version]}</variable>
+        <variable key="pg-version" if="{[os-type-is-centos6]}">{[os-centos6-pg-version]}</variable>
+        <variable key="pg-version" if="{[os-type-is-centos7]}">{[os-centos7-pg-version]}</variable>
         <variable key="pg-version-nodot" eval="y">my $version = '{[pg-version]}'; $version =~ s/\.//g; return $version;</variable>
 
         <variable key="pg-version-upgrade" if="{[os-type-is-debian]}">11</variable>
@@ -1130,7 +1140,7 @@
 
                 <execute if="{[os-type-is-centos7]}" user="root" output="y" err-expect="3">
                     <exe-cmd>{[pg-cluster-check]}</exe-cmd>
-                    <exe-highlight>could not find the database system</exe-highlight>
+                    <exe-highlight>Failed to start PostgreSQL</exe-highlight>
                 </execute>
             </execute-list>