Improved support for --require option and section depends now default to the previous section.

doc/doc.pl

@@ -155,6 +155,12 @@ eval
             or confess "--require ${strError}";
     }
 
+    # one --include must be specified when --required is
+    if (@stryRequire && @stryInclude != 1)
+    {
+        confess "one --include is required when --require is specified";
+    }
+
     # Set console log level
     if ($bQuiet)
     {

doc/lib/BackRestDoc/Common/DocManifest.pm

@@ -577,8 +577,6 @@ sub renderOutGet
             {name => 'bIgnoreMissing', default => false, trace => true},
         );
 
-    # use Data::Dumper; print Dumper(${$self->{oManifest}}{render});
-
     if (!defined(${$self->{oManifest}}{render}{$strType}{out}{$strKey}) && !$bIgnoreMissing)
     {
         confess &log(ERROR, "render out ${strKey} does not exist");

doc/lib/BackRestDoc/Common/DocRender.pm

@@ -239,6 +239,11 @@ sub new
                 confess &log(ERROR, "path ${strPath} must begin with a /");
             }
 
+            if (!defined($self->{oSection}->{$strPath}))
+            {
+                confess &log(ERROR, "required section '${strPath}' does not exist");
+            }
+
             if (defined(${$self->{oSection}}{$strPath}))
             {
                 $self->required($strPath);
@@ -340,7 +345,8 @@ sub build
     # Build section
     if ($strName eq 'section')
     {
-        &log(DEBUG, 'build section [' . $oNode->paramGet('id') . ']');
+        my $strSectionId = $oNode->paramGet('id');
+        &log(DEBUG, "build section [${strSectionId}]");
 
         # Set path and parent-path for this section
         if (defined($strPath))
@@ -354,6 +360,78 @@ sub build
         ${$self->{oSection}}{$strPath} = $oNode;
         $oNode->paramSet('path', $strPath);
 
+        # If depend is not set then set it to the last section
+        my $strDepend = $oNode->paramGet('depend', false);
+
+        my $oContainerNode = defined($oParent) ? $oParent : $self->{oDoc};
+        my $oLastChild;
+        my $strDependPrev;
+
+        foreach my $oChild ($oContainerNode->nodeList('section', false))
+        {
+            if ($oChild->paramGet('id') eq $oNode->paramGet('id'))
+            {
+                if (defined($oLastChild))
+                {
+                    $strDependPrev = $oLastChild->paramGet('id');
+                }
+                elsif (defined($oParent->paramGet('depend', false)))
+                {
+                    $strDependPrev = $oParent->paramGet('depend');
+                }
+
+                last;
+            }
+
+            $oLastChild = $oChild;
+        }
+
+        if (defined($strDepend))
+        {
+            if (defined($strDependPrev) && $strDepend eq $strDependPrev && !$oNode->paramTest('depend-default'))
+            {
+                &log(WARN,
+                    "section '${strPath}' depend is set to '${strDepend}' which is the default, best to remove" .
+                    " because it may become obsolete if a new section is added in between");
+            }
+        }
+        else
+        {
+            $strDepend = $strDependPrev;
+        }
+
+        # If depend is defined make sure it exists
+        if (defined($strDepend))
+        {
+            # If this is a relative depend then prepend the parent section
+            if (index($strDepend, '/') != 0)
+            {
+                if (defined($oParent->paramGet('path', false)))
+                {
+                    $strDepend = $oParent->paramGet('path') . '/' . $strDepend;
+                }
+                else
+                {
+                    $strDepend = "/${strDepend}";
+                }
+            }
+
+            if (!defined($self->{oSection}->{$strDepend}))
+            {
+                confess &log(ERROR, "section '${strSectionId}' depend '${strDepend}' is not valid");
+            }
+        }
+
+        if (defined($strDepend))
+        {
+            $oNode->paramSet('depend', $strDepend);
+        }
+
+        if (defined($strDependPrev))
+        {
+            $oNode->paramSet('depend-default', $strDependPrev);
+        }
+
         # If section content is being pulled from elsewhere go get the content
         if ($oNode->paramTest('source'))
         {
@@ -394,8 +472,6 @@ sub build
 
         $self->{oyBlockDefine}{$strBlockId} = dclone($oNode->{oDoc}{children});
         $oParent->nodeRemove($oNode);
-        # use Data::Dumper; confess "DATA" . Dumper($self->{oyBlockDefine});
-        # confess "GOT HERE";
     }
     # Copy blocks
     elsif ($strName eq 'block')
@@ -484,7 +560,7 @@ sub required
             {
                 if (!defined(${$self->{oSectionRequired}}{$strChildPath}))
                 {
-                    &log(INFO, "        require section: ${strChildPath}");
+                    &log(INFO, ('    ' x (scalar(split('/', $strChildPath)) - 2)) . "        require section: ${strChildPath}");
 
                     ${$self->{oSectionRequired}}{$strChildPath} = true;
                 }

doc/lib/BackRestDoc/Html/DocHtmlPage.pm

@@ -126,7 +126,7 @@ sub process
     {
         my $oMenuBody = $oHtmlBuilder->bodyGet()->addNew(HTML_DIV, 'page-menu')->addNew(HTML_DIV, 'menu-body');
 
-        if ($self->{strRenderOutKey} ne 'index')
+        if ($self->{strRenderOutKey} ne 'index' && defined($self->{oManifest}->renderOutGet(RENDER_TYPE_HTML, 'index', true)))
         {
             my $oRenderOut = $self->{oManifest}->renderOutGet(RENDER_TYPE_HTML, 'index');
 
@@ -219,7 +219,7 @@ sub sectionProcess
             {name => 'iDepth'}
         );
 
-    &log($iDepth == 1 ? INFO : DEBUG, ('    ' x ($iDepth + 1)) . 'process section: ' . $oSection->paramGet('id'));
+    &log(INFO, ('    ' x ($iDepth + 1)) . 'process section: ' . $oSection->paramGet('path'));
 
     if ($iDepth > 3)
     {

doc/lib/BackRestDoc/Latex/DocLatexSection.pm

@@ -111,7 +111,7 @@ sub sectionProcess
             {name => 'iDepth'}
         );
 
-    &log($iDepth == 1 ? INFO : DEBUG, ('    ' x ($iDepth + 1)) . 'process section: ' . $oSection->paramGet('id'));
+    &log(INFO, ('    ' x ($iDepth + 1)) . 'process section: ' . $oSection->paramGet('path'));
 
     # Create the section
     my $strSectionTitle = $self->processText($oSection->nodeGet('title')->textGet());

doc/lib/BackRestDoc/Markdown/DocMarkdownRender.pm

@@ -176,7 +176,7 @@ sub sectionProcess
             {name => 'iDepth'}
         );
 
-    &log($iDepth == 1 ? INFO : DEBUG, ('    ' x ($iDepth + 1)) . 'process section: ' . $oSection->paramGet('id'));
+    &log(INFO, ('    ' x ($iDepth + 1)) . 'process section: ' . $oSection->paramGet('path'));
 
     if ($iDepth > 3)
     {

doc/xml/release.xml

@@ -163,6 +163,10 @@
                         <p>Documentation can now be built with reusable blocks to reduce duplication.</p>
                     </release-item>
 
+                    <release-item>
+                        <p>Improved support for <setting>--require</setting> option and section depends now default to the previous section.</p>
+                    </release-item>
+
                     <release-item>
                         <p>Added ability to pass options to containers within the documentation.</p>
                     </release-item>

doc/xml/user-guide.xml

@@ -263,13 +263,13 @@
     </section>
 
     <!-- SECTION => QUICKSTART -->
-    <section id="quickstart" depend="installation">
+    <section id="quickstart">
         <title>Quick Start</title>
 
         <p>The Quick Start section will cover basic configuration of <backrest/> and <postgres/> and introduce the <cmd>backup</cmd>, <cmd>restore</cmd>, and <cmd>info</cmd> commands.</p>
 
         <!-- SECTION => QUICKSTART - SETUP DEMO CLUSTER -->
-        <section id="setup-demo-cluster">
+        <section id="setup-demo-cluster" depend="/quickstart">
             <title>Setup Demo Cluster</title>
 
             <p>Creating the demo cluster is optional but is strongly recommended, especially for new users, since the example commands in the user guide reference the demo cluster; the examples assume the demo cluster is running on the default port (i.e. 5432). The cluster will not be started until a later section because there is still some configuration to do.</p>
@@ -313,7 +313,7 @@
         </section>
 
         <!-- SECTION => QUICKSTART - CONFIGURE STANZA -->
-        <section id="configure-stanza" depend="setup-demo-cluster">
+        <section id="configure-stanza">
             <title>Configure Cluster Stanza</title>
 
             <option-description key="stanza"/>
@@ -339,7 +339,7 @@
         </section>
 
         <!-- SECTION => QUICKSTART - CREATE REPOSITORY -->
-        <section id="create-repository" depend="configure-stanza">
+        <section id="create-repository">
             <title>Create the Repository</title>
 
             <option-description key="repo-path"/>
@@ -370,7 +370,7 @@
         </section>
 
         <!-- SECTION => QUICKSTART - CONFIGURE ARCHIVING -->
-        <section id="configure-archiving" depend="create-repository">
+        <section id="configure-archiving">
             <title>Configure Archiving</title>
 
             <p>Backing up a running <postgres/> cluster requires WAL archiving to be enabled.  Note that <i>at least</i> one WAL segment will be created during the backup process even if no explicit writes are made to the cluster.</p>
@@ -404,7 +404,7 @@
         </section>
 
         <!-- SECTION => QUICKSTART - RETENTION -->
-        <section id="retention" depend="configure-archiving">
+        <section id="retention">
             <title>Configure Retention</title>
 
             <p><backrest/> expires backups based on retention options.</p>
@@ -419,7 +419,7 @@
         </section>
 
         <!-- SECTION => QUICKSTART - STANZA CREATE -->
-        <section id="create-stanza" depend="retention">
+        <section id="create-stanza">
             <title>Create the Stanza</title>
 
             <p>The <cmd>stanza-create</cmd> command must be run on the host where the repository is located to initialize the stanza. It is recommended that the <cmd>check</cmd> command be run after <cmd>stanza-create</cmd> to ensure archiving and backups are properly configured.</p>
@@ -435,7 +435,7 @@
         </section>
 
         <!-- SECTION => QUICKSTART - CHECK CONFIGURATION -->
-        <section id="check-configuration" depend="create-stanza">
+        <section id="check-configuration">
             <title>Check the Configuration</title>
             <cmd-description key="check"/>
 
@@ -460,7 +460,7 @@
         </section>
 
         <!-- SECTION => QUICKSTART - PERFORM BACKUP -->
-        <section id="perform-backup" depend="check-configuration">
+        <section id="perform-backup">
             <title>Perform a Backup</title>
 
             <p>To perform a backup of the <postgres/> cluster run <backrest/> with the <cmd>backup</cmd> command.</p>
@@ -784,7 +784,7 @@
         </section>
 
         <!-- SECTION => RETENTION - DIFF -->
-        <section id="diff" depend="full">
+        <section id="diff">
             <title>Differential Backup Retention</title>
 
             <p>Set <br-option>retention-diff</br-option> to the number of differential backups required.  Differentials only rely on the prior full backup so it is possible to create a <quote>rolling</quote> set of differentials for the last day or more.  This allows quick restores to recent points-in-time but reduces overall space consumption.</p>
@@ -827,7 +827,7 @@
         </section>
 
         <!-- SECTION => RETENTION - ARCHIVE -->
-        <section id="archive" depend="diff">
+        <section id="archive">
             <title>Archive Retention</title>
 
             <p>Although <backrest/> automatically removes archived WAL segments when expiring backups (the default expires WAL for full backups based on the <br-option>retention-full</br-option> option), it may be useful to expire archive more aggressively to save disk space.  Note that full backups are treated as differential backups for the purpose of differential archive retention.</p>
@@ -1412,11 +1412,10 @@
                     <exe-cmd>{[project-exe]} {[dash]}-stanza={[postgres-cluster-demo]} check</exe-cmd>
                 </execute>
             </execute-list>
-
         </section>
 
         <!-- SECTION => BACKUP HOST - PERFORM BACKUP -->
-        <section id="perform-backup" depend="install-config">
+        <section id="perform-backup">
             <title>Perform a Backup</title>
 
             <p>To perform a backup of the <postgres/> cluster run <backrest/> with the <cmd>backup</cmd> command on the <host>backup</host> host.</p>
@@ -1433,7 +1432,7 @@
         </section>
 
         <!-- SECTION => BACKUP HOST - PERFORM RESTORE -->
-        <section id="perform-restore" depend="perform-backup">
+        <section id="perform-restore">
             <title>Restore a Backup</title>
 
             <p>To perform a restore of the <postgres/> cluster run <backrest/> with the <cmd>restore</cmd> command on the <host>database</host> host.</p>
@@ -1866,7 +1865,7 @@
         </section>
 
         <!-- SECTION => REPLICATION - STREAMING -->
-        <section id="streaming" depend="hot-standby">
+        <section id="streaming">
             <title>Streaming Replication</title>
 
             <p>Instead of relying solely on the WAL archive, streaming replication makes a direct connection to the master and applies changes as soon as they are made on the master.  This results in much less lag between the master and standby.</p>