mirror of
https://github.com/pgbackrest/pgbackrest.git
synced 2025-01-30 05:39:12 +02:00
1eb0162208
Migrate generation of these files from help.xml to the intermediate documentation format. This allows us to share a lot of code that is already in C and remove duplicated code in Perl. More duplicate code can be removed in Perl once man generation is migrated. Also update the unit test harness to allow testing of modules in the doc directory.
1090 lines
35 KiB
Perl
1090 lines
35 KiB
Perl
####################################################################################################################################
|
|
# DOC RENDER MODULE
|
|
####################################################################################################################################
|
|
package pgBackRestDoc::Common::DocRender;
|
|
|
|
use strict;
|
|
use warnings FATAL => qw(all);
|
|
use Carp qw(confess);
|
|
|
|
use Exporter qw(import);
|
|
our @EXPORT = qw();
|
|
use JSON::PP;
|
|
use Storable qw(dclone);
|
|
|
|
use pgBackRestDoc::Common::DocManifest;
|
|
use pgBackRestDoc::Common::Log;
|
|
use pgBackRestDoc::Common::String;
|
|
|
|
####################################################################################################################################
|
|
# XML tag/param constants
|
|
####################################################################################################################################
|
|
use constant XML_SECTION_PARAM_ANCHOR => 'anchor';
|
|
push @EXPORT, qw(XML_SECTION_PARAM_ANCHOR);
|
|
use constant XML_SECTION_PARAM_ANCHOR_VALUE_NOINHERIT => 'no-inherit';
|
|
push @EXPORT, qw(XML_SECTION_PARAM_ANCHOR_VALUE_NOINHERIT);
|
|
|
|
####################################################################################################################################
|
|
# Render tags for various output types
|
|
####################################################################################################################################
|
|
my $oRenderTag =
|
|
{
|
|
'markdown' =>
|
|
{
|
|
'br' => ['\n', ''],
|
|
'quote' => ['"', '"'],
|
|
'b' => ['**', '**'],
|
|
'i' => ['_', '_'],
|
|
# 'bi' => ['_**', '**_'],
|
|
'list-item' => ["\n", ""],
|
|
'list-item' => ['- ', "\n"],
|
|
'id' => ['`', '`'],
|
|
'file' => ['`', '`'],
|
|
'path' => ['`', '`'],
|
|
'cmd' => ['`', '`'],
|
|
'param' => ['`', '`'],
|
|
'setting' => ['`', '`'],
|
|
'pg-setting' => ['`', '`'],
|
|
'code' => ['`', '`'],
|
|
# 'code-block' => ['```', '```'],
|
|
# 'exe' => [undef, ''],
|
|
'backrest' => [undef, ''],
|
|
'proper' => ['', ''],
|
|
'postgres' => ['PostgreSQL', ''],
|
|
'admonition' => ["\n> **", "\n"],
|
|
},
|
|
|
|
'text' =>
|
|
{
|
|
'br' => ['\n', ''],
|
|
'quote' => ['"', '"'],
|
|
'p' => ['', "\n\n"],
|
|
'b' => ['', ''],
|
|
'i' => ['', ''],
|
|
# 'bi' => ['', ''],
|
|
'list' => ["", "\n"],
|
|
'list-item' => ['* ', "\n"],
|
|
'id' => ['', ''],
|
|
'host' => ['', ''],
|
|
'file' => ['', ''],
|
|
'path' => ['', ''],
|
|
'cmd' => ['', ''],
|
|
'br-option' => ['', ''],
|
|
'pg-setting' => ['', ''],
|
|
'param' => ['', ''],
|
|
'setting' => ['', ''],
|
|
'code' => ['', ''],
|
|
'code-block' => ['', ''],
|
|
'exe' => [undef, ''],
|
|
'backrest' => [undef, ''],
|
|
'proper' => ['', ''],
|
|
'postgres' => ['PostgreSQL', ''],
|
|
'admonition' => ['', "\n\n"],
|
|
},
|
|
|
|
'latex' =>
|
|
{
|
|
'br' => ['\\\vspace{1em}', ''],
|
|
'quote' => ['``', '"'],
|
|
'p' => ["\n\\begin{sloppypar}", "\\end{sloppypar}\n"],
|
|
'b' => ['\textbf{', '}'],
|
|
'i' => ['\textit{', '}'],
|
|
# 'bi' => ['', ''],
|
|
'list' => ["\\begin{itemize}\n", "\\end{itemize}\n"],
|
|
'list-item' => ['\item ', "\n"],
|
|
'id' => ['\textnormal{\texttt{', '}}'],
|
|
'host' => ['\textnormal{\textbf{', '}}'],
|
|
'file' => ['\textnormal{\texttt{', '}}'],
|
|
'path' => ['\textnormal{\texttt{', '}}'],
|
|
'cmd' => ['\textnormal{\texttt{', "}}"],
|
|
'user' => ['\textnormal{\texttt{', '}}'],
|
|
'br-option' => ['', ''],
|
|
# 'param' => ['\texttt{', '}'],
|
|
# 'setting' => ['\texttt{', '}'],
|
|
'br-option' => ['\textnormal{\texttt{', '}}'],
|
|
'br-setting' => ['\textnormal{\texttt{', '}}'],
|
|
'pg-option' => ['\textnormal{\texttt{', '}}'],
|
|
'pg-setting' => ['\textnormal{\texttt{', '}}'],
|
|
'code' => ['\textnormal{\texttt{', '}}'],
|
|
# 'code' => ['\texttt{', '}'],
|
|
# 'code-block' => ['', ''],
|
|
# 'exe' => [undef, ''],
|
|
'backrest' => [undef, ''],
|
|
'proper' => ['\textnormal{\texttt{', '}}'],
|
|
'postgres' => ['PostgreSQL', ''],
|
|
'admonition' =>
|
|
["\n\\vspace{.5em}\\begin{leftbar}\n\\begin{sloppypar}\\textit{\\textbf{", "}\\end{sloppypar}\n\\end{leftbar}\n"],
|
|
},
|
|
|
|
'html' =>
|
|
{
|
|
'br' => ['<br/>', ''],
|
|
'quote' => ['<q>', '</q>'],
|
|
'b' => ['<b>', '</b>'],
|
|
'i' => ['<i>', '</i>'],
|
|
'p' => ['', ''],
|
|
# 'bi' => ['<i><b>', '</b></i>'],
|
|
'list' => ['<ul class="list-unordered">', '</ul>'],
|
|
'list-item' => ['<li class="list-unordered">', '</li>'],
|
|
'id' => ['<span class="id">', '</span>'],
|
|
'host' => ['<span class="host">', '</span>'],
|
|
'file' => ['<span class="file">', '</span>'],
|
|
'path' => ['<span class="path">', '</span>'],
|
|
'cmd' => ['<span class="cmd">', '</span>'],
|
|
'user' => ['<span class="user">', '</span>'],
|
|
'br-option' => ['<span class="br-option">', '</span>'],
|
|
'br-setting' => ['<span class="br-setting">', '</span>'],
|
|
'pg-option' => ['<span class="pg-option">', '</span>'],
|
|
'pg-setting' => ['<span class="pg-setting">', '</span>'],
|
|
'code' => ['<span class="id">', '</span>'],
|
|
'code-block' => ['<code-block>', '</code-block>'],
|
|
'exe' => [undef, ''],
|
|
'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>', ''],
|
|
'admonition' => ['<div class="admonition">', '</div>'],
|
|
}
|
|
};
|
|
|
|
####################################################################################################################################
|
|
# CONSTRUCTOR
|
|
####################################################################################################################################
|
|
sub new
|
|
{
|
|
my $class = shift; # Class name
|
|
|
|
# Create the class hash
|
|
my $self = {};
|
|
bless $self, $class;
|
|
|
|
# Assign function parameters, defaults, and log debug info
|
|
(
|
|
my $strOperation,
|
|
$self->{strType},
|
|
$self->{oManifest},
|
|
$self->{bExe},
|
|
$self->{strRenderOutKey},
|
|
) =
|
|
logDebugParam
|
|
(
|
|
__PACKAGE__ . '->new', \@_,
|
|
{name => 'strType'},
|
|
{name => 'oManifest', required => false},
|
|
{name => 'bExe', required => false},
|
|
{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]}";
|
|
|
|
$$oRenderTag{text}{backrest}[0] = "{[project]}";
|
|
$$oRenderTag{text}{exe}[0] = "{[project-exe]}";
|
|
|
|
$$oRenderTag{latex}{backrest}[0] = "{[project]}";
|
|
$$oRenderTag{latex}{exe}[0] = "\\textnormal\{\\texttt\{[project-exe]}}\}\}";
|
|
|
|
$$oRenderTag{html}{backrest}[0] = "<span class=\"backrest\">{[project]}</span>";
|
|
$$oRenderTag{html}{exe}[0] = "<span class=\"file\">{[project-exe]}</span>";
|
|
|
|
if (defined($self->{strRenderOutKey}))
|
|
{
|
|
# Copy page data to self
|
|
my $oRenderOut =
|
|
$self->{oManifest}->renderOutGet($self->{strType} eq 'latex' ? 'pdf' : $self->{strType}, $self->{strRenderOutKey});
|
|
|
|
# If these are the backrest docs then load the help
|
|
if ($self->{oManifest}->isBackRest())
|
|
{
|
|
$self->{oReference} =
|
|
new pgBackRestDoc::Common::DocConfig(${$self->{oManifest}->sourceGet('help')}{doc}, $self);
|
|
}
|
|
|
|
if (defined($$oRenderOut{source}) && $$oRenderOut{source} eq 'release' && $self->{oManifest}->isBackRest())
|
|
{
|
|
require pgBackRestDoc::Custom::DocCustomRelease;
|
|
pgBackRestDoc::Custom::DocCustomRelease->import();
|
|
|
|
$self->{oDoc} =
|
|
(new pgBackRestDoc::Custom::DocCustomRelease(
|
|
${$self->{oManifest}->sourceGet('release')}{doc},
|
|
defined($self->{oManifest}->variableGet('dev')) && $self->{oManifest}->variableGet('dev') eq 'y'))->docGet();
|
|
}
|
|
else
|
|
{
|
|
$self->{oDoc} = ${$self->{oManifest}->sourceGet($self->{strRenderOutKey})}{doc};
|
|
}
|
|
|
|
$self->{oSource} = $self->{oManifest}->sourceGet($$oRenderOut{source});
|
|
}
|
|
|
|
if (defined($self->{strRenderOutKey}))
|
|
{
|
|
# Build the doc
|
|
$self->build($self->{oDoc});
|
|
|
|
# Get required sections
|
|
foreach my $strPath (@{$self->{oManifest}->{stryRequire}})
|
|
{
|
|
if (substr($strPath, 0, 1) ne '/')
|
|
{
|
|
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);
|
|
}
|
|
}
|
|
}
|
|
|
|
if (defined($self->{oDoc}))
|
|
{
|
|
$self->{bToc} = !defined($self->{oDoc}->paramGet('toc', false)) || $self->{oDoc}->paramGet('toc') eq 'y' ? true : false;
|
|
$self->{bTocNumber} =
|
|
$self->{bToc} &&
|
|
(!defined($self->{oDoc}->paramGet('toc-number', false)) || $self->{oDoc}->paramGet('toc-number') eq 'y') ? true : false;
|
|
}
|
|
|
|
# Return from function and log return values if any
|
|
return logDebugReturn
|
|
(
|
|
$strOperation,
|
|
{name => 'self', value => $self}
|
|
);
|
|
}
|
|
|
|
####################################################################################################################################
|
|
# Set begin and end values for a tag
|
|
####################################################################################################################################
|
|
sub tagSet
|
|
{
|
|
my $self = shift;
|
|
my $strTag = shift;
|
|
my $strBegin = shift;
|
|
my $strEnd = shift;
|
|
|
|
$oRenderTag->{$self->{strType}}{$strTag}[0] = defined($strBegin) ? $strBegin : '';
|
|
$oRenderTag->{$self->{strType}}{$strTag}[1] = defined($strEnd) ? $strEnd : '';
|
|
}
|
|
|
|
####################################################################################################################################
|
|
# variableReplace
|
|
#
|
|
# Replace variables in the string.
|
|
####################################################################################################################################
|
|
sub variableReplace
|
|
{
|
|
my $self = shift;
|
|
|
|
return defined($self->{oManifest}) ? $self->{oManifest}->variableReplace(shift, $self->{strType}) : shift;
|
|
}
|
|
|
|
####################################################################################################################################
|
|
# variableSet
|
|
#
|
|
# Set a variable to be replaced later.
|
|
####################################################################################################################################
|
|
sub variableSet
|
|
{
|
|
my $self = shift;
|
|
|
|
return $self->{oManifest}->variableSet(shift, shift);
|
|
}
|
|
|
|
####################################################################################################################################
|
|
# variableGet
|
|
#
|
|
# Get the current value of a variable.
|
|
####################################################################################################################################
|
|
sub variableGet
|
|
{
|
|
my $self = shift;
|
|
|
|
return $self->{oManifest}->variableGet(shift);
|
|
}
|
|
|
|
####################################################################################################################################
|
|
# Get pre-execute list for a host
|
|
####################################################################################################################################
|
|
sub preExecute
|
|
{
|
|
my $self = shift;
|
|
my $strHost = shift;
|
|
|
|
if (defined($self->{preExecute}{$strHost}))
|
|
{
|
|
return @{$self->{preExecute}{$strHost}};
|
|
}
|
|
|
|
return;
|
|
}
|
|
|
|
####################################################################################################################################
|
|
# build
|
|
#
|
|
# Build the section map and perform filtering.
|
|
####################################################################################################################################
|
|
sub build
|
|
{
|
|
my $self = shift;
|
|
my $oNode = shift;
|
|
my $oParent = shift;
|
|
my $strPath = shift;
|
|
my $strPathPrefix = shift;
|
|
|
|
# &log(INFO, " node " . $oNode->nameGet());
|
|
|
|
my $strName = $oNode->nameGet();
|
|
|
|
if (defined($oParent))
|
|
{
|
|
# Evaluate if condition -- when false the node will be removed
|
|
if (!$self->{oManifest}->evaluateIf($oNode))
|
|
{
|
|
my $strDescription;
|
|
|
|
if (defined($oNode->nodeGet('title', false)))
|
|
{
|
|
$strDescription = $self->processText($oNode->nodeGet('title')->textGet());
|
|
}
|
|
|
|
&log(DEBUG, " filtered ${strName}" . (defined($strDescription) ? ": ${strDescription}" : ''));
|
|
|
|
$oParent->nodeRemove($oNode);
|
|
return;
|
|
}
|
|
}
|
|
else
|
|
{
|
|
&log(DEBUG, ' build document');
|
|
$self->{oSection} = {};
|
|
}
|
|
|
|
# Build section
|
|
if ($strName eq 'section')
|
|
{
|
|
my $strSectionId = $oNode->paramGet('id');
|
|
&log(DEBUG, "build section [${strSectionId}]");
|
|
|
|
# Set path and parent-path for this section
|
|
if (defined($strPath))
|
|
{
|
|
$oNode->paramSet('path-parent', $strPath);
|
|
}
|
|
|
|
$strPath .= '/' . $oNode->paramGet('id');
|
|
|
|
&log(DEBUG, " path ${strPath}");
|
|
${$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);
|
|
}
|
|
|
|
# Set log to true if this section has an execute list. This helps reduce the info logging by only showing sections that are
|
|
# likely to take a log time.
|
|
$oNode->paramSet('log', $self->{bExe} && $oNode->nodeList('execute-list', false) > 0 ? true : false);
|
|
|
|
# If section content is being pulled from elsewhere go get the content
|
|
if ($oNode->paramTest('source'))
|
|
{
|
|
my $oSource = ${$self->{oManifest}->sourceGet($oNode->paramGet('source'))}{doc};
|
|
|
|
# Section should not already have title defined, it should come from the source doc
|
|
if ($oNode->nodeTest('title'))
|
|
{
|
|
confess &log(ERROR, "cannot specify title in section that sources another document");
|
|
}
|
|
|
|
# Set title from source doc's title
|
|
$oNode->nodeAdd('title')->textSet($oSource->paramGet('title'));
|
|
|
|
foreach my $oSection ($oSource->nodeList('section'))
|
|
{
|
|
push(@{${$oNode->{oDoc}}{children}}, $oSection->{oDoc});
|
|
}
|
|
|
|
# Set path prefix to modify all section paths further down
|
|
$strPathPrefix = $strPath;
|
|
|
|
# Remove source so it is not included again later
|
|
$oNode->paramSet('source', undef);
|
|
}
|
|
}
|
|
# Build link
|
|
elsif ($strName eq 'link')
|
|
{
|
|
&log(DEBUG, 'build link [' . $oNode->valueGet() . ']');
|
|
|
|
# If the path prefix is set and this is a section
|
|
if (defined($strPathPrefix) && $oNode->paramTest('section'))
|
|
{
|
|
my $strNewPath = $strPathPrefix . $oNode->paramGet('section');
|
|
&log(DEBUG, "modify link section from '" . $oNode->paramGet('section') . "' to '${strNewPath}'");
|
|
|
|
$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);
|
|
}
|
|
# 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', false))
|
|
{
|
|
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++;
|
|
}
|
|
}
|
|
# Check for pre-execute statements
|
|
elsif ($strName eq 'execute')
|
|
{
|
|
if ($self->{oManifest}->{bPre} && $oNode->paramGet('pre', false, 'n') eq 'y')
|
|
{
|
|
# Add to pre-execute list
|
|
my $strHost = $self->variableReplace($oParent->paramGet('host'));
|
|
push(@{$self->{preExecute}{$strHost}}, $oNode);
|
|
|
|
# Skip this command so it doesn't get executed twice
|
|
$oNode->paramSet('skip', 'y')
|
|
}
|
|
}
|
|
|
|
# Iterate all text nodes
|
|
if (defined($oNode->textGet(false)))
|
|
{
|
|
foreach my $oChild ($oNode->textGet()->nodeList(undef, false))
|
|
{
|
|
if (ref(\$oChild) ne "SCALAR")
|
|
{
|
|
$self->build($oChild, $oNode, $strPath, $strPathPrefix);
|
|
}
|
|
}
|
|
}
|
|
|
|
# Iterate all non-text nodes
|
|
foreach my $oChild ($oNode->nodeList(undef, false))
|
|
{
|
|
if (ref(\$oChild) ne "SCALAR")
|
|
{
|
|
$self->build($oChild, $oNode, $strPath, $strPathPrefix);
|
|
|
|
# If the child should be logged then log the parent as well so the hierarchy is complete
|
|
if ($oChild->nameGet() eq 'section' && $oChild->paramGet('log', false, false))
|
|
{
|
|
$oNode->paramSet('log', true);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
####################################################################################################################################
|
|
# required
|
|
#
|
|
# Build a list of required sections
|
|
####################################################################################################################################
|
|
sub required
|
|
{
|
|
my $self = shift;
|
|
my $strPath = shift;
|
|
my $bDepend = shift;
|
|
|
|
# If node is not found that means the path is invalid
|
|
my $oNode = ${$self->{oSection}}{$strPath};
|
|
|
|
if (!defined($oNode))
|
|
{
|
|
confess &log(ERROR, "invalid path ${strPath}");
|
|
}
|
|
|
|
# Only add sections that are listed dependencies
|
|
if (!defined($bDepend) || $bDepend)
|
|
{
|
|
# Match section and all child sections
|
|
foreach my $strChildPath (sort(keys(%{$self->{oSection}})))
|
|
{
|
|
if ($strChildPath =~ /^$strPath$/ || $strChildPath =~ /^$strPath\/.*$/)
|
|
{
|
|
if (!defined(${$self->{oSectionRequired}}{$strChildPath}))
|
|
{
|
|
my @stryChildPath = split('/', $strChildPath);
|
|
|
|
&log(INFO, (' ' x (scalar(@stryChildPath) - 2)) . " require section: ${strChildPath}");
|
|
|
|
${$self->{oSectionRequired}}{$strChildPath} = true;
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
# Get the path of the current section's parent
|
|
my $strParentPath = $oNode->paramGet('path-parent', false);
|
|
|
|
if ($oNode->paramTest('depend'))
|
|
{
|
|
foreach my $strDepend (split(',', $oNode->paramGet('depend')))
|
|
{
|
|
if ($strDepend !~ /^\//)
|
|
{
|
|
if (!defined($strParentPath))
|
|
{
|
|
$strDepend = "/${strDepend}";
|
|
}
|
|
else
|
|
{
|
|
$strDepend = "${strParentPath}/${strDepend}";
|
|
}
|
|
}
|
|
|
|
$self->required($strDepend, true);
|
|
}
|
|
}
|
|
elsif (defined($strParentPath))
|
|
{
|
|
$self->required($strParentPath, false);
|
|
}
|
|
}
|
|
|
|
####################################################################################################################################
|
|
# isRequired
|
|
#
|
|
# Is it required to execute the section statements?
|
|
####################################################################################################################################
|
|
sub isRequired
|
|
{
|
|
my $self = shift;
|
|
my $oSection = shift;
|
|
|
|
if (!defined($self->{oSectionRequired}))
|
|
{
|
|
return true;
|
|
}
|
|
|
|
my $strPath = $oSection->paramGet('path');
|
|
|
|
defined(${$self->{oSectionRequired}}{$strPath}) ? true : false;
|
|
}
|
|
|
|
####################################################################################################################################
|
|
# processTag
|
|
####################################################################################################################################
|
|
sub processTag
|
|
{
|
|
my $self = shift;
|
|
|
|
# Assign function parameters, defaults, and log debug info
|
|
my
|
|
(
|
|
$strOperation,
|
|
$oTag
|
|
) =
|
|
logDebugParam
|
|
(
|
|
__PACKAGE__ . '->processTag', \@_,
|
|
{name => 'oTag', trace => true}
|
|
);
|
|
|
|
my $strBuffer = "";
|
|
|
|
my $strType = $self->{strType};
|
|
my $strTag = $oTag->nameGet();
|
|
|
|
if (!defined($strTag))
|
|
{
|
|
require Data::Dumper;
|
|
confess Dumper($oTag);
|
|
}
|
|
|
|
if ($strTag eq 'link')
|
|
{
|
|
my $strUrl = $oTag->paramGet('url', false);
|
|
|
|
if (!defined($strUrl))
|
|
{
|
|
my $strPage = $self->variableReplace($oTag->paramGet('page', false));
|
|
my $strSection = $oTag->paramGet('section', false);
|
|
|
|
# If a page/section link points to the current page then remove the page portion
|
|
if (defined($strPage) && defined($strSection) && defined($self->{strRenderOutKey}) &&
|
|
$strPage eq $self->{strRenderOutKey})
|
|
{
|
|
undef($strPage);
|
|
}
|
|
|
|
# If this is a page URL
|
|
if (defined($strPage))
|
|
{
|
|
# If the page wasn't rendered then point at the website
|
|
if (!defined($self->{oManifest}->renderOutGet($strType, $strPage, true)))
|
|
{
|
|
$strUrl = '{[backrest-url-base]}/' . $oTag->paramGet('page') . '.html';
|
|
}
|
|
# Else point locally
|
|
else
|
|
{
|
|
if ($strType eq 'html')
|
|
{
|
|
$strUrl = "${strPage}.html". (defined($strSection) ? '#' . substr($strSection, 1) : '');
|
|
}
|
|
elsif ($strType eq 'markdown')
|
|
{
|
|
if (defined($strSection))
|
|
{
|
|
confess &log(
|
|
ERROR,
|
|
"page and section links not supported for type ${strType}, value '" . $oTag->valueGet() . "'");
|
|
}
|
|
|
|
$strUrl = "${strPage}.md";
|
|
}
|
|
else
|
|
{
|
|
confess &log(ERROR, "page links not supported for type ${strType}, value '" . $oTag->valueGet() . "'");
|
|
}
|
|
}
|
|
}
|
|
else
|
|
{
|
|
my $strSection = $oTag->paramGet('section');
|
|
my $oSection = ${$self->{oSection}}{$strSection};
|
|
|
|
if (!defined($oSection))
|
|
{
|
|
confess &log(ERROR, "section link '${strSection}' does not exist");
|
|
}
|
|
|
|
if (!defined($strSection))
|
|
{
|
|
confess &log(ERROR, "link with value '" . $oTag->valueGet() . "' must defined url, page, or section");
|
|
}
|
|
|
|
if ($strType eq 'html')
|
|
{
|
|
$strUrl = '#' . substr($strSection, 1);
|
|
}
|
|
elsif ($strType eq 'latex')
|
|
{
|
|
$strUrl = $strSection;
|
|
}
|
|
else
|
|
{
|
|
$strUrl = lc($self->processText($oSection->nodeGet('title')->textGet()));
|
|
$strUrl =~ s/[^\w\- ]//g;
|
|
$strUrl =~ s/ /-/g;
|
|
$strUrl = '#' . $strUrl;
|
|
}
|
|
}
|
|
}
|
|
|
|
if ($strType eq 'html')
|
|
{
|
|
$strBuffer = '<a href="' . $strUrl . '">' . $oTag->valueGet() . '</a>';
|
|
}
|
|
elsif ($strType eq 'markdown')
|
|
{
|
|
$strBuffer = '[' . $oTag->valueGet() . '](' . $strUrl . ')';
|
|
}
|
|
elsif ($strType eq 'latex')
|
|
{
|
|
if ($oTag->paramTest('url'))
|
|
{
|
|
$strBuffer = "\\href{$strUrl}{" . $oTag->valueGet() . "}";
|
|
}
|
|
else
|
|
{
|
|
$strBuffer = "\\hyperref[$strUrl]{" . $oTag->valueGet() . "}";
|
|
}
|
|
}
|
|
elsif ($strType eq 'text')
|
|
{
|
|
$strBuffer = $oTag->valueGet();
|
|
}
|
|
else
|
|
{
|
|
confess "'link' tag not valid for type ${strType}";
|
|
}
|
|
}
|
|
else
|
|
{
|
|
my $strStart = $$oRenderTag{$strType}{$strTag}[0];
|
|
my $strStop = $$oRenderTag{$strType}{$strTag}[1];
|
|
|
|
if (!defined($strStart) || !defined($strStop))
|
|
{
|
|
confess &log(ERROR, "invalid type ${strType} or tag ${strTag}");
|
|
}
|
|
|
|
$strBuffer .= $strStart;
|
|
|
|
# Admonitions in the help 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 'list-item' || $strTag eq 'code-block' || $strTag eq 'summary'
|
|
|| $strTag eq 'admonition')
|
|
{
|
|
$strBuffer .= $self->processText($oTag);
|
|
}
|
|
elsif (defined($oTag->valueGet()))
|
|
{
|
|
$strBuffer .= $oTag->valueGet();
|
|
}
|
|
else
|
|
{
|
|
foreach my $oSubTag ($oTag->nodeList(undef, false))
|
|
{
|
|
$strBuffer .= $self->processTag($oSubTag);
|
|
}
|
|
}
|
|
|
|
if ($strTag eq 'admonition')
|
|
{
|
|
$strBuffer .= $self->processAdmonitionEnd($oTag);
|
|
}
|
|
|
|
$strBuffer .= $strStop;
|
|
}
|
|
|
|
# Return from function and log return values if any
|
|
return logDebugReturn
|
|
(
|
|
$strOperation,
|
|
{name => 'strBuffer', value => $strBuffer, trace => true}
|
|
);
|
|
}
|
|
|
|
####################################################################################################################################
|
|
# 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
|
|
####################################################################################################################################
|
|
sub processText
|
|
{
|
|
my $self = shift;
|
|
|
|
# Assign function parameters, defaults, and log debug info
|
|
my
|
|
(
|
|
$strOperation,
|
|
$oText
|
|
) =
|
|
logDebugParam
|
|
(
|
|
__PACKAGE__ . '->processText', \@_,
|
|
{name => 'oText', trace => true}
|
|
);
|
|
|
|
my $strType = $self->{strType};
|
|
my $strBuffer = '';
|
|
my $strLastTag = 'body';
|
|
|
|
foreach my $oNode ($oText->nodeList(undef, false))
|
|
{
|
|
if (ref(\$oNode) eq "SCALAR")
|
|
{
|
|
if ($oNode =~ /\"/)
|
|
{
|
|
confess &log(ERROR, "unable to process quotes in string (use <quote> instead):\n${oNode}");
|
|
}
|
|
|
|
# Skip text nodes with linefeeds since they happen between tags
|
|
if (index($oNode, "\n") == -1)
|
|
{
|
|
$strBuffer .= $oNode;
|
|
}
|
|
}
|
|
else
|
|
{
|
|
# Add br tags to separate paragraphs and linefeeds to make the output more diffable. This is needed because of the hacky
|
|
# way config text is being rendered in the final document, i.e. by passing rendered HTML into divs rather than XML to be
|
|
# rendered at that time.
|
|
if ($strLastTag eq 'p' && $strType eq 'html')
|
|
{
|
|
$strBuffer .= "<br/>\n";
|
|
|
|
if ($oNode->nameGet() eq 'p')
|
|
{
|
|
$strBuffer .= "<br/>\n";
|
|
}
|
|
}
|
|
|
|
$strBuffer .= $self->processTag($oNode);
|
|
|
|
$strLastTag = $oNode->nameGet();
|
|
}
|
|
}
|
|
#
|
|
# if ($strType eq 'html')
|
|
# {
|
|
# # $strBuffer =~ s/^\s+|\s+$//g;
|
|
#
|
|
# $strBuffer =~ s/\n/\<br\/\>\n/g;
|
|
# }
|
|
|
|
# if ($strType eq 'markdown')
|
|
# {
|
|
# $strBuffer =~ s/^\s+|\s+$//g;
|
|
|
|
$strBuffer =~ s/ +/ /g;
|
|
$strBuffer =~ s/^ //smg;
|
|
# }
|
|
|
|
if ($strType eq 'latex')
|
|
{
|
|
$strBuffer =~ s/\&mdash\;/---/g;
|
|
$strBuffer =~ s/\<\;/\</g;
|
|
$strBuffer =~ s/\<\=/\$\\leq\$/g;
|
|
$strBuffer =~ s/\>\=/\$\\geq\$/g;
|
|
# $strBuffer =~ s/\_/\\_/g;
|
|
|
|
# If not a code-block, which is to be taken AS IS, then escape special characters in latex
|
|
if ($oText->nameGet() ne 'code-block')
|
|
{
|
|
# If the previous character is not already a slash (e.g. not already escaped) then insert a slash
|
|
$strBuffer =~ s/(?<!\\)\#/\\#/g;
|
|
$strBuffer =~ s/(?<!\\)\%/\\%/g;
|
|
$strBuffer =~ s/(?<!\\)\_/\\_/g;
|
|
# $strBuffer =~ s/(?<!\\)\$/\\\$/g;
|
|
|
|
# Escape square brackest in list items since they are used for reformatting the bullet item with what is in brackets,
|
|
# which is not the intention.
|
|
if ($oText->nameGet() eq 'list-item')
|
|
{
|
|
$strBuffer =~ s/\[/\{\[/g;
|
|
$strBuffer =~ s/\]/\]\}/g;
|
|
}
|
|
|
|
$strBuffer =~ s/\©\;/{\\textcopyright}/g;
|
|
$strBuffer =~ s/\&trade\;/{\\texttrademark}/g;
|
|
$strBuffer =~ s/\®\;/{\\textregistered}/g;
|
|
|
|
$strBuffer =~ s/\&rarr\;/{\\textrightarrow}/g;
|
|
|
|
# Escape all ampersands after making any other conversions above
|
|
$strBuffer =~ s/(?<!\\)\&/\\&/g;
|
|
}
|
|
}
|
|
|
|
if ($strType eq 'html')
|
|
{
|
|
$strBuffer =~ s/ma[s]ter/master/g;
|
|
}
|
|
|
|
if ($strType eq 'text')
|
|
{
|
|
$strBuffer =~ s/\&mdash\;/--/g;
|
|
$strBuffer =~ s/\<\;/\</g;
|
|
$strBuffer =~ s/\&ge\;/\>\=/g;
|
|
}
|
|
|
|
$strBuffer = $self->variableReplace($strBuffer);
|
|
|
|
# Return from function and log return values if any
|
|
return logDebugReturn
|
|
(
|
|
$strOperation,
|
|
{name => 'strBuffer', value => $strBuffer, trace => true}
|
|
);
|
|
}
|
|
|
|
1;
|