Adding upstream version 0.70.1+ds1.upstream/0.70.1+ds1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

4 files changed, 405 insertions, 0 deletions

diff --git a/crates/mdman/doc/mdman.md b/crates/mdman/doc/mdman.md
new file mode 100644
index 0000000..2025c13
--- /dev/null
+++ b/crates/mdman/doc/mdman.md
@@ -0,0 +1,95 @@
+# mdman(1)
+
+## NAME
+
+mdman - Converts markdown to a man page
+
+## SYNOPSIS
+
+`mdman` [_options_] `-t` _type_ `-o` _outdir_ _sources..._
+
+## DESCRIPTION
+
+Converts a markdown file to a man page.
+
+The source file is first processed as a
+[handlebars](https://handlebarsjs.com/) template. Then, it is processed as
+markdown into the target format. This supports different output formats,
+such as troff or plain text.
+
+Every man page should start with a level-1 header with the man name and
+section, such as `# mdman(1)`.
+
+The handlebars template has several special tags to assist with generating the
+man page:
+
+{{{{raw}}}}
+- Every block of command-line options must be wrapped between `{{#options}}`
+  and `{{/options}}` tags. This tells the processor where the options start
+  and end.
+- Each option must be expressed with a `{{#option}}` block. The parameters to
+  the the block are a sequence of strings indicating the option. For example,
+  ```{{#option "`-p` _spec_..." "`--package` _spec_..."}}``` is an option that
+  has two different forms. The text within the string is processed as markdown.
+  It is recommended to use formatting similar to this example.
+
+  The content of the `{{#option}}` block should contain a detailed description
+  of the option.
+
+  Use the `{{/option}}` tag to end the option block.
+- References to other man pages should use the `{{man name section}}`
+  expression. For example, `{{man "mdman" 1}}` will generate a reference to
+  the `mdman(1)` man page. For non-troff output, the `--man` option will tell
+  `mdman` how to create links to the man page. If there is no matching `--man`
+  option, then it links to a file named _name_`.md` in the same directory.
+- Variables can be set with `{{*set name="value"}}`. These variables can
+  then be referenced with `{{name}}` expressions.
+- Partial templates should be placed in a directory named `includes`
+  next to the source file. Templates can be included with an expression like
+  `{{> template-name}}`.
+- Other helpers include:
+    - `{{lower value}}` Converts the given value to lowercase.
+{{{{/raw}}}}
+
+## OPTIONS
+
+{{#options}}
+
+{{#option "`-t` _type_"}}
+Specifies the output type. The following output types are supported:
+- `man` — A troff-style man page. Outputs with a numbered extension (like
+  `.1`) matching the man page section.
+- `md` — A markdown file, after all handlebars processing has been finished.
+  Outputs with the `.md` extension.
+- `txt` — A text file, rendered for situations where a man page viewer isn't
+  available. Outputs with the `.txt` extension.
+{{/option}}
+
+{{#option "`-o` _outdir_"}}
+Specifies the directory where to save the output.
+{{/option}}
+
+{{#option "`--url` _base_url_"}}
+Specifies a base URL to use for relative URLs within the document. Any
+relative URL will be joined with this URL.
+{{/option}}
+
+{{#option "`--man` _name_`:`_section_`=`_url_"}}
+Specifies a URL to use for the given man page. When the `\{{man name
+section}}` expression is used, the given URL will be inserted as a link. This
+may be specified multiple times. If a man page reference does not have a
+matching `--man` entry, then a relative link to a file named _name_`.md` will
+be used.
+{{/option}}
+
+{{#option "_sources..._"}}
+The source input filename, may be specified multiple times.
+{{/option}}
+
+{{/options}}
+
+## EXAMPLES
+
+1. Convert the given documents to man pages:
+
+       mdman -t man -o doc doc/mdman.md
diff --git a/crates/mdman/doc/out/mdman.1 b/crates/mdman/doc/out/mdman.1
new file mode 100644
index 0000000..0718d6d
--- /dev/null
+++ b/crates/mdman/doc/out/mdman.1
@@ -0,0 +1,124 @@
+'\" t
+.TH "MDMAN" "1"
+.nh
+.ad l
+.ss \n[.ss] 0
+.SH "NAME"
+mdman \- Converts markdown to a man page
+.SH "SYNOPSIS"
+\fBmdman\fR [\fIoptions\fR] \fB\-t\fR \fItype\fR \fB\-o\fR \fIoutdir\fR \fIsources...\fR
+.SH "DESCRIPTION"
+Converts a markdown file to a man page.
+.sp
+The source file is first processed as a
+\fIhandlebars\fR <https://handlebarsjs.com/> template. Then, it is processed as
+markdown into the target format. This supports different output formats,
+such as troff or plain text.
+.sp
+Every man page should start with a level\-1 header with the man name and
+section, such as \fB# mdman(1)\fR\&.
+.sp
+The handlebars template has several special tags to assist with generating the
+man page:
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'Every block of command\-line options must be wrapped between \fB{{#options}}\fR
+and \fB{{/options}}\fR tags. This tells the processor where the options start
+and end.
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'Each option must be expressed with a \fB{{#option}}\fR block. The parameters to
+the the block are a sequence of strings indicating the option. For example,
+\fB{{#option "`\-p` _spec_..." "`\-\-package` _spec_..."}}\fR is an option that
+has two different forms. The text within the string is processed as markdown.
+It is recommended to use formatting similar to this example.
+.sp
+The content of the \fB{{#option}}\fR block should contain a detailed description
+of the option.
+.sp
+Use the \fB{{/option}}\fR tag to end the option block.
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'References to other man pages should use the \fB{{man name section}}\fR
+expression. For example, \fB{{man "mdman" 1}}\fR will generate a reference to
+the \fBmdman(1)\fR man page. For non\-troff output, the \fB\-\-man\fR option will tell
+\fBmdman\fR how to create links to the man page. If there is no matching \fB\-\-man\fR
+option, then it links to a file named \fIname\fR\fB\&.md\fR in the same directory.
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'Variables can be set with \fB{{*set name="value"}}\fR\&. These variables can
+then be referenced with \fB{{name}}\fR expressions.
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'Partial templates should be placed in a directory named \fBincludes\fR
+next to the source file. Templates can be included with an expression like
+\fB{{> template\-name}}\fR\&.
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'Other helpers include:
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'\fB{{lower value}}\fR Converts the given value to lowercase.
+.RE
+.RE
+.SH "OPTIONS"
+.sp
+\fB\-t\fR \fItype\fR
+.RS 4
+Specifies the output type. The following output types are supported:
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'\fBman\fR \[em] A troff\-style man page. Outputs with a numbered extension (like
+\fB\&.1\fR) matching the man page section.
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'\fBmd\fR \[em] A markdown file, after all handlebars processing has been finished.
+Outputs with the \fB\&.md\fR extension.
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'\fBtxt\fR \[em] A text file, rendered for situations where a man page viewer isn't
+available. Outputs with the \fB\&.txt\fR extension.
+.RE
+.RE
+.sp
+\fB\-o\fR \fIoutdir\fR
+.RS 4
+Specifies the directory where to save the output.
+.RE
+.sp
+\fB\-\-url\fR \fIbase_url\fR
+.RS 4
+Specifies a base URL to use for relative URLs within the document. Any
+relative URL will be joined with this URL.
+.RE
+.sp
+\fB\-\-man\fR \fIname\fR\fB:\fR\fIsection\fR\fB=\fR\fIurl\fR
+.RS 4
+Specifies a URL to use for the given man page. When the \fB{{man name section}}\fR expression is used, the given URL will be inserted as a link. This
+may be specified multiple times. If a man page reference does not have a
+matching \fB\-\-man\fR entry, then a relative link to a file named \fIname\fR\fB\&.md\fR will
+be used.
+.RE
+.sp
+\fIsources...\fR
+.RS 4
+The source input filename, may be specified multiple times.
+.RE
+.SH "EXAMPLES"
+.sp
+.RS 4
+\h'-04' 1.\h'+01'Convert the given documents to man pages:
+.sp
+.RS 4
+.nf
+mdman \-t man \-o doc doc/mdman.md
+.fi
+.RE
+.RE
diff --git a/crates/mdman/doc/out/mdman.md b/crates/mdman/doc/out/mdman.md
new file mode 100644
index 0000000..d0dd345
--- /dev/null
+++ b/crates/mdman/doc/out/mdman.md
@@ -0,0 +1,95 @@
+# mdman(1)
+
+## NAME
+
+mdman - Converts markdown to a man page
+
+## SYNOPSIS
+
+`mdman` [_options_] `-t` _type_ `-o` _outdir_ _sources..._
+
+## DESCRIPTION
+
+Converts a markdown file to a man page.
+
+The source file is first processed as a
+[handlebars](https://handlebarsjs.com/) template. Then, it is processed as
+markdown into the target format. This supports different output formats,
+such as troff or plain text.
+
+Every man page should start with a level-1 header with the man name and
+section, such as `# mdman(1)`.
+
+The handlebars template has several special tags to assist with generating the
+man page:
+
+- Every block of command-line options must be wrapped between `{{#options}}`
+  and `{{/options}}` tags. This tells the processor where the options start
+  and end.
+- Each option must be expressed with a `{{#option}}` block. The parameters to
+  the the block are a sequence of strings indicating the option. For example,
+  ```{{#option "`-p` _spec_..." "`--package` _spec_..."}}``` is an option that
+  has two different forms. The text within the string is processed as markdown.
+  It is recommended to use formatting similar to this example.
+
+  The content of the `{{#option}}` block should contain a detailed description
+  of the option.
+
+  Use the `{{/option}}` tag to end the option block.
+- References to other man pages should use the `{{man name section}}`
+  expression. For example, `{{man "mdman" 1}}` will generate a reference to
+  the `mdman(1)` man page. For non-troff output, the `--man` option will tell
+  `mdman` how to create links to the man page. If there is no matching `--man`
+  option, then it links to a file named _name_`.md` in the same directory.
+- Variables can be set with `{{*set name="value"}}`. These variables can
+  then be referenced with `{{name}}` expressions.
+- Partial templates should be placed in a directory named `includes`
+  next to the source file. Templates can be included with an expression like
+  `{{> template-name}}`.
+- Other helpers include:
+    - `{{lower value}}` Converts the given value to lowercase.
+
+
+## OPTIONS
+
+<dl>
+
+<dt class="option-term" id="option-mdman--t"><a class="option-anchor" href="#option-mdman--t"></a><code>-t</code> <em>type</em></dt>
+<dd class="option-desc">Specifies the output type. The following output types are supported:</p>
+<ul>
+<li><code>man</code> — A troff-style man page. Outputs with a numbered extension (like
+<code>.1</code>) matching the man page section.</li>
+<li><code>md</code> — A markdown file, after all handlebars processing has been finished.
+Outputs with the <code>.md</code> extension.</li>
+<li><code>txt</code> — A text file, rendered for situations where a man page viewer isn't
+available. Outputs with the <code>.txt</code> extension.</li>
+</ul></dd>
+
+
+<dt class="option-term" id="option-mdman--o"><a class="option-anchor" href="#option-mdman--o"></a><code>-o</code> <em>outdir</em></dt>
+<dd class="option-desc">Specifies the directory where to save the output.</dd>
+
+
+<dt class="option-term" id="option-mdman---url"><a class="option-anchor" href="#option-mdman---url"></a><code>--url</code> <em>base_url</em></dt>
+<dd class="option-desc">Specifies a base URL to use for relative URLs within the document. Any
+relative URL will be joined with this URL.</dd>
+
+
+<dt class="option-term" id="option-mdman---man"><a class="option-anchor" href="#option-mdman---man"></a><code>--man</code> <em>name</em><code>:</code><em>section</em><code>=</code><em>url</em></dt>
+<dd class="option-desc">Specifies a URL to use for the given man page. When the <code>{{man name section}}</code> expression is used, the given URL will be inserted as a link. This
+may be specified multiple times. If a man page reference does not have a
+matching <code>--man</code> entry, then a relative link to a file named <em>name</em><code>.md</code> will
+be used.</dd>
+
+
+<dt class="option-term" id="option-mdman-sources..."><a class="option-anchor" href="#option-mdman-sources..."></a><em>sources...</em></dt>
+<dd class="option-desc">The source input filename, may be specified multiple times.</dd>
+
+
+</dl>
+
+## EXAMPLES
+
+1. Convert the given documents to man pages:
+
+       mdman -t man -o doc doc/mdman.md
diff --git a/crates/mdman/doc/out/mdman.txt b/crates/mdman/doc/out/mdman.txt
new file mode 100644
index 0000000..83fa7de
--- /dev/null
+++ b/crates/mdman/doc/out/mdman.txt
@@ -0,0 +1,91 @@
+MDMAN(1)
+
+NAME
+       mdman - Converts markdown to a man page
+
+SYNOPSIS
+       mdman [options] -t type -o outdir sources...
+
+DESCRIPTION
+       Converts a markdown file to a man page.
+
+       The source file is first processed as a handlebars
+       <https://handlebarsjs.com/> template. Then, it is processed as markdown
+       into the target format. This supports different output formats, such as
+       troff or plain text.
+
+       Every man page should start with a level-1 header with the man name and
+       section, such as # mdman(1).
+
+       The handlebars template has several special tags to assist with
+       generating the man page:
+
+       o  Every block of command-line options must be wrapped between
+          {{#options}} and {{/options}} tags. This tells the processor where
+          the options start and end.
+
+       o  Each option must be expressed with a {{#option}} block. The
+          parameters to the the block are a sequence of strings indicating the
+          option. For example, {{#option "`-p` _spec_..." "`--package`
+          _spec_..."}} is an option that has two different forms. The text
+          within the string is processed as markdown. It is recommended to use
+          formatting similar to this example.
+
+          The content of the {{#option}} block should contain a detailed
+          description of the option.
+
+          Use the {{/option}} tag to end the option block.
+
+       o  References to other man pages should use the {{man name section}}
+          expression. For example, {{man "mdman" 1}} will generate a reference
+          to the mdman(1) man page. For non-troff output, the --man option will
+          tell mdman how to create links to the man page. If there is no
+          matching --man option, then it links to a file named name.md in the
+          same directory.
+
+       o  Variables can be set with {{*set name="value"}}. These variables can
+          then be referenced with {{name}} expressions.
+
+       o  Partial templates should be placed in a directory named includes next
+          to the source file. Templates can be included with an expression like
+          {{> template-name}}.
+
+       o  Other helpers include:
+
+          o  {{lower value}} Converts the given value to lowercase.
+
+OPTIONS
+       -t type
+           Specifies the output type. The following output types are supported:
+
+           o  man — A troff-style man page. Outputs with a numbered extension
+              (like .1) matching the man page section.
+
+           o  md — A markdown file, after all handlebars processing has been
+              finished. Outputs with the .md extension.
+
+           o  txt — A text file, rendered for situations where a man page
+              viewer isn't available. Outputs with the .txt extension.
+
+       -o outdir
+           Specifies the directory where to save the output.
+
+       --url base_url
+           Specifies a base URL to use for relative URLs within the document.
+           Any relative URL will be joined with this URL.
+
+       --man name:section=url
+           Specifies a URL to use for the given man page. When the {{man name
+           section}} expression is used, the given URL will be inserted as a
+           link. This may be specified multiple times. If a man page reference
+           does not have a matching --man entry, then a relative link to a file
+           named name.md will be used.
+
+       sources...
+           The source input filename, may be specified multiple times.
+
+EXAMPLES
+       1. Convert the given documents to man pages:
+
+              mdman -t man -o doc doc/mdman.md
+