From 597739fafecf349af470134200aafc65a53eabf2 Mon Sep 17 00:00:00 2001 From: David Steele Date: Fri, 25 Sep 2020 11:26:27 -0400 Subject: [PATCH] Move info command text to the reference and link to user guide. This means the same text will appear in both places, which should make it easier to find. Also update the link code to allow both page and section to be specified rather than only one or the other. --- doc/lib/pgBackRestDoc/Common/DocRender.pm | 24 +++++++++++++++++++---- doc/xml/reference.xml | 16 ++++++++++++++- doc/xml/release.xml | 9 +++++++++ doc/xml/user-guide.xml | 14 +------------ 4 files changed, 45 insertions(+), 18 deletions(-) diff --git a/doc/lib/pgBackRestDoc/Common/DocRender.pm b/doc/lib/pgBackRestDoc/Common/DocRender.pm index a1d49b447..6ded7486b 100644 --- a/doc/lib/pgBackRestDoc/Common/DocRender.pm +++ b/doc/lib/pgBackRestDoc/Common/DocRender.pm @@ -729,6 +729,13 @@ sub processTag 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) && $strPage eq $self->{strRenderOutKey}) + { + undef($strPage); + } # If this is a page URL if (defined($strPage)) @@ -741,11 +748,20 @@ sub processTag # Else point locally else { - if ($strType eq 'html' || $strType eq 'markdown') + if ($strType eq 'html') { - $strUrl = - $oTag->paramGet('page', false) . '.' . - ($strType eq 'html' ? $strType : '.md'); + $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 { diff --git a/doc/xml/reference.xml b/doc/xml/reference.xml index c712f63e0..0f8925058 100644 --- a/doc/xml/reference.xml +++ b/doc/xml/reference.xml @@ -1557,7 +1557,21 @@ The info command operates on a single stanza or all stanzas. Text output is the default and gives a human-readable summary of backups for the stanza(s) requested. This format is subject to change with any release. - For machine-readable output use --output=json. The JSON output contains far more information than the text output and is kept stable unless a bug is found. + For machine-readable output use --output=json. The JSON output contains far more information than the text output and is kept stable unless a bug is found. + + Each stanza has a separate section and it is possible to limit output to a single stanza with the --stanza option. The stanza 'status' gives a brief indication of the stanza's health. If this is 'ok' then is functioning normally. The 'wal archive min/max' shows the minimum and maximum WAL currently stored in the archive. Note that there may be gaps due to archive retention policies or other reasons. + + The 'backup/expire running' message will appear beside the 'status' information if one of those commands is currently running on the host. + + The backups are displayed oldest to newest. The oldest backup will always be a full backup (indicated by an F at the end of the label) but the newest backup can be full, differential (ends with D), or incremental (ends with I). + + The 'timestamp start/stop' defines the time period when the backup ran. The 'timestamp stop' can be used to determine the backup to use when performing Point-In-Time Recovery. More information about Point-In-Time Recovery can be found in the Point-In-Time Recovery section. + + The 'wal start/stop' defines the WAL range that is required to make the database consistent when restoring. The backup command will ensure that this WAL range is in the archive before completing. + + The 'database size' is the full uncompressed size of the database while 'backup size' is the amount of data actually backed up (these will be the same for full backups). The 'repository size' includes all the files from this backup and any referenced backups that are required to restore the database while 'repository backup size' includes only the files in this backup (these will also be the same for full backups). Repository sizes reflect compressed file sizes if compression is enabled in or the filesystem. + + The 'backup reference list' contains the additional backups that are required to restore this backup. diff --git a/doc/xml/release.xml b/doc/xml/release.xml index 1612c38ee..7eed9f6d2 100644 --- a/doc/xml/release.xml +++ b/doc/xml/release.xml @@ -116,6 +116,15 @@

Add note that versions must match when running remotely.

+ + + + + + +

Move info command text to the reference and link to user guide.

+ + diff --git a/doc/xml/user-guide.xml b/doc/xml/user-guide.xml index 512b6a016..5a46b3031 100644 --- a/doc/xml/user-guide.xml +++ b/doc/xml/user-guide.xml @@ -1249,19 +1249,7 @@ -

Each stanza has a separate section and it is possible to limit output to a single stanza with the --stanza option. The stanza 'status' gives a brief indication of the stanza's health. If this is 'ok' then is functioning normally. The 'wal archive min/max' shows the minimum and maximum WAL currently stored in the archive. Note that there may be gaps due to archive retention policies or other reasons.

- -

The 'backup/expire running' message will appear beside the 'status' information if one of those commands is currently running on the host.

- -

The backups are displayed oldest to newest. The oldest backup will always be a full backup (indicated by an F at the end of the label) but the newest backup can be full, differential (ends with D), or incremental (ends with I).

- -

The 'timestamp start/stop' defines the time period when the backup ran. The 'timestamp stop' can be used to determine the backup to use when performing Point-In-Time Recovery. More information about Point-In-Time Recovery can be found in the Point-In-Time Recovery section.

- -

The 'wal start/stop' defines the WAL range that is required to make the database consistent when restoring. The backup command will ensure that this WAL range is in the archive before completing.

- -

The 'database size' is the full uncompressed size of the database while 'backup size' is the amount of data actually backed up (these will be the same for full backups). The 'repository size' includes all the files from this backup and any referenced backups that are required to restore the database while 'repository backup size' includes only the files in this backup (these will also be the same for full backups). Repository sizes reflect compressed file sizes if compression is enabled in or the filesystem.

- -

The 'backup reference list' contains the additional backups that are required to restore this backup.

+