db/pgbackrest
1
0
Fork 0
mirror of https://github.com/pgbackrest/pgbackrest.git synced 2024-12-12 10:04:14 +02:00
Code Issues Releases Activity

Simplify description rendering in command and configuration reference.

Browse Source 
The reference documentation was still using a very old version of rendering from before the user guide was introduced. This was preserved in the initial C migration to reduce the diff between Perl and C for testing purposes. The old version used hard linefeeds to simulate paragraphs and reduce the amount of markup that needed to be used. In retrospect this was not a great idea.

Instead use more natural rendering that does not depend on using hard linefeeds between paragraphs.
This commit is contained in:
David Steele 2023-10-10 16:49:05 -04:00
parent 45abea471e
commit 81536cd486
3 changed files with 20 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
doc/src/command/build/reference.c
View File

@ -41,7 +41,7 @@ referenceOptionRender(
if (optCfg->beta)
xmlNodeContentSet(xmlNodeAdd(xmlOption, STRDEF("p")), STRDEF("FOR BETA TESTING ONLY. DO NOT USE IN PRODUCTION."));
xmlNodeChildAdd(xmlNodeAdd(xmlOption, STRDEF("p")), optHlp->description);
xmlNodeChildAdd(xmlOption, optHlp->description);
// Add default value
StringList *const blockList = strLstNew();
@ -159,7 +159,7 @@ referenceConfigurationRender(const BldCfg *const bldCfg, const BldHlp *const bld
xmlNodeAttributeSet(xmlIntro, STRDEF("id"), STRDEF("introduction"));
xmlNodeContentSet(xmlNodeAdd(xmlIntro, STRDEF("title")), STRDEF("Introduction"));
xmlNodeChildAdd(xmlNodeAdd(xmlIntro, STRDEF("text")), bldHlp->optIntroduction);
xmlNodeChildAdd(xmlIntro, bldHlp->optIntroduction);
for (unsigned int sctIdx = 0; sctIdx < lstSize(bldHlp->sctList); sctIdx++)
{
@ -169,7 +169,7 @@ referenceConfigurationRender(const BldCfg *const bldCfg, const BldHlp *const bld
xmlNodeAttributeSet(xmlSection, STRDEF("id"), strNewFmt("section-%s", strZ(section->id)));
xmlNodeContentSet(xmlSectionTitle, strNewFmt("%s Options", strZ(section->name)));
xmlNodeChildAdd(xmlNodeAdd(xmlSection, STRDEF("text")), section->introduction);
xmlNodeChildAdd(xmlSection, section->introduction);
for (unsigned int optIdx = 0; optIdx < lstSize(bldHlp->optList); optIdx++)
{
@ -238,7 +238,7 @@ referenceCommandRender(const BldCfg *const bldCfg, const BldHlp *const bldHlp)
xmlNodeAttributeSet(xmlIntro, STRDEF("id"), STRDEF("introduction"));
xmlNodeContentSet(xmlNodeAdd(xmlIntro, STRDEF("title")), STRDEF("Introduction"));
xmlNodeChildAdd(xmlNodeAdd(xmlIntro, STRDEF("text")), bldHlp->cmdIntroduction);
xmlNodeChildAdd(xmlIntro, bldHlp->cmdIntroduction);
for (unsigned int cmdIdx = 0; cmdIdx < lstSize(bldHlp->cmdList); cmdIdx++)
{
@ -257,7 +257,7 @@ referenceCommandRender(const BldCfg *const bldCfg, const BldHlp *const bldHlp)
xmlNodeContentSet(xmlSectionTitle, strNewFmt("%s Command (", strZ(cmdHlp->title)));
xmlNodeContentSet(xmlNodeAdd(xmlSectionTitle, STRDEF("id")), cmdHlp->name);
xmlNodeContentSet(xmlSectionTitle, STRDEF(")"));
xmlNodeChildAdd(xmlNodeAdd(xmlSection, STRDEF("text")), cmdHlp->description);
xmlNodeChildAdd(xmlSection, cmdHlp->description);
// Build option list for command
StringList *const sctList = strLstNew();

1
doc/xml/release/2023/2.49.xml
View File

@ -9,6 +9,7 @@
<commit subject="Use CSS to number sections in documentation."/>
<commit subject="Build command and configuration reference in C."/>
<commit subject="Simplify section titles in configuration reference."/>
<commit subject="Simplify description rendering in command and configuration reference."/>
<p>Build command and configuration reference in C.</p>
</release-item>

28
test/src/module/doc/buildTest.c
View File

@ -216,16 +216,16 @@ testRun(void)
"<description>config description</description>"
"<section id=\"introduction\">"
"<title>Introduction</title>"
"<text><p>config text</p></text>"
"<p>config text</p>"
"</section>"
"<section id=\"section-general\">"
"<title>General Options</title>"
"<text><p>general section</p></text>"
"<p>general section</p>"
"<section id=\"option-buffer-size\">"
"<title>Buffer Size Option (<id>--buffer-size</id>)</title>"
"<p>Buffer size option summary.</p>"
"<p>FOR BETA TESTING ONLY. DO NOT USE IN PRODUCTION.</p>"
"<p><p>Buffer size option description.</p></p>"
"<p>Buffer size option description.</p>"
"<code-block>default: 1024\n"
"example: buffer-size=128KiB\n"
"example: buffer-size=256KiB</code-block>"
@ -233,12 +233,12 @@ testRun(void)
"<section id=\"option-config\">"
"<title>Config Option (<id>--config</id>)</title>"
"<p>config option summary.</p>"
"<p><p>config option description.</p></p>"
"<p>config option description.</p>"
"</section>"
"<section id=\"option-secure\">"
"<title>Secure Option (<id>--secure</id>)</title>"
"<p>Secure option summary.</p>"
"<p><p>Secure option description</p></p>"
"<p>Secure option description</p>"
"<code-block>default: n</code-block>"
"</section>"
"</section>"
@ -257,17 +257,17 @@ testRun(void)
// {uncrustify_off - indentation}
"<description>command description</description>"
"<section id=\"introduction\"><title>Introduction</title>"
"<text><p>command text</p></text>"
"<p>command text</p>"
"</section>"
"<section id=\"command-backup\">"
"<title>Backup Command (<id>backup</id>)</title>"
"<text><p>Backup command description.</p></text>"
"<p>Backup command description.</p>"
"<section id=\"category-command\" toc=\"n\">"
"<title>Command Options</title>"
"<section id=\"option-force\">"
"<title>Force Backup Option (<id>--force</id>)</title>"
"<p>Force option command backup summary.</p>"
"<p><p>Force option command backup description.</p></p>"
"<p>Force option command backup description.</p>"
"<code-block>default: y\n"
"example: --no-force --force</code-block>"
"<p>Deprecated Name: frc</p>"
@ -275,7 +275,7 @@ testRun(void)
"<section id=\"option-repo-compress-level\">"
"<title>Repo Compress Level Backup Option (<id>--repo-compress-level</id>)</title>"
"<p>Repo compress level option command backup summary.</p>"
"<p><p>Repo compress level option command backup description.</p></p>"
"<p>Repo compress level option command backup description.</p>"
"<code-block>default: 9\n"
"allowed: 0-9\n"
"example: --repo1-compress-level=4</code-block>"
@ -287,7 +287,7 @@ testRun(void)
"<title>Buffer Size Option (<id>--buffer-size</id>)</title>"
"<p>Buffer size option summary.</p>"
"<p>FOR BETA TESTING ONLY. DO NOT USE IN PRODUCTION.</p>"
"<p><p>Buffer size option description.</p></p>"
"<p>Buffer size option description.</p>"
"<code-block>default: 1024\n"
"example: --buffer-size=128KiB --buffer-size=256KiB</code-block>"
"</section>"
@ -295,21 +295,21 @@ testRun(void)
"</section>"
"<section id=\"command-check\">"
"<title>Check Command (<id>check</id>)</title>"
"<text><p>Check command description.</p></text>"
"<p>Check command description.</p>"
"<section id=\"category-general\" toc=\"n\">"
"<title>General Options</title>"
"<section id=\"option-buffer-size\">"
"<title>Buffer Size Option (<id>--buffer-size</id>)</title>"
"<p>Buffer size option summary.</p>"
"<p>FOR BETA TESTING ONLY. DO NOT USE IN PRODUCTION.</p>"
"<p><p>Buffer size option description.</p></p>"
"<p>Buffer size option description.</p>"
"<code-block>default: 1024\n"
"example: --buffer-size=128KiB --buffer-size=256KiB</code-block>"
"</section>"
"<section id=\"option-config\">"
"<title>Config Option (<id>--config</id>)</title>"
"<p>config option summary.</p>"
"<p><p>config option description.</p></p>"
"<p>config option description.</p>"
"</section>"
"</section>"
"<section id=\"category-stanza\" toc=\"n\">"
@ -317,7 +317,7 @@ testRun(void)
"<section id=\"option-stanza\">"
"<title>Stanza Option (<id>--stanza</id>)</title>"
"<p>Stanza option summary.</p>"
"<p><p>Stanza option description</p></p>"
"<p>Stanza option description</p>"
"<code-block>default: demo</code-block>"
"<p>Deprecated Names: stanza1, stanza2</p>"
"</section>"