diff --git a/doc/lib/BackRestDoc/Common/Doc.pm b/doc/lib/BackRestDoc/Common/Doc.pm index 225e19a3c..722e3e569 100644 --- a/doc/lib/BackRestDoc/Common/Doc.pm +++ b/doc/lib/BackRestDoc/Common/Doc.pm @@ -518,13 +518,75 @@ sub nodeRemove if (!$bRemove) { - confess &log(ERROR, "child was not found in node"); + confess &log(ERROR, "child was not found in node, could not be removed"); } # Return from function and log return values if any return logDebugReturn($strOperation); } +#################################################################################################################################### +# nodeReplace +# +# Replace a child node with one or more child nodes. +#################################################################################################################################### +sub nodeReplace +{ + my $self = shift; + + # Assign function parameters, defaults, and log debug info + my + ( + $strOperation, + $oChildRemove, + $oyChildReplace, + ) = + logDebugParam + ( + __PACKAGE__ . '->nodeReplace', \@_, + {name => 'oChildRemove', trace => true}, + {name => 'oChildReplace', trace => true}, + ); + + my $bReplace = false; + my $iReplaceIdx = undef; + my $iReplaceTotal = undef; + my $oDoc = $self->{oDoc}; + + # Error if there are no children + if (!defined($$oDoc{children})) + { + confess &log(ERROR, "node has no children"); + } + + for (my $iIndex = 0; $iIndex < @{$$oDoc{children}}; $iIndex++) + { + if ($$oDoc{children}[$iIndex] == $oChildRemove->{oDoc}) + { + splice(@{$$oDoc{children}}, $iIndex, 1); + splice(@{$$oDoc{children}}, $iIndex, 0, @{$oyChildReplace}); + + $iReplaceIdx = $iIndex; + $iReplaceTotal = scalar(@{$oyChildReplace}); + $bReplace = true; + last; + } + } + + if (!$bReplace) + { + confess &log(ERROR, "child was not found in node, could not be replaced"); + } + + # Return from function and log return values if any + return logDebugReturn + ( + $strOperation, + {name => 'iReplaceIdx', value => $iReplaceIdx, trace => true}, + {name => 'iReplaceTotal', value => $iReplaceTotal, trace => true}, + ); +} + #################################################################################################################################### # nameGet #################################################################################################################################### diff --git a/doc/lib/BackRestDoc/Common/DocExecute.pm b/doc/lib/BackRestDoc/Common/DocExecute.pm index 3946d830a..2a1d8d4d8 100644 --- a/doc/lib/BackRestDoc/Common/DocExecute.pm +++ b/doc/lib/BackRestDoc/Common/DocExecute.pm @@ -558,7 +558,9 @@ sub backrestConfig # Save the ini file iniSave($strLocalFile, $self->{config}{$strHostName}{$$hCacheKey{file}}, true); - $oHost->copyTo($strLocalFile, $$hCacheKey{file}, $oConfig->paramGet('owner', false, 'postgres:postgres'), '640'); + $oHost->copyTo( + $strLocalFile, $$hCacheKey{file}, + $self->{oManifest}->variableReplace($oConfig->paramGet('owner', false, 'postgres:postgres')), '640'); # Remove the log-console-stderr option before pushing into the cache # ??? This is not very pretty and should be replaced with a general way to hide config options @@ -764,6 +766,11 @@ sub hostKey image => $self->{oManifest}->variableReplace($oHost->paramGet('image')), }; + if (defined($oHost->paramGet('option', false))) + { + $$hCacheKey{option} = $self->{oManifest}->variableReplace($oHost->paramGet('option')); + } + if (defined($oHost->paramGet('os', false))) { $$hCacheKey{os} = $self->{oManifest}->variableReplace($oHost->paramGet('os')); @@ -958,7 +965,7 @@ sub sectionChildProcess my $oHost = new pgBackRestTest::Common::HostTest( $$hCacheKey{name}, "doc-$$hCacheKey{name}", $$hCacheKey{image}, $$hCacheKey{user}, $$hCacheKey{os}, - defined($$hCacheKey{mount}) ? [$$hCacheKey{mount}] : undef); + defined($$hCacheKey{mount}) ? [$$hCacheKey{mount}] : undef, $$hCacheKey{option}); $self->{host}{$$hCacheKey{name}} = $oHost; $self->{oManifest}->variableSet("host-$$hCacheKey{name}-ip", $oHost->{strIP}, true); diff --git a/doc/lib/BackRestDoc/Common/DocRender.pm b/doc/lib/BackRestDoc/Common/DocRender.pm index d29574736..955cebadd 100644 --- a/doc/lib/BackRestDoc/Common/DocRender.pm +++ b/doc/lib/BackRestDoc/Common/DocRender.pm @@ -9,6 +9,8 @@ use Carp qw(confess); use Exporter qw(import); our @EXPORT = qw(); +use JSON::PP; +use Storable qw(dclone); use pgBackRest::Common::Log; use pgBackRest::Common::String; @@ -48,6 +50,7 @@ my $oRenderTag = # 'code-block' => ['```', '```'], # 'exe' => [undef, ''], 'backrest' => [undef, ''], + 'proper' => ['', ''], 'postgres' => ['PostgreSQL', ''] }, @@ -73,6 +76,7 @@ my $oRenderTag = 'code-block' => ['', ''], 'exe' => [undef, ''], 'backrest' => [undef, ''], + 'proper' => ['', ''], 'postgres' => ['PostgreSQL', ''] }, @@ -103,6 +107,7 @@ my $oRenderTag = # 'code-block' => ['', ''], # 'exe' => [undef, ''], 'backrest' => [undef, ''], + 'proper' => ['\textnormal{\texttt{', '}}'], 'postgres' => ['PostgreSQL', ''] }, @@ -130,6 +135,7 @@ my $oRenderTag = 'exe' => [undef, ''], 'setting' => ['', ''], # ??? This will need to be fixed 'backrest' => [undef, ''], + 'proper' => ['', ''], 'postgres' => ['PostgreSQL', ''] } }; @@ -160,6 +166,9 @@ sub new {name => 'strRenderOutKey', required => false} ); + # Create JSON object + $self->{oJSON} = JSON::PP->new()->allow_nonref(); + # Initialize project tags $$oRenderTag{markdown}{backrest}[0] = "{[project]}"; $$oRenderTag{markdown}{exe}[0] = "{[project-exe]}"; @@ -373,6 +382,56 @@ sub build $oNode->paramSet('section', $strNewPath); } } + # Store block defines + elsif ($strName eq 'block-define') + { + my $strBlockId = $oNode->paramGet('id'); + + if (defined($self->{oyBlockDefine}{$strBlockId})) + { + confess &log(ERROR, "block ${strBlockId} is already defined"); + } + + $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') + { + my $strBlockId = $oNode->paramGet('id'); + + if (!defined($self->{oyBlockDefine}{$strBlockId})) + { + confess &log(ERROR, "block ${strBlockId} is not defined"); + } + + my $strNodeJSON = $self->{oJSON}->encode($self->{oyBlockDefine}{$strBlockId}); + + foreach my $oVariable ($oNode->nodeList('block-variable-replace')) + { + my $strVariableKey = $oVariable->paramGet('key'); + my $strVariableReplace = $oVariable->valueGet(); + + $strNodeJSON =~ s/\{\[$strVariableKey\]\}/$strVariableReplace/g; + } + + my ($iReplaceIdx, $iReplaceTotal) = $oParent->nodeReplace($oNode, $self->{oJSON}->decode($strNodeJSON)); + + # Build any new children that were added + my $iChildIdx = 0; + + foreach my $oChild ($oParent->nodeList(undef, false)) + { + if ($iChildIdx >= $iReplaceIdx && $iChildIdx < ($iReplaceIdx + $iReplaceTotal)) + { + $self->build($oChild, $oParent, $strPath, $strPathPrefix); + } + + $iChildIdx++; + } + } # Iterate all text nodes if (defined($oNode->textGet(false))) diff --git a/doc/resource/html/default.css b/doc/resource/html/default.css index e39d085db..7861222d2 100644 --- a/doc/resource/html/default.css +++ b/doc/resource/html/default.css @@ -426,7 +426,7 @@ li.list-unordered /******************************************************************************* Keywords *******************************************************************************/ -.backrest, .cmd, .postgres, .host +.backrest, .cmd, .postgres, .host, .proper { font-weight: 500; } diff --git a/doc/xml/dtd/doc.dtd b/doc/xml/dtd/doc.dtd index 4c4827dcc..52a908dd1 100644 --- a/doc/xml/dtd/doc.dtd +++ b/doc/xml/dtd/doc.dtd @@ -1,5 +1,5 @@ + (description?, variable-list?, block-define*, cleanup?, section+))> @@ -113,14 +113,24 @@ + option-description|code-block|block|section)+))> + pg-option|pg-setting|link|user|proper)*> + + + + + + + + @@ -175,6 +185,7 @@ + @@ -184,32 +195,32 @@ + br-setting|pg-option|pg-setting|link|user|proper)*> + br-setting|pg-option|pg-setting|link|user|proper)*> + br-setting|pg-option|pg-setting|link|user|proper)*> + pg-option|pg-setting|link|user|proper)*> + br-setting|pg-option|pg-setting|link|user|proper)*> + br-setting|pg-option|pg-setting|link|user|proper)*> + br-setting|pg-option|pg-setting|link|user|proper)*> @@ -221,6 +232,7 @@ + diff --git a/doc/xml/release.xml b/doc/xml/release.xml index cb3468d3b..a4bd62804 100644 --- a/doc/xml/release.xml +++ b/doc/xml/release.xml @@ -158,6 +158,18 @@
Updated async archiving documentation to more accurately describe how the new method works and how it differs from the old method.
+ +Documentation can now be built with reusable blocks to reduce duplication.
+Added ability to pass options to containers within the documentation.
+Add proper
tag to slightly emphasize proper nouns.