From e796f563c4af7a265a1f8ecd94e7f3f795a78839 Mon Sep 17 00:00:00 2001
From: David Steele <david@pgmasters.net>
Date: Fri, 3 Jun 2016 20:07:28 -0400
Subject: [PATCH] Add cmd-extra field.

Allow hidden options to be added to a command. This allows certain commands (like apt-get) to be forced during the build without making that a part of the documentation.
---
 doc/lib/BackRestDoc/Common/DocExecute.pm | 14 ++++++++++----
 doc/xml/dtd/doc.dtd                      |  3 ++-
 doc/xml/release.xml                      |  6 ++++++
 doc/xml/user-guide.xml                   | 15 ++++++++-------
 4 files changed, 26 insertions(+), 12 deletions(-)

diff --git a/doc/lib/BackRestDoc/Common/DocExecute.pm b/doc/lib/BackRestDoc/Common/DocExecute.pm
index 11e78e398..3a87348db 100644
--- a/doc/lib/BackRestDoc/Common/DocExecute.pm
+++ b/doc/lib/BackRestDoc/Common/DocExecute.pm
@@ -115,6 +115,11 @@ sub executeKey
         output => JSON::PP::false,
     };
 
+    if (defined($oCommand->fieldGet('exe-cmd-extra', false)))
+    {
+        $$hCacheKey{'cmd-extra'} = $oCommand->fieldGet('exe-cmd-extra');
+    }
+
     if (defined($oCommand->paramGet('err-expect', false)))
     {
         $$hCacheKey{'err-expect'} = $oCommand->paramGet('err-expect');
@@ -211,10 +216,11 @@ sub execute
                     confess &log(ERROR, "cannot execute on host ${strHostName} because the host does not exist");
                 }
 
-                my $oExec = $oHost->execute($strCommand,
-                                            {iExpectedExitStatus => $$hCacheKey{'err-expect'},
-                                             bSuppressError => $oCommand->paramTest('err-suppress', 'y'),
-                                             iRetrySeconds => $oCommand->paramGet('retry', false)});
+                my $oExec = $oHost->execute(
+                    $strCommand . (defined($$hCacheKey{'cmd-extra'}) ? ' ' . $$hCacheKey{'cmd-extra'} : ''),
+                    {iExpectedExitStatus => $$hCacheKey{'err-expect'},
+                     bSuppressError => $oCommand->paramTest('err-suppress', 'y'),
+                     iRetrySeconds => $oCommand->paramGet('retry', false)});
                 $oExec->begin();
                 $oExec->end();
 
diff --git a/doc/xml/dtd/doc.dtd b/doc/xml/dtd/doc.dtd
index 7fa1e9d22..c5e15c8c2 100644
--- a/doc/xml/dtd/doc.dtd
+++ b/doc/xml/dtd/doc.dtd
@@ -55,7 +55,7 @@
 <!ELEMENT execute-list (title, execute+)>
     <!ATTLIST execute-list host CDATA #REQUIRED>
     <!ATTLIST execute-list keyword CDATA "">
-<!ELEMENT execute (exe-cmd, exe-user?,  exe-var?, exe-retry?, exe-output?, (exe-highlight-type?, exe-highlight)?,
+<!ELEMENT execute (exe-cmd, exe-cmd-extra?, exe-user?,  exe-var?, exe-retry?, exe-output?, (exe-highlight-type?, exe-highlight)?,
                    exe-err-expect?, exe-err-suppress?, exe-err-suppress-stderr?)>
     <!ATTLIST execute keyword CDATA "">
     <!ATTLIST execute user CDATA "">
@@ -69,6 +69,7 @@
     <!ATTLIST execute retry CDATA "">
     <!ATTLIST execute variable-key CDATA "">
 <!ELEMENT exe-cmd (#PCDATA)>
+<!ELEMENT exe-cmd-extra (#PCDATA)>
 <!ELEMENT exe-highlight (#PCDATA)>
 <!ELEMENT exe-highlight-type (#PCDATA)>
 
diff --git a/doc/xml/release.xml b/doc/xml/release.xml
index 3829ee387..572a4fd84 100644
--- a/doc/xml/release.xml
+++ b/doc/xml/release.xml
@@ -86,6 +86,12 @@
     <release-list>
          <release date="XXXX-XX-XX" version="1.03dev" title="UNDER DEVELOPMENT">
              <release-doc-list>
+                 <release-feature-list>
+                    <release-item>
+                        <p>Allow hidden options to be added to a command.  This allows certain commands (like <id>apt-get</id>) to be forced during the build without making that a part of the documentation.</p>
+                    </release-item>
+                </release-feature-list>
+
                  <release-refactor-list>
                     <release-item>
                         <p>Recommended install location for <backrest/> modules is now <path>/usr/share/perl5</path> since <path>/usr/lib/perl5</path> has been removed from the search path in newer versions of Perl.</p>
diff --git a/doc/xml/user-guide.xml b/doc/xml/user-guide.xml
index f75c96b71..fdf05c481 100644
--- a/doc/xml/user-guide.xml
+++ b/doc/xml/user-guide.xml
@@ -156,24 +156,26 @@
             </execute>
         </host-add>
 
-        <p keyword="default"><backrest/> is written in Perl which is included with {[user-guide-os]} by default.  A few additional modules are required which are all available as packages.</p>
+        <p keyword="default"><backrest/> is written in Perl which is included with {[user-guide-os]} by default.  The <id>DBD::Pg</id> module must also be installed.</p>
 
         <execute-list host="{[host-db-master]}" keyword="default">
-            <title>Install required Perl packages</title>
+            <title>Install the <id>DBD::Pg</id> module</title>
 
             <execute user="root">
-                <exe-cmd>apt-get install libdbd-pg-perl libdbi-perl libnet-daemon-perl libplrpc-perl</exe-cmd>
+                <exe-cmd>apt-get install libdbd-pg-perl</exe-cmd>
+                <exe-cmd-extra>-y</exe-cmd-extra>
             </execute>
         </execute-list>
 
-        <p keyword="co6"><backrest/> is written in Perl which is not included with {[user-guide-os]} by default, however all required modules are all available as standard packages.</p>
+        <p keyword="co6"><backrest/> is written in Perl which is not included with {[user-guide-os]} by default, however all required modules are available as standard packages.</p>
 
         <execute-list host="{[host-db-master]}" keyword="co6">
             <title>Install required Perl packages</title>
 
             <execute user="root">
-                <exe-cmd>yum -y install perl perl-Time-HiRes perl-parent perl-JSON
+                <exe-cmd>yum install perl perl-Time-HiRes perl-parent perl-JSON
                     perl-Digest-SHA perl-DBD-Pg</exe-cmd>
+                <exe-cmd-extra>-y</exe-cmd-extra>
             </execute>
         </execute-list>
 
@@ -1397,8 +1399,7 @@
             <host-add name="{[host-db-standby]}" user="{[host-db-standby-user]}" image="{[host-db-standby-image]}" os="{[host-os]}" mount="{[host-db-standby-mount]}">
                 <!-- Install packages -->
                 <execute user="root" keyword="default">
-                    <exe-cmd>apt-get -y install libdbd-pg-perl libdbi-perl
-                        libnet-daemon-perl libplrpc-perl</exe-cmd>
+                    <exe-cmd>apt-get -y install libdbd-pg-perl</exe-cmd>
                 </execute>
 
                 <execute user="root" keyword="co6">