Add admonitions to documentation renderers.

Admonitions call out places where the user should take special care.

Support added for HTML, PDF, Markdown and help text renderers.  XML files have been updated accordingly.

Contributed by Cynthia Shang.

doc/lib/BackRestDoc/Common/Doc.pm

@@ -117,7 +117,8 @@ sub parse
     my %oOut;
     my $iIndex = 0;
     my $bText = $strName eq 'text' || $strName eq 'li' || $strName eq 'p' || $strName eq 'title' ||
-                $strName eq 'summary' || $strName eq 'table-cell' || $strName eq 'table-column' || $strName eq 'list-item';
+                $strName eq 'summary' || $strName eq 'table-cell' || $strName eq 'table-column' || $strName eq 'list-item' ||
+                $strName eq 'admonition';
 
     # Store the node name
     $oOut{name} = $strName;
@@ -232,7 +233,8 @@ sub build
     }
 
     if ($$oDoc{name} eq 'p' || $$oDoc{name} eq 'title' || $$oDoc{name} eq 'summary' ||
-        $$oDoc{name} eq 'table-cell' || $$oDoc{name} eq 'table-column' || $$oDoc{name} eq 'list-item')
+        $$oDoc{name} eq 'table-cell' || $$oDoc{name} eq 'table-column' || $$oDoc{name} eq 'list-item' ||
+        $$oDoc{name} eq 'admonition')
     {
         $$oOut{field}{text} = $oDoc;
     }

doc/lib/BackRestDoc/Common/DocRender.pm

@@ -51,7 +51,8 @@ my $oRenderTag =
         # 'exe' => [undef, ''],
         'backrest' => [undef, ''],
         'proper' => ['', ''],
-        'postgres' => ['PostgreSQL', '']
+        'postgres' => ['PostgreSQL', ''],
+        'admonition' => ["\n> **", "\n"],
     },
 
     'text' =>
@@ -77,7 +78,8 @@ my $oRenderTag =
         'exe' => [undef, ''],
         'backrest' => [undef, ''],
         'proper' => ['', ''],
-        'postgres' => ['PostgreSQL', '']
+        'postgres' => ['PostgreSQL', ''],
+        'admonition' => ["\n", "\n\n"],
     },
 
     'latex' =>
@@ -108,7 +110,8 @@ my $oRenderTag =
         # 'exe' => [undef, ''],
         'backrest' => [undef, ''],
         'proper' => ['\textnormal{\texttt{', '}}'],
-        'postgres' => ['PostgreSQL', '']
+        'postgres' => ['PostgreSQL', ''],
+        'admonition' => ["\n\\begin{leftbar}\n\\textit{\\textbf{", "}\n\\end{leftbar}\n"],
     },
 
     'html' =>
@@ -136,7 +139,8 @@ my $oRenderTag =
         'setting' => ['<span class="br-setting">', '</span>'], # ??? This will need to be fixed
         'backrest' => [undef, ''],
         'proper' => ['<span class="host">', '</span>'],
-        'postgres' => ['<span class="postgres">PostgreSQL</span>', '']
+        'postgres' => ['<span class="postgres">PostgreSQL</span>', ''],
+        'admonition' => ['<div class="admonition">', '</div>'],
     }
 };
 
@@ -802,7 +806,15 @@ sub processTag
 
         $strBuffer .= $strStart;
 
-        if ($strTag eq 'p' || $strTag eq 'title' || $strTag eq 'li' || $strTag eq 'code-block' || $strTag eq 'summary')
+        # Admonitions in the reference materials are tags of the text element rather than field elements of the document so special
+        # handling is required
+        if ($strTag eq 'admonition')
+        {
+            $strBuffer .= $self->processAdmonitionStart($oTag);
+        }
+
+        if ($strTag eq 'p' || $strTag eq 'title' || $strTag eq 'li' || $strTag eq 'code-block' || $strTag eq 'summary'
+            || $strTag eq 'admonition')
         {
             $strBuffer .= $self->processText($oTag);
         }
@@ -818,6 +830,11 @@ sub processTag
             }
         }
 
+        if ($strTag eq 'admonition')
+        {
+            $strBuffer .= $self->processAdmonitionEnd($oTag);
+        }
+
         $strBuffer .= $strStop;
     }
 
@@ -829,6 +846,88 @@ sub processTag
     );
 }
 
+####################################################################################################################################
+# processAdmonitionStart
+####################################################################################################################################
+sub processAdmonitionStart
+{
+    my $self = shift;
+
+    # Assign function parameters, defaults, and log debug info
+    my
+    (
+        $strOperation,
+        $oTag
+    ) =
+        logDebugParam
+        (
+            __PACKAGE__ . '->processAdmonitionStart', \@_,
+            {name => 'oTag', trace => true}
+        );
+
+    my $strType = $self->{strType};
+    my $strBuffer = '';
+
+    # Note that any changes to the way the HTML, markdown or latex display tags may also need to be made here
+    if ($strType eq 'html')
+    {
+        my $strType = $oTag->paramGet('type');
+        $strBuffer = '<div class="' . $strType . '">' . uc($strType) . ':</div>' .
+            '<div class="' . $strType . '-text">';
+    }
+    elsif ($strType eq 'text' || $strType eq 'markdown')
+    {
+        $strBuffer = uc($oTag->paramGet('type')) . ": ";
+    }
+    elsif ($strType eq 'latex')
+    {
+        $strBuffer = uc($oTag->paramGet('type')) . ": }";
+    }
+
+    # Return from function and log return values if any
+    return logDebugReturn
+    (
+        $strOperation,
+        {name => 'strBuffer', value => $strBuffer, trace => true}
+    );
+}
+
+####################################################################################################################################
+# processAdmonitionEnd
+####################################################################################################################################
+sub processAdmonitionEnd
+{
+    my $self = shift;
+
+    # Assign function parameters, defaults, and log debug info
+    my
+    (
+        $strOperation,
+        $oTag
+    ) =
+        logDebugParam
+        (
+            __PACKAGE__ . '->processAdmonitionEnd', \@_,
+            {name => 'oTag', trace => true}
+        );
+
+    my $strType = $self->{strType};
+    my $strBuffer = '';
+
+    # Note that any changes to the way the HTML, markdown or latex display tags may also need to be made here
+    if ($strType eq 'html')
+    {
+        $strBuffer = '</div>';
+    }
+
+    # Return from function and log return values if any
+    return logDebugReturn
+    (
+        $strOperation,
+        {name => 'strBuffer', value => $strBuffer, trace => true}
+    );
+}
+
 ####################################################################################################################################
 # processText
 ####################################################################################################################################

doc/lib/BackRestDoc/Html/DocHtmlPage.pm

@@ -552,6 +552,14 @@ sub sectionProcess
 
             $iSectionNo++;
         }
+        # Add an admonition (e.g. NOTE, WARNING, etc)
+        elsif ($oChild->nameGet() eq 'admonition')
+        {
+            my $oAdmonition = $oSectionBodyElement->addNew(HTML_DIV, 'admonition');
+            $oAdmonition->addNew(HTML_DIV, $oChild->paramGet('type'), {strContent => uc($oChild->paramGet('type')) . ": "});
+            $oAdmonition->addNew(HTML_DIV, $oChild->paramGet('type') . '-text',
+                {strContent => $self->processText($oChild->textGet())});
+        }
         # Check if the child can be processed by a parent
         else
         {

doc/lib/BackRestDoc/Latex/DocLatexSection.pm

@@ -399,6 +399,14 @@ sub sectionProcess
         {
             $strLatex .= "\n" . $self->sectionProcess($oChild, $strSection, $iDepth + 1);
         }
+        # Add an admonition (e.g. NOTE, WARNING, etc)
+        elsif ($oChild->nameGet() eq 'admonition')
+        {
+            $strLatex .= "\n\\begin{leftbar}";
+            $strLatex .= "\n\\textit{\\textbf{" . uc($oChild->paramGet('type')) . ": }";
+            $strLatex .= $self->processText($oChild->textGet()) . "}";
+            $strLatex .= "\n\\end{leftbar}\n";
+        }
         # Check if the child can be processed by a parent
         else
         {

doc/lib/BackRestDoc/Markdown/DocMarkdownRender.pm

@@ -430,6 +430,11 @@ sub sectionProcess
                         (($iRowCellIdx < @oRowCellList -1) ? " | " : " |\n");
                 }
             }
+        }
+        # Add an admonition (e.g. NOTE, WARNING, etc)
+        elsif ($oChild->nameGet() eq 'admonition')
+        {
+            $strMarkdown .= "\n> **" . uc($oChild->paramGet('type')) . ":** " . $self->processText($oChild->textGet());
         }
          # Check if the child can be processed by a parent
         else

doc/resource/html/default.css

@@ -482,6 +482,28 @@ li.list-unordered
     margin-top: .5em;
 }
 
+/*******************************************************************************
+Admonition
+*******************************************************************************/
+.admonition
+{
+    padding-left: 20px;
+    font-style: italic;
+    margin: 10px 0px;
+}
+
+.admonition>.note, .admonition>.warning, .admonition>.caution, .admonition>.important, .admonition>.tip
+{
+    font-weight: bold;
+    float: left;
+    padding-right: 10px;
+}
+
+.admonition>.note-text, .admonition>.warning-text, .admonition>.caution-text, .admonition>.important-text, .admonition>.tip-text
+{
+    overflow: hidden;
+}
+
 /*******************************************************************************
 Keywords
 *******************************************************************************/

doc/resource/latex/preamble.tex

@@ -115,6 +115,10 @@
 \renewcommand{\headrulewidth}{0.4pt}
 \renewcommand{\footrulewidth}{0.4pt}
 
+% Use framed package for admonition
+% ----------------------------------------------------------------------------------------------------------------------------------
+\usepackage{framed}
+
 % ----------------------------------------------------------------------------------------------------------------------------------
 % Begin document
 % ----------------------------------------------------------------------------------------------------------------------------------

doc/xml/dtd/doc.dtd

@@ -118,7 +118,7 @@
 
 <!ELEMENT section (title?,
                    ((p|list|table|host-add|execute-list|backrest-config|postgres-config|cmd-description|
-                     option-description|code-block|block|section)*))>
+                     option-description|code-block|block|section|admonition)*))>
     <!ATTLIST section id CDATA #REQUIRED>
     <!ATTLIST section if CDATA "">
     <!ATTLIST section depend CDATA "">
@@ -222,13 +222,16 @@
                       br-setting|pg-option|pg-setting|link|user|proper)*>
 
 <!-- Formatted elements -->
+<!-- adminition type can be note, important, warning, caution and tip -->
+<!ELEMENT admonition ANY>
+    <!ATTLIST admonition type CDATA #REQUIRED>
 <!ELEMENT summary (#PCDATA|quote|b|i|ul|ol|id|code|code-block|host|file|path|cmd|setting|exe|backrest|postgres|br-option|
                    br-setting|pg-option|pg-setting|link|user|proper)*>
 <!ELEMENT p (#PCDATA|quote|b|i|id|code|code-block|host|file|path|cmd|setting|exe|backrest|postgres|br-option|br-setting|
              pg-option|pg-setting|link|user|proper)*>
     <!ATTLIST p if CDATA "">
 <!ELEMENT text (#PCDATA|quote|b|i|ul|ol|id|code|code-block|host|file|path|cmd|setting|exe|backrest|postgres|br-option|
-                br-setting|pg-option|pg-setting|link|user|proper)*>
+                br-setting|pg-option|pg-setting|link|user|proper|admonition)*>
 <!ELEMENT i (#PCDATA)>
 <!ELEMENT b (#PCDATA)>
 <!ELEMENT ul (li+)>

doc/xml/reference.xml

@@ -10,9 +10,7 @@
         <config-section-list title="Settings">
             <!-- CONFIG - LOG -->
             <config-section id="log" name="Log">
-                <text>The <setting>log</setting> section defines logging-related settings.
+                <text>The <setting>log</setting> section defines logging-related settings.<admonition type="caution">Trace-level logging may expose secrets such as keys and passwords.  Use with caution!</admonition></text>
-
-                <b>IMPORTANT NOTE</b>: Trace-level logging may expose secrets such as keys and passwords.  Use with caution!</text>
 
                 <!-- CONFIG - LOG SECTION - LOG-LEVEL-FILE KEY -->
                 <config-key-list>
@@ -358,9 +356,7 @@
                     <config-key id="repo-retention-archive" name="Archive Retention">
                         <summary>Number of backups worth of continuous WAL to retain.</summary>
 
-                        <text>Note that the WAL segments required to make a backup consistent are always retained until the backup is expired regardless of how this option is configured.
+                        <text><admonition type="note">WAL segments required to make a backup consistent are always retained until the backup is expired regardless of how this option is configured.</admonition>If this value is not set, then the archive to expire will default to the <setting>repo-retention-full</setting> (or <setting>repo-retention-diff</setting>) value corresponding to the <setting>repo-retention-archive-type</setting> if set to <setting>full</setting> (or <setting>diff</setting>). This will ensure that WAL is only expired for backups that are already expired.
-
-                        If this value is not set, then the archive to expire will default to the <setting>repo-retention-full</setting> (or <setting>repo-retention-diff</setting>) value corresponding to the <setting>repo-retention-archive-type</setting> if set to <setting>full</setting> (or <setting>diff</setting>). This will ensure that WAL is only expired for backups that are already expired.
 
                         This option must be set if <setting>repo-retention-archive-type</setting> is set to <setting>incr</setting>.  If disk space is at a premium, then this setting, in conjunction with <setting>repo-retention-archive-type</setting>, can be used to aggressively expire WAL segments. However, doing so negates the ability to perform PITR from the backups with expired WAL and is therefore <b>not</b> recommended.</text>
 
@@ -555,11 +551,7 @@
 
                         <b>Be careful using this feature -- it is very easy to exclude something critical that will make the backup inconsistent.  Be sure to test your restores!</b>
 
-                        All excluded files will be logged at <id>info</id> level along with the exclusion rule.  Be sure to audit the list of excluded files to ensure nothing unexpected is being excluded.
+                        All excluded files will be logged at <id>info</id> level along with the exclusion rule.  Be sure to audit the list of excluded files to ensure nothing unexpected is being excluded.<admonition type="note">Exclusions are not honored on delta restores.  Any files/directories that were excluded by the backup will be <i>removed</i> on delta restore.</admonition>This option should not be used to exclude <postgres/> logs from a backup.  Logs can be moved out of the <id>PGDATA</id> directory using the <postgres/> <setting>log_directory</setting> setting, which has the benefit of allowing logs to be preserved after a restore.
-
-                        Note that exclusions are not honored on delta restores.  Any files/directories that were excluded by the backup will be <i>removed</i> on delta restore.
-
-                        This option should not be used to exclude <postgres/> logs from a backup.  Logs can be moved out of the <id>PGDATA</id> directory using the <postgres/> <setting>log_directory</setting> setting, which has the benefit of allowing logs to be preserved after a restore.
 
                         Multiple exclusions may be specified on the command-line or in a configuration file.</text>
 
@@ -679,11 +671,7 @@
                     <config-key id="db-include" name="Include Database">
                         <summary>Restore only specified databases.</summary>
 
-                        <text>This feature allows only selected databases to be restored.  Databases not specifically included will be restored as sparse, zeroed files to save space but still allow <postgres/> to perform recovery.  After recovery the databases that were not included will not be accessible but can be removed with the <id>drop database</id> command.
+                        <text>This feature allows only selected databases to be restored.  Databases not specifically included will be restored as sparse, zeroed files to save space but still allow <postgres/> to perform recovery.  After recovery the databases that were not included will not be accessible but can be removed with the <id>drop database</id> command. <admonition type="note">built-in databases (<id>template0</id>, <id>template1</id>, and <id>postgres</id>) are always restored.</admonition>The <setting>{[dash]}-db-include</setting> option can be passed multiple times to specify more than one database to include.</text>
-
-                        Note that built-in databases (<id>template0</id>, <id>template1</id>, and <id>postgres</id>) are always restored.
-
-                        The <setting>{[dash]}-db-include</setting> option can be passed multiple times to specify more than one database to include.</text>
 
                         <example>db_main</example>
                     </config-key>
@@ -710,11 +698,7 @@
                     <config-key id="recovery-option" name="Recovery Option">
                         <summary>Set an option in <file>recovery.conf</file>.</summary>
 
-                        <text>See http://www.postgresql.org/docs/X.X/static/recovery-config.html for details on recovery.conf options (replace X.X with your <postgres/> version).  This option can be used multiple times.
+                        <text>See http://www.postgresql.org/docs/X.X/static/recovery-config.html for details on recovery.conf options (replace X.X with your <postgres/> version).  This option can be used multiple times.<admonition type="note">The <setting>restore_command</setting> option will be automatically generated but can be overridden with this option.  Be careful about specifying your own <setting>restore_command</setting> as <backrest/> is designed to handle this for you.  Target Recovery options (recovery_target_name, recovery_target_time, etc.) are generated automatically by <backrest/> and should not be set with this option.</admonition>Since <backrest/> does not start <postgres/> after writing the <file>recovery.conf</file> file, it is always possible to edit/check <file>recovery.conf</file> before manually restarting.</text>
-
-                        Note: The <setting>restore_command</setting> option will be automatically generated but can be overridden with this option.  Be careful about specifying your own <setting>restore_command</setting> as <backrest/> is designed to handle this for you.  Target Recovery options (recovery_target_name, recovery_target_time, etc.) are generated automatically by <backrest/> and should not be set with this option.
-
-                        Since <backrest/> does not start <postgres/> after writing the <file>recovery.conf</file> file, it is always possible to edit/check <file>recovery.conf</file> before manually restarting.</text>
 
                         <example>primary_conninfo=db.mydomain.com</example>
                     </config-key>
@@ -1262,9 +1246,7 @@
                     <option id="force" name="Force">
                         <summary>Force stanza creation.</summary>
 
-                        <text><b>Caution</b>: Use <br-option>--force</br-option> only as a last resort, when all else fails.  If data is missing from the repository then the recreated <file>.info</file> files will likely be corrupt.
+                        <text><admonition type="caution">Use <br-option>--force</br-option> only as a last resort, when all else fails.  If data is missing from the repository then the recreated <file>.info</file> files will likely be corrupt.</admonition>If the required stanza <file>.info</file> files do not exist in the repository but backups or WAL segments do exist, then this option can be used to force the stanza to be created from the existing data in the repository.  This is most likely to be useful after corruption or an incomplete restore of the repository from elsewhere.</text>
-
-                        If the required stanza <file>.info</file> files do not exist in the repository but backups or WAL segments do exist, then this option can be used to force the stanza to be created from the existing data in the repository.  This is most likely to be useful after corruption or an incomplete restore of the repository from elsewhere.</text>
 
                         <example>n</example>
                     </option>
@@ -1322,8 +1304,7 @@
             <command id="stanza-delete" name="Stanza Delete">
                 <summary>Delete a stanza.</summary>
 
-                <text>The <cmd>stanza-delete</cmd> command removes data in the repository associated with a stanza. Use this command with caution &amp;mdash; it will permanently remove all backups and archives from the <backrest/> repository for the specified stanza.
+                <text>The <cmd>stanza-delete</cmd> command removes data in the repository associated with a stanza.<admonition type="warning">Use this command with caution &amp;mdash; it will permanently remove all backups and archives from the <backrest/> repository for the specified stanza.</admonition>
-
                 To delete a stanza:
                 <ul>
                     <li>Shut down the <postgres/> cluster associated with the stanza (or use --force to override).</li>

doc/xml/release.xml

@@ -243,6 +243,14 @@
                 </release-improvement-list>
 
                 <release-development-list>
+                    <release-item>
+                        <release-item-contributor-list>
+                            <release-item-contributor id="cynthia.shang"/>
+                        </release-item-contributor-list>
+
+                        <p>Add <code>admonitions</code> to all documentation renderers (HTML, PDF, Markdown and help text) and update <file>xml</file> files accordingly.</p>
+                    </release-item>
+
                     <release-item>
                         <release-item-contributor-list>
                             <release-item-contributor id="cynthia.shang"/>

doc/xml/test.xml

@@ -10,7 +10,7 @@
 
         <p>A `Vagrantfile` is provided that contains the complete configuration required to run <backrest/> tests and build documentation.  If Vagrant is not suitable then the `Vagrantfile` still contains the configuration steps required to build a test system.</p>
 
-        <p>Note that this is not required for normal operation of <backrest/>.</p>
+        <admonition type="note">this is not required for normal operation of <backrest/>.</admonition>
     </section>
 
     <section id="testing">
@@ -50,13 +50,13 @@ vagrant ssh
 /backrest/test/test.pl --vm=co6 --module=backup --test=full --process-max=4
         </code-block>
 
-        <p>Note that process-max is only applicable to the <id>synthetic</id> and <id>full</id> tests in the <id>backup</id> module.</p>
+        <admonition type="note">process-max is only applicable to the <id>synthetic</id> and <id>full</id> tests in the <id>backup</id> module.</admonition>
 
         <code-block title="Run Tests for a Specific OS, Module, Test, Process Max, and Database Version">
 /backrest/test/test.pl --vm=co6 --module=backup --test=full --process-max=4 --pg-version=9.4
         </code-block>
 
-        <p>Note that pg-version is only applicable to the <id>full</id> test in the <id>backup</id> module.</p>
+        <admonition type="note">pg-version is only applicable to the <id>full</id> test in the <id>backup</id> module.</admonition>
 
         <code-block title="Iterate All Possible Test Combinations">
 /backrest/test/test.pl --dry-run

doc/xml/user-guide.xml

@@ -838,7 +838,7 @@
                 <list-item>[global]</list-item>
             </list>
 
-            <p><b>Note:</b> <br-option>--config</br-option>, <br-option>--config-include-path</br-option> and <br-option>--config-path</br-option> are command-line only options.</p>
+            <admonition type="note"><br-option>--config</br-option>, <br-option>--config-include-path</br-option> and <br-option>--config-path</br-option> are command-line only options.</admonition>
 
             <p><backrest/> can also be configured using environment variables as described in the <link url="command.html">command reference</link>.</p>
 
@@ -1261,7 +1261,7 @@
 
             <p>Although useful this feature may not be appropriate when another third-party backup solution is being used to take online backups as <backrest/> will not recognize that the other software is running and may terminate a backup started by that software.  However, it would be unusual to run more than one third-party backup solution at the same time so this is not likely to be a problem.</p>
 
-            <p>Note that <id>pg_dump</id> and <id>pg_basebackup</id> do not take online backups so are not affected.  It is safe to run them in conjunction with <backrest/>.</p>
+            <admonition type="note"><id>pg_dump</id> and <id>pg_basebackup</id> do not take online backups so are not affected.  It is safe to run them in conjunction with <backrest/>.</admonition>
         </section>
 
         <!-- SECTION => BACKUP - ARCHIVE-TIMEOUT -->
@@ -1373,7 +1373,7 @@
                 </execute>
             </execute-list>
 
-            <p>Note that this syntax requires <proper>jq v1.5</proper>.</p>
+            <admonition type="note">This syntax requires <proper>jq v1.5</proper>.</admonition>
         </section>
     </section>
 
@@ -1998,7 +1998,7 @@
             <backrest-config-option section="global" key="process-max">4</backrest-config-option>
         </backrest-config>
 
-        <p>Note that the region and endpoint will need to be configured to where the bucket is located.  The values given here are for the <id>us-east-1</id> region.</p>
+        <admonition type="note">The region and endpoint will need to be configured to where the bucket is located.  The values given here are for the <id>us-east-1</id> region.</admonition>
 
         <p>A role should be created to run <backrest/> and the bucket permissions should be set as restrictively as possible.  This sample policy will restrict all reads and writes to the bucket and repository path.</p>
 
@@ -2191,7 +2191,7 @@
                 <block-variable-replace key="setup-ssh-user-home-path">{[pg-home-path]}</block-variable-replace>
             </block>
 
-            <p>Note that ssh has been configured to only allow <backrest/> to be run via passwordless ssh.  This enhances security in the event that one of the service accounts is hijacked.</p>
+            <admonition type="note">ssh has been configured to only allow <backrest/> to be run via passwordless ssh.  This enhances security in the event that one of the service accounts is hijacked.</admonition>
 
             <!-- <block if="{[pg-version]} >= 11" id="setup-ssh">
                 <block-variable-replace key="setup-ssh-host">{[host-pg1]}</block-variable-replace>
@@ -2581,7 +2581,7 @@
                 </execute>
             </execute-list>
 
-            <p>Note that the <pg-setting>standby_mode</pg-setting> setting has been written into the <file>recovery.conf</file> file.  Configuring recovery settings in <backrest/> means that the <file>recovery.conf</file> file does not need to be stored elsewhere since it will be properly recreated with each restore.  The <br-setting>--type=preserve</br-setting> option can be used with the <cmd>restore</cmd> to leave the existing <file>recovery.conf</file> file in place if that behavior is preferred.</p>
+            <admonition type="note">The <pg-setting>standby_mode</pg-setting> setting has been written into the <file>recovery.conf</file> file.  Configuring recovery settings in <backrest/> means that the <file>recovery.conf</file> file does not need to be stored elsewhere since it will be properly recreated with each restore.  The <br-setting>--type=preserve</br-setting> option can be used with the <cmd>restore</cmd> to leave the existing <file>recovery.conf</file> file in place if that behavior is preferred.</admonition>
 
             <p>The <pg-setting>hot_standby</pg-setting> setting must be enabled before starting <postgres/> to allow read-only connections on <host>{[host-pg2]}</host>.  Otherwise, connection attempts will be refused.  The rest of the configuration is in case the standby is promoted to a primary.</p>
 
@@ -2887,7 +2887,7 @@
             <backrest-config-option section="global:archive-get" key="process-max">2</backrest-config-option>
         </backrest-config>
 
-        <p>Note that <br-option>process-max</br-option> is configured using command sections so that the option is not used by backup and restore.  This also allows different values for <cmd>archive-push</cmd> and <cmd>archive-get</cmd>.</p>
+        <admonition type="note"><br-option>process-max</br-option> is configured using command sections so that the option is not used by backup and restore.  This also allows different values for <cmd>archive-push</cmd> and <cmd>archive-get</cmd>.</admonition>
 
         <p>For demonstration purposes streaming replication will be broken to force <postgres/> to get WAL using the <pg-option>restore_command</pg-option>.</p>
 
@@ -2916,7 +2916,7 @@
 
             <p>The spool path holds the current status of WAL archiving.  Status files written into the spool directory are typically zero length and should consume a minimal amount of space (a few MB at most) and very little IO.  All the information in this directory can be recreated so it is not necessary to preserve the spool directory if the cluster is moved to new hardware.</p>
 
-            <p><b>NOTE:</b> In the original implementation of asynchronous archiving, WAL segments were copied to the spool directory before compression and transfer.  The new implementation copies WAL directly from the <path>pg_xlog</path> directory.  If asynchronous archiving was utilized in <proper>v1.12</proper> or prior, read the <proper>v1.13</proper> release notes carefully before upgrading.</p>
+            <admonition type="important">In the original implementation of asynchronous archiving, WAL segments were copied to the spool directory before compression and transfer.  The new implementation copies WAL directly from the <path>pg_xlog</path> directory.  If asynchronous archiving was utilized in <proper>v1.12</proper> or prior, read the <proper>v1.13</proper> release notes carefully before upgrading.</admonition>
 
             <p>The <file>[stanza]-archive-push-async.log</file> file can be used to monitor the activity of the asynchronous process.  A good way to test this is to quickly push a number of WAL segments.</p>
 

src/config/define.auto.c

@@ -145,8 +145,10 @@ static ConfigDefineCommandData configDefineCommandData[] = CFGDEFDATA_COMMAND_LI
         CFGDEFDATA_COMMAND_HELP_SUMMARY("Delete a stanza.")
         CFGDEFDATA_COMMAND_HELP_DESCRIPTION
         (
-            "The stanza-delete command removes data in the repository associated with a stanza. Use this command with caution -- "
+            "The stanza-delete command removes data in the repository associated with a stanza.\n"
-                "it will permanently remove all backups and archives from the pgBackRest repository for the specified stanza.\n"
+            "WARNING: Use this command with caution -- it will permanently remove all backups and archives from the pgBackRest "
+                "repository for the specified stanza.\n"
+            "\n"
             "\n"
             "To delete a stanza:\n"
             "\n"
@@ -914,9 +916,8 @@ static ConfigDefineOptionData configDefineOptionData[] = CFGDEFDATA_OPTION_LIST
         (
             "This feature allows only selected databases to be restored. Databases not specifically included will be restored as "
                 "sparse, zeroed files to save space but still allow PostgreSQL to perform recovery. After recovery the databases "
-                "that were not included will not be accessible but can be removed with the drop database command.\n"
+                "that were not included will not be accessible but can be removed with the drop database command. \n"
-            "\n"
+            "NOTE: built-in databases (template0, template1, and postgres) are always restored.\n"
-            "Note that built-in databases (template0, template1, and postgres) are always restored.\n"
             "\n"
             "The --db-include option can be passed multiple times to specify more than one database to include."
         )
@@ -1030,9 +1031,8 @@ static ConfigDefineOptionData configDefineOptionData[] = CFGDEFDATA_OPTION_LIST
             "\n"
             "All excluded files will be logged at info level along with the exclusion rule. Be sure to audit the list of excluded "
                 "files to ensure nothing unexpected is being excluded.\n"
-            "\n"
+            "NOTE: Exclusions are not honored on delta restores. Any files/directories that were excluded by the backup will be "
-            "Note that exclusions are not honored on delta restores. Any files/directories that were excluded by the backup will "
+                "removed on delta restore.\n"
-                "be removed on delta restore.\n"
             "\n"
             "This option should not be used to exclude PostgreSQL logs from a backup. Logs can be moved out of the PGDATA "
                 "directory using the PostgreSQL log_directory setting, which has the benefit of allowing logs to be preserved "
@@ -1119,7 +1119,7 @@ static ConfigDefineOptionData configDefineOptionData[] = CFGDEFDATA_OPTION_LIST
                 CFGDEFDATA_OPTION_OPTIONAL_HELP_SUMMARY("Force stanza creation.")
                 CFGDEFDATA_OPTION_OPTIONAL_HELP_DESCRIPTION
                 (
-                    "Caution: Use --force only as a last resort, when all else fails. If data is missing from the repository then "
+                    "CAUTION: Use --force only as a last resort, when all else fails. If data is missing from the repository then "
                         "the recreated .info files will likely be corrupt.\n"
                     "\n"
                     "If the required stanza .info files do not exist in the repository but backups or WAL segments do exist, then "
@@ -2433,8 +2433,7 @@ static ConfigDefineOptionData configDefineOptionData[] = CFGDEFDATA_OPTION_LIST
         (
             "See http://www.postgresql.org/docs/X.X/static/recovery-config.html for details on recovery.conf options (replace X.X "
                 "with your PostgreSQL version). This option can be used multiple times.\n"
-            "\n"
+            "NOTE: The restore_command option will be automatically generated but can be overridden with this option. Be careful "
-            "Note: The restore_command option will be automatically generated but can be overridden with this option. Be careful "
                 "about specifying your own restore_command as pgBackRest is designed to handle this for you. Target Recovery "
                 "options (recovery_target_name, recovery_target_time, etc.) are generated automatically by pgBackRest and should "
                 "not be set with this option.\n"
@@ -2987,8 +2986,8 @@ static ConfigDefineOptionData configDefineOptionData[] = CFGDEFDATA_OPTION_LIST
         CFGDEFDATA_OPTION_HELP_SUMMARY("Number of backups worth of continuous WAL to retain.")
         CFGDEFDATA_OPTION_HELP_DESCRIPTION
         (
-            "Note that the WAL segments required to make a backup consistent are always retained until the backup is expired "
+            "NOTE: WAL segments required to make a backup consistent are always retained until the backup is expired regardless of "
-                "regardless of how this option is configured.\n"
+                "how this option is configured.\n"
             "\n"
             "If this value is not set, then the archive to expire will default to the repo-retention-full (or repo-retention-diff) "
                 "value corresponding to the repo-retention-archive-type if set to full (or diff). This will ensure that WAL is "

test/README.md

@@ -5,8 +5,7 @@
 pgBackRest uses Docker to run tests and generate documentation. Docker's light-weight virualization provides the a good balance between proper OS emulation and performance (especially startup)
 
 A `Vagrantfile` is provided that contains the complete configuration required to run pgBackRest tests and build documentation. If Vagrant is not suitable then the `Vagrantfile` still contains the configuration steps required to build a test system.
-
+> **NOTE:** this is not required for normal operation of pgBackRest.
-Note that this is not required for normal operation of pgBackRest.
 
 ## Testing
 
@@ -44,13 +43,13 @@ _Run Tests for a Specific OS, Module, Test, and Process Max_:
 ```
 /backrest/test/test.pl --vm=co6 --module=backup --test=full --process-max=4
 ```
-Note that process-max is only applicable to the `synthetic` and `full` tests in the `backup` module.
+> **NOTE:** process-max is only applicable to the `synthetic` and `full` tests in the `backup` module.
 
 _Run Tests for a Specific OS, Module, Test, Process Max, and Database Version_:
 ```
 /backrest/test/test.pl --vm=co6 --module=backup --test=full --process-max=4 --pg-version=9.4
 ```
-Note that pg-version is only applicable to the `full` test in the `backup` module.
+> **NOTE:** pg-version is only applicable to the `full` test in the `backup` module.
 
 _Iterate All Possible Test Combinations_:
 ```

test/src/module/help/helpTest.c

@@ -332,6 +332,39 @@ testRun(void)
         TEST_RESULT_VOID(
             configParse(strLstSize(argList), strLstPtr(argList), false), "help for backup command, repo-hardlink option");
         TEST_RESULT_STR(strPtr(helpRender()), optionHelp, "    check text");
+
+        // Check admonition
+        // -------------------------------------------------------------------------------------------------------------------------
+        optionHelp = strPtr(strNewFmt(
+            "%s - 'backup' command - 'repo-retention-archive' option help\n"
+            "\n"
+            "Number of backups worth of continuous WAL to retain.\n"
+            "\n"
+            "NOTE: WAL segments required to make a backup consistent are always retained\n"
+            "until the backup is expired regardless of how this option is configured.\n"
+            "\n"
+            "If this value is not set, then the archive to expire will default to the\n"
+            "repo-retention-full (or repo-retention-diff) value corresponding to the\n"
+            "repo-retention-archive-type if set to full (or diff). This will ensure that WAL\n"
+            "is only expired for backups that are already expired.\n"
+            "\n"
+            "This option must be set if repo-retention-archive-type is set to incr. If disk\n"
+            "space is at a premium, then this setting, in conjunction with\n"
+            "repo-retention-archive-type, can be used to aggressively expire WAL segments.\n"
+            "However, doing so negates the ability to perform PITR from the backups with\n"
+            "expired WAL and is therefore not recommended.\n"
+            "\n"
+            "deprecated name: retention-archive\n",
+            helpVersion));
+
+        argList = strLstNew();
+        strLstAddZ(argList, "/path/to/pgbackrest");
+        strLstAddZ(argList, "help");
+        strLstAddZ(argList, "backup");
+        strLstAddZ(argList, "repo-retention-archive");
+        TEST_RESULT_VOID(
+            configParse(strLstSize(argList), strLstPtr(argList), false), "help for backup command, repo-retention-archive option");
+        TEST_RESULT_STR(strPtr(helpRender()), optionHelp, "    check admonition text");
     }
 
     // *****************************************************************************************************************************