db/pgbackrest
1
0
Fork 0
mirror of https://github.com/pgbackrest/pgbackrest.git synced 2025-03-03 14:52:21 +02:00
Code Issues Releases Activity

Added a man page to document generation.

Browse Source
This commit is contained in:
David Steele 2016-06-02 09:25:12 -04:00
parent 9a9f26a96f
commit df6086bd24
6 changed files with 246 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
doc/doc.pl
View File

@ -160,12 +160,13 @@ if (@stryOutput == 0)
if ($oManifest->isBackRest())
{
push(@stryOutput, 'help');
push(@stryOutput, 'man');
}
}
for my $strOutput (@stryOutput)
{
if (!(($strOutput eq 'help' || $strOutput eq 'markdown') && $oManifest->isBackRest()))
if (!(($strOutput eq 'help' || $strOutput eq 'man') && $oManifest->isBackRest()))
{
$oManifest->renderGet($strOutput);
}
@ -185,14 +186,23 @@ for my $strOutput (@stryOutput)
$oMarkdown->process();
}
elsif ($strOutput eq 'help' && $oManifest->isBackRest())
elsif (($strOutput eq 'help' || $strOutput eq 'man') && $oManifest->isBackRest())
{
# Generate the command-line help
my $oRender = new BackRestDoc::Common::DocRender('text', $oManifest);
my $oDocConfig =
new BackRestDoc::Common::DocConfig(
new BackRestDoc::Common::Doc("${strBasePath}/xml/reference.xml"), $oRender);
$oDocConfig->helpDataWrite($oManifest);
if ($strOutput eq 'help')
{
$oDocConfig->helpDataWrite($oManifest);
}
else
{
filePathCreate("${strBasePath}/output/man", '0770', true, true);
fileStringWrite("${strBasePath}/output/man/" . lc(BACKREST_NAME) . '.1.txt', $oDocConfig->manGet($oManifest), false);
}
}
elsif ($strOutput eq 'html')
{

212
doc/lib/BackRestDoc/Common/DocConfig.pm
View File

@ -17,6 +17,7 @@ use pgBackRest::Common::String;
use pgBackRest::Config::Config;
use pgBackRest::Config::ConfigHelp;
use pgBackRest::FileCommon;
use pgBackRest::Version;
####################################################################################################################################
# Help types
@ -479,6 +480,217 @@ sub helpDataWriteFormatText
return $strText;
}
####################################################################################################################################
# manGet
#
# Generate the man page.
####################################################################################################################################
sub manGet
{
my $self = shift;
# Assign function parameters, defaults, and log debug info
my
(
$strOperation,
$oManifest
) =
logDebugParam
(
__PACKAGE__ . '->manGet', \@_,
{name => 'oManifest'}
);
# Get index.xml to pull various text from
my $oIndexDoc = ${$oManifest->sourceGet('index')}{doc};
# Write the header
my $strManPage =
"NAME\n" .
' ' . BACKREST_NAME . ' - ' . $oManifest->variableReplace($oIndexDoc->paramGet('subtitle')) . "\n\n" .
"SYNOPSIS\n" .
' ' . BACKREST_EXE . ' [options] [command]';
# Output the description (first two paragraphs of index.xml introduction)
my $iParaTotal = 0;
$strManPage .= "\n\n" .
"DESCRIPTION";
foreach my $oPara ($oIndexDoc->nodeGetById('section', 'introduction')->nodeList('p'))
{
if ($iParaTotal >= 2)
{
last;
}
$strManPage .= ($iParaTotal == 0 ? "\n" : "\n\n") . ' ' .
manGetFormatText($oManifest->variableReplace($self->{oDocRender}->processText($oPara->textGet())), 80, 2);
$iParaTotal++;
}
# Build command and config hashes
my $hOptionRule = optionRuleGet();
my $hConfig = $self->{oConfigHash};
my $hCommandList = {};
my $iCommandMaxLen = 0;
my $hOptionList = {};
my $iOptionMaxLen = 0;
foreach my $strCommand (sort(keys(%{$$hConfig{&CONFIG_HELP_COMMAND}})))
{
my $hCommand = $$hConfig{&CONFIG_HELP_COMMAND}{$strCommand};
$iCommandMaxLen = length($strCommand) > $iCommandMaxLen ? length($strCommand) : $iCommandMaxLen;
$$hCommandList{$strCommand}{summary} = $$hCommand{&CONFIG_HELP_SUMMARY};
if (defined($$hCommand{&CONFIG_HELP_OPTION}))
{
foreach my $strOption (sort(keys(%{$$hCommand{&CONFIG_HELP_OPTION}})))
{
my $hOption = $$hCommand{&CONFIG_HELP_OPTION}{$strOption};
if ($$hOption{&CONFIG_HELP_SOURCE} eq CONFIG_HELP_SOURCE_COMMAND)
{
$iOptionMaxLen = length($strOption) > $iOptionMaxLen ? length($strOption) : $iOptionMaxLen;
$$hOptionList{$strCommand}{$strOption}{&CONFIG_HELP_SUMMARY} = $$hOption{&CONFIG_HELP_SUMMARY};
}
}
}
}
foreach my $strOption (sort(keys(%{$$hConfig{&CONFIG_HELP_OPTION}})))
{
my $hOption = $$hConfig{&CONFIG_HELP_OPTION}{$strOption};
$iOptionMaxLen = length($strOption) > $iOptionMaxLen ? length($strOption) : $iOptionMaxLen;
my $strSection = defined($$hOption{&CONFIG_HELP_SECTION}) ? $$hOption{&CONFIG_HELP_SECTION} : CONFIG_SECTION_GENERAL;
$$hOptionList{$strSection}{$strOption}{&CONFIG_HELP_SUMMARY} = $$hOption{&CONFIG_HELP_SUMMARY};
}
# Output Commands
$strManPage .= "\n\n" .
'COMMANDS';
foreach my $strCommand (sort(keys(%{$hCommandList})))
{
# Construct the summary
my $strSummary = $oManifest->variableReplace($self->{oDocRender}->processText($$hCommandList{$strCommand}{summary}));
# $strSummary = lcfirst(substr($strSummary, 0, length($strSummary) - 1));
# Output the summary
$strManPage .=
"\n " . "${strCommand}" . (' ' x ($iCommandMaxLen - length($strCommand))) . ' ' .
manGetFormatText($strSummary, 80, $iCommandMaxLen + 4);
}
# Output options
my $bFirst = true;
$strManPage .= "\n\n" .
'OPTIONS';
foreach my $strSection (sort(keys(%{$hOptionList})))
{
$strManPage .= ($bFirst ?'' : "\n") . "\n " . ucfirst($strSection) . ' Options:';
foreach my $strOption (sort(keys(%{$$hOptionList{$strSection}})))
{
my $hOption = $$hOptionList{$strSection}{$strOption};
# Contruct the default
my $strCommand = defined(${commandHashGet()}{$strSection}) ? $strSection : undef;
my $strDefault = optionDefault($strOption, $strCommand);
if (defined($strDefault))
{
if ($$hOptionRule{$strOption}{&OPTION_RULE_TYPE} eq &OPTION_TYPE_BOOLEAN)
{
$strDefault = $strDefault ? 'y' : 'n';
}
}
#
# use Data::Dumper; confess Dumper($$hOption{&CONFIG_HELP_SUMMARY});
# Construct the summary
my $strSummary = $oManifest->variableReplace($self->{oDocRender}->processText($$hOption{&CONFIG_HELP_SUMMARY}));
$strSummary = $strSummary . (defined($strDefault) ? " [default=${strDefault}]" : '');
# Output the summary
$strManPage .=
"\n " . "--${strOption}" . (' ' x ($iOptionMaxLen - length($strOption))) . ' ' .
manGetFormatText($strSummary, 80, $iOptionMaxLen + 8);
}
$bFirst = false;
}
# Write files, examples, and references
$strManPage .= "\n\n" .
"FILES\n" .
"\n" .
' ' . OPTION_DEFAULT_CONFIG . "\n" .
' ' . OPTION_DEFAULT_REPO_PATH . "\n" .
' ' . OPTION_DEFAULT_LOG_PATH . "\n" .
' ' . OPTION_DEFAULT_SPOOL_PATH . "\n" .
' ' . OPTION_DEFAULT_LOCK_PATH . "\n" .
"\n" .
"EXAMPLES\n" .
"\n" .
" * Create a backup of the PostgreSQL `main` cluster:\n" .
"\n" .
' $ ' . BACKREST_EXE . ' --' . OPTION_STANZA . "=main backup\n" .
"\n" .
' The `main` cluster should be configured in `' . OPTION_DEFAULT_CONFIG . "`\n" .
"\n" .
" * Show all available backups:\n" .
"\n" .
' $ ' . BACKREST_EXE . ' ' . CMD_INFO . "\n" .
"\n" .
" * Show all available backups for a specific cluster:\n" .
"\n" .
' $ ' . BACKREST_EXE . ' --' . OPTION_STANZA . '=main ' . CMD_INFO . "\n" .
"\n" .
" * Show backup specific options:\n" .
"\n" .
' $ ' . BACKREST_EXE . ' ' . CMD_HELP . ' ' . CMD_BACKUP . "\n" .
"\n" .
"SEE ALSO\n" .
"\n" .
' /usr/share/doc/' . BACKREST_EXE . "-doc/html/index.html\n" .
' ' . $oManifest->variableReplace('{[backrest-url-base]}') . "\n";
return $strManPage;
}
# Helper function for manGet() used to format text by indenting and splitting
sub manGetFormatText
{
my $strLine = shift;
my $iLength = shift;
my $iIndentRest = shift;
my $strPart;
my $strResult;
my $bFirst = true;
do
{
my $iIndent = $bFirst ? 0 : $iIndentRest;
($strPart, $strLine) = stringSplit($strLine, ' ', $iLength - $iIndentRest);
$strResult .= ($bFirst ? '' : "\n") . (' ' x $iIndent) . trim($strPart);
$bFirst = false;
}
while (defined($strLine));
return $strResult;
}
####################################################################################################################################
# helpConfigDocGet
#

1
doc/xml/index.xml
View File

@ -28,6 +28,7 @@
<section id="introduction">
<title>Introduction</title>
<!-- These first two paragraphs are pulled in other parts of the documentation as a concise introduction and summary of features. -->
<p><backrest/> aims to be a simple, reliable backup and restore system that can seamlessly scale up to the largest databases and workloads.</p>
<p>Instead of relying on traditional backup tools like tar and rsync, <backrest/> implements all backup features internally and uses a custom protocol for communicating with remote systems. Removing reliance on tar and rsync allows for better solutions to database-specific backup challenges. The custom remote protocol allows for more flexibility and limits the types of connections that are required to perform a backup which increases security.</p>

10
doc/xml/reference.xml
View File

@ -474,9 +474,9 @@
<config-key id="db-path" name="Database Path">
<summary>Cluster data directory.</summary>
<text>This should be the same as the <setting>data_directory</setting> setting in <file>postgresql.conf</file>. Even though this value can be read from <file>postgresql.conf</file> or the database cluster it is prudent to set it in case those resources are not available during a restore or cold backup scenario.
<text>This should be the same as the <setting>data_directory</setting> setting in <file>postgresql.conf</file>. Even though this value can be read from <file>postgresql.conf</file> or the database cluster it is prudent to set it in case those resources are not available during a restore or offline backup scenario.
The <setting>db-path</setting> option is tested against the value reported by <postgres/> on every hot backup so it should always be current.</text>
The <setting>db-path</setting> option is tested against the value reported by <postgres/> on every online backup so it should always be current.</text>
<example>/data/db</example>
</config-key>
@ -557,18 +557,18 @@
<!-- OPERATION - BACKUP COMMAND - ONLINE OPTION -->
<option id="online" name="Online">
<summary>Perform hot backup.</summary>
<summary>Perform an online backup.</summary>
<text>Specifying --no-online prevents <backrest/> from running <code>pg_start_backup()</code> and <code>pg_stop_backup()</code> on the database cluster. In order for this to work <postgres/> should be shut down and <backrest/> will generate an error if it is not.
The purpose of this option is to allow cold backups. The <path>pg_xlog</path> directory is copied as-is and <setting>archive-check</setting> is automatically disabled for the backup.</text>
The purpose of this option is to allow offline backups. The <path>pg_xlog</path> directory is copied as-is and <setting>archive-check</setting> is automatically disabled for the backup.</text>
<example>n</example>
</option>
<!-- OPERATION - BACKUP COMMAND - FORCE OPTION -->
<option id="force" name="Force">
<summary>Force a cold backup.</summary>
<summary>Force an offline backup.</summary>
<text>When used with <br-option>--no-start-stop</br-option> a backup will be run even if <backrest/> thinks that <postgres/> is running. <b>This option should be used with extreme care as it will likely result in a bad backup.</b>

9
doc/xml/release.xml
View File

@ -129,6 +129,15 @@
<release-item>
<p>Release notes are now broken into sections so that bugs, features, and refactors are clearly delineated. An <quote>Additional Notes</quote> section has been added for changes to documentation and the test suite that do not affect the core code.</p>
</release-item>
<release-item>
<release-item-contributor-list>
<release-item-contributor id="vondendriesch.adrian"/>
<release-item-contributor id="steele.david"/>
</release-item-contributor-list>
<p>Added man page generation.</p>
</release-item>
</release-feature-list>
<release-refactor-list>

12
lib/pgBackRest/Config/ConfigHelpData.pm
View File

@ -238,10 +238,10 @@ my $oConfigHelpData =
description =>
"This should be the same as the data_directory setting in postgresql.conf. Even though this value can be read " .
"from postgresql.conf or the database cluster it is prudent to set it in case those resources are not " .
"available during a restore or cold backup scenario.\n" .
"available during a restore or offline backup scenario.\n" .
"\n" .
"The db-path option is tested against the value reported by PostgreSQL on every hot backup so it should always " .
"be current."
"The db-path option is tested against the value reported by PostgreSQL on every online backup so it should " .
"always be current."
},
# DB-PORT Option Help
@ -753,7 +753,7 @@ my $oConfigHelpData =
'force' =>
{
summary =>
"Force a cold backup.",
"Force an offline backup.",
description =>
"When used with --no-start-stop a backup will be run even if pgBackRest thinks that PostgreSQL is " .
"running. This option should be used with extreme care as it will likely result in a bad backup.\n" .
@ -778,13 +778,13 @@ my $oConfigHelpData =
'online' =>
{
summary =>
"Perform hot backup.",
"Perform an online backup.",
description =>
"Specifying --no-online prevents pgBackRest from running pg_start_backup() and pg_stop_backup() on the " .
"database cluster. In order for this to work PostgreSQL should be shut down and pgBackRest will " .
"generate an error if it is not.\n" .
"\n" .
"The purpose of this option is to allow cold backups. The pg_xlog directory is copied as-is and " .
"The purpose of this option is to allow offline backups. The pg_xlog directory is copied as-is and " .
"archive-check is automatically disabled for the backup."
},