Adding upstream version 2.8.5.upstream/2.8.5upstream

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

4 files changed, 606 insertions, 0 deletions

diff --git a/docs/manpage.example b/docs/manpage.example
new file mode 100644
index 0000000..efd9276
--- /dev/null
+++ b/docs/manpage.example
@@ -0,0 +1,114 @@
+.\" In .TH, FOO should be all caps, SECTION should be 1-8, maybe w/ subsection
+.\" other parms are allowed: see man(7), man(1)
+.\"
+.\" This template provided by Tom Christiansen <tchrist@jhereg.perl.com>.
+.\" 
+.TH FOO SECTION 
+.SH NAME
+foo, bar \- programs to do something
+.SH SYNOPSIS
+A short usage summary.
+.PP
+.B foo
+{
+.BR this | that
+}
+[
+.B -flags
+]
+[
+.B \-o
+.I option
+]
+.I argument
+[
+.I more...
+]
+.SH DESCRIPTION
+.\" Putting a newline after each sentence can generate better output.
+Long drawn-out discussion of the program.
+It's a good idea to break this up into subsections using the .SS macro,
+like these:
+.SS "A Sample Subsection"
+.SS "Yet Another Sample Subsection"
+References to the
+.BR foo (SECTION)
+(or other) manual page should use the .BR macro as here.
+.PP
+Use the .PP macro to start a new paragraph within a section.
+.SH OPTIONS
+Some people make this separate from the description.
+The following style is typically used to document options:
+.TP
+.BR this | that
+The user MUST specify either
+.B this
+or
+.B that
+to run the program.
+The { and } braces mean one of the enclosed is required.
+The bar (|) separates exclusive options (i.e. you cannot have both at once).
+.TP
+.B \-o
+Pass the user-supplied
+.I option
+to
+.B foo
+to change its behaviour.
+The fact that
+.I option
+is underlined or in italics means that the user replaces it with a valid
+value for this option.
+The [ and ] brackets mean it isn't required.
+.IP
+Use \(oq\e-\(cq rather than \(oq-\(cq for dashes in command-line options.
+\(oq-\(cq means hyphen, and formats differently when using certain output
+devices.
+.TP
+.I argument
+The last
+.I argument
+is required, because it is not in brackets.
+.TP
+.I more
+means that the user can optionally specify additional arguments at the end.
+The ellipses (...) indicate one or more of this parameter is allowed.
+.SH "RETURN VALUE"
+What the program or function returns if successful.
+.SH ERRORS
+Return codes, either exit status or errno settings.
+.SH EXAMPLES
+Give some example uses of the program.
+.SH ENVIRONMENT
+Environment variables this program might care about.
+.SH FILES
+All files used by the program.
+Typical usage is like this:
+.br
+.nf
+.\" set tabstop to longest possible filename, plus a wee bit
+.ta \w'/usr/lib/perl/getopts.pl   'u
+\fI/usr/man\fR	default man tree
+\fI/usr/man/man*/*.*\fR	unformatted (nroff source) man pages
+.SH NOTES
+Miscellaneous commentary.
+.SH CAVEATS
+Things to take special care with, sometimes called WARNINGS.
+.SH DIAGNOSTICS
+All the possible error messages the program can print out,
+what they mean, and how to correct them if applicable.
+.SH BUGS
+Things that are broken or just don't work quite right.
+.SH RESTRICTIONS
+Bugs you don't plan to fix. :-)
+.SH AUTHOR
+Who wrote it (or AUTHORS if multiple).
+.SH HISTORY
+Programs derived from other sources sometimes have this.
+.SH "SEE ALSO"
+.\" Always quote multiple words for .SH
+Other man pages to check out, like
+.BR man (1),
+.BR man (7),
+.BR mandb (8),
+.BR catman (8).
diff --git a/docs/manpage.example.mdoc b/docs/manpage.example.mdoc
new file mode 100644
index 0000000..b10fee7
--- /dev/null
+++ b/docs/manpage.example.mdoc
@@ -0,0 +1,134 @@
+.\" -mdoc is a groff macro package supporting logical formatting. The author
+.\" of this example considers it the best package available in groff for
+.\" writing manual pages. If you're used to the traditional Unix -man
+.\" macros, give this a try; it doesn't take long to learn. groff_mdoc(7) is
+.\" a complete reference manual.
+.\"
+.\" Many of the macros below stack, so ".Op Ar foo" means an optional
+.\" argument called "foo", while ".Ar foo" means an argument called "foo".
+.\" Where you see things like ".Ql .Fl" below, the second dot causes ".Fl"
+.\" to be interpreted as ordinary text rather than calling the .Fl macro.
+.Dd June 4, 2005
+.Os FooOS
+.Dt FOO 1
+.Sh NAME
+.Nm foo
+.Nd program to do something
+.Sh SYNOPSIS
+A short usage summary.
+.Pp
+.Nm
+.Brq Cm this | Cm that
+.Op Fl flags
+.Op Fl o Ar option
+.Ar argument
+.\" Punctuation is treated specially by -mdoc, and often gets pushed up
+.\" against whatever precedes it without the special formatting, so having
+.\" an underlined argument immediately followed by a normal comma is easy.
+.\" If you want to make sure this special handling isn't applied, put a
+.\" zero-width space, \&, before the punctuation.
+.Op Ar more \&...
+.Sh DESCRIPTION
+.\" Putting a newline after each sentence generates better output.
+Long drawn-out discussion of the program.
+It's a good idea to break this up into subsections using the
+.Ql .Ss
+macro, like these:
+.Ss A Sample Subsection
+.Ss Yet Another Sample Subsection
+.Pp
+References to the
+.Xr foo SECTION
+(or other) manual page should use the
+.Ql .Xr
+macro as here.
+References to the
+.Sx OPTIONS
+(or other) section within this manual page should use the
+.Ql .Sx
+macro as here.
+.Pp
+Use the
+.Ql .Pp
+macro to start a new paragraph within a section.
+.Sh OPTIONS
+Some people make this separate from the description.
+The following list style is typically used to document options:
+.Bl -tag -width 4n
+.It Cm this | Cm that
+The user MUST specify either
+.Cm this
+or
+.Cm that
+to run the program.
+The { and } braces (using the
+.Ql .Brq
+macro) mean one of the enclosed is required.
+The bar (|) separates exclusive options (i.e. you cannot have both at once).
+.It Fl o
+Pass the user-supplied
+.Ar option
+to
+.Nm
+to change its behaviour.
+The fact that
+.Ar option
+is underlined or in italics means that the user replaces it with a valid
+value for this option.
+The [ and ] brackets (using the
+.Ql .Op
+macro) mean it isn't required.
+.Pp
+Use the
+.Ql .Fl
+macro to render dashes in command-line option.
+.It Ar argument
+The last
+.Ar argument
+is required, because it is not in brackets.
+.It Ar more
+means that the user can optionally specify additional arguments at the end.
+The ellipses
+.Pf ( Ar ... )
+indicate one or more of this parameter is allowed.
+.\" Remember to close lists you open with .Bl.
+.El
+.Sh RETURN VALUE
+What the program or function returns if successful.
+.Sh ERRORS
+Return codes, either exit status or errno settings.
+.Sh EXAMPLES
+Give some example uses of the program.
+.Sh ENVIRONMENT
+Environment variables this program might care about.
+.Sh FILES
+All files used by the program.
+Typical usage is like this:
+.Pp
+.Bl -tag -width "/usr/man/man*/*.*" -compact
+.It Pa /usr/man
+default man tree
+.It Pa /usr/man/man*/*.*
+unformatted (nroff source) man pages
+.El
+.Sh NOTES
+Miscellaneous commentary.
+.Sh CAVEATS
+Things to take special care with, sometimes called WARNINGS.
+.Sh DIAGNOSTICS
+All the possible error messages the program can print out,
+what they mean, and how to correct them if applicable.
+.Sh BUGS
+Things that are broken or just don't work quite right.
+.Sh RESTRICTIONS
+Bugs you don't plan to fix. :-)
+.Sh AUTHOR
+Who wrote it (or AUTHORS if multiple).
+.Sh HISTORY
+Programs derived from other sources sometimes have this.
+.Sh SEE ALSO
+Other man pages to check out, like
+.Xr man 1 ,
+.Xr man 7 ,
+.Xr mandb 8 ,
+.Xr catman 8 .
diff --git a/docs/manpage.example.pod b/docs/manpage.example.pod
new file mode 100644
index 0000000..7c62de7
--- /dev/null
+++ b/docs/manpage.example.pod
@@ -0,0 +1,126 @@
+=head1 NAME
+
+foo, bar - programs to do something
+
+=head1 SYNOPSIS
+
+A short usage summary.
+
+B<foo> { B<this>|B<that> } [ B<-flags> ] [ B<-o> I<option> ] I<argument> [ I<more...> ]
+
+=head1 DESCRIPTION
+
+Long drawn-out discussion of the program. It's a good idea to break this
+up into subsections using "=head2" directives, like these:
+
+=head2 A Sample Subsection
+
+=head2 Yet Another Sample Subsection
+
+References to the foo(1) (or other) manual page should be written normally
+as here; B<pod2man> will usually guess the correct formatting. Use S<L><>
+(e.g. L<foo(SECTION)>) if you need to force this.
+
+Paragraphs are separated by blank lines.
+
+=head1 OPTIONS
+
+Some people make this separate from the description.
+
+The following style is typically used to document options:
+
+=over 8
+
+=item B<this>|B<that>
+
+The user MUST specify either B<this> or B<that> to run the program. The {
+and } braces mean one of the enclosed is required. The bar (|) separates
+exclusive options (i.e. you cannot have both at once).
+
+=item B<-o>
+
+Pass the user-supplied I<option> to B<foo> to change its behaviour. The
+fact that I<option> is underlined or in italics means that the user replaces
+it with a valid value for this option. The [ and ] brackets mean it isn't
+required.
+
+=item I<argument>
+
+The last I<argument> is required, because it is not in brackets.
+
+=item I<more>
+
+means that the user can optionally specify additional arguments at the end.
+The ellipses (...) indicate one or more of this parameter is allowed.
+
+=back
+
+=head1 RETURN VALUE
+
+What the program or function returns if successful.
+
+=head1 ERRORS
+
+Return codes, either exit status or errno settings.
+
+=head1 EXAMPLES
+
+Give some example uses of the program.
+
+=head1 ENVIRONMENT
+
+Environment variables this program might care about.
+
+=head1 FILES
+
+All files used by the program. Typical usage is like this:
+
+=over 8
+
+=item F</usr/man>
+
+default man tree
+
+=item F</usr/man/man*/*.*>
+
+unformatted (nroff source) man pages
+
+=back
+
+=head1 NOTES
+
+Miscellaneous commentary.
+
+=head1 CAVEATS
+
+Things to take special care with, sometimes called WARNINGS.
+
+=head1 DIAGNOSTICS
+
+All the possible error messages the program can print out, what they
+mean, and how to correct them if applicable.
+
+=head1 BUGS
+
+Things that are broken or just don't work quite right.
+
+=head1 RESTRICTIONS
+
+Bugs you don't plan to fix. :-)
+
+=head1 AUTHOR
+
+Who wrote it (or AUTHORS if multiple).
+
+This example was constructed by Colin Watson <S<cjwatson@debian.org>>
+from a template provided by Tom Christiansen <S<tchrist@jhereg.perl.com>>.
+
+=head1 HISTORY
+
+Programs derived from other sources sometimes have this.
+
+=head1 SEE ALSO
+
+Other man pages to check out, like man(1), man(7), mandb(8), catman(8).
+
+For this example, see pod2man(1) for more details.
diff --git a/docs/manpage.example.sgml b/docs/manpage.example.sgml
new file mode 100644
index 0000000..c460680
--- /dev/null
+++ b/docs/manpage.example.sgml
@@ -0,0 +1,232 @@
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+
+<!-- Process this file with docbook-to-man to generate an nroff manual
+     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
+     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
+     less'.  A typical entry in a Makefile or Makefile.am is:
+
+manpage.1: manpage.sgml
+	docbook-to-man $< > $@
+  -->
+
+<!-- This example was constructed by Colin Watson
+     <email>cjwatson@debian.org</email>, based on a man page template
+     provided by Tom Christiansen <email>tchrist@jhereg.perl.com</email>
+     and a DocBook man page example by Craig Small
+     <email>csmall@debian.org</email>.
+  -->
+
+  <!-- Fill in the various UPPER CASE things here. -->
+  <!ENTITY manfirstname "<firstname>FIRSTNAME</firstname>">
+  <!ENTITY mansurname   "<surname>SURNAME</surname>">
+  <!-- Please adjust the date whenever revising the manpage. -->
+  <!ENTITY mandate      "<date>DATE</date>">
+  <!-- SECTION should be 1-8, maybe with subsection. Other parameters are
+       allowed: see man(7), man(1). -->
+  <!ENTITY mansection   "<manvolnum>SECTION</manvolnum>">
+  <!ENTITY manemail     "<email>EMAIL</email>">
+  <!ENTITY manusername  "USERNAME">
+  <!ENTITY manucpackage "<refentrytitle>UCPACKAGE</refentrytitle>">
+  <!ENTITY manpackage   "PACKAGE">
+]>
+
+<refentry>
+  <refentryinfo>
+    <address>
+      &manemail;
+    </address>
+    <author>
+      &manfirstname;
+      &mansurname;
+    </author>
+    <copyright>
+      <year>2002</year>
+      <holder>&manusername;</holder>
+    </copyright>
+    &mandate;
+  </refentryinfo>
+  <refmeta>
+    &manucpackage;
+
+    &mansection;
+  </refmeta>
+  <refnamediv>
+    <refname>&manpackage;</refname>
+
+    <refpurpose>program to do something</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>&manpackage;</command>
+
+      <group choice="req"><arg>this</arg><arg>that</arg></group>
+      <group choice="opt"><arg>-flags</arg></group>
+      <group choice="opt">
+       <arg>-o <replaceable>option</replaceable></arg>
+      </group>
+      <arg>argument</arg>
+      <arg rep="repeat" choice="opt"><replaceable>more</replaceable></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>DESCRIPTION</title>
+
+    <para>Long drawn-out discussion of <command>&manpackage;</command>.
+      It's a good idea to break this up into subsections, like these:</para>
+
+    <refsect2>
+      <title>A Sample Subsection</title>
+      <para></para>
+    </refsect2>
+    <refsect2>
+      <title>Yet Another Sample Subsection</title>
+
+      <para>References to the
+        <citerefentry>
+         <refentrytitle>foo</refentrytitle><manvolnum>SECTION</manvolnum>
+        </citerefentry> (or other) manual page should use the
+        <markup>&lt;citerefentry&gt;</markup> element as here.
+      </para>
+
+      <para>Each paragraph within a section is contained within a
+        <markup>&lt;para&gt;</markup> tag.</para>
+    </refsect2>
+  </refsect1>
+  <refsect1>
+    <title>OPTIONS</title>
+
+    <para>Some people make this separate from the description.</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><option>this</option>|<option>that</option></term>
+        <listitem>
+          <para>The user MUST specify either <option>this</option> or
+            <option>that</option> to run the program. The { and } braces
+            mean one of the enclosed is required. The bar (|) separates
+            exclusive options (i.e. you cannot have both at once.)</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>-o</option></term>
+        <listitem>
+          <para>Pass the user-supplied <replaceable>option</replaceable> to
+            <command>foo</command> to change its behaviour. The fact that
+            <replaceable>option</replaceable> is underlined or in italics
+            means that the user replaces it with a valid value for this
+            option. The [ and ] brackets mean it isn't required.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>argument</option></term>
+        <listitem>
+          <para>The last <option>argument</option> is required, because it
+            is not in brackets.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>more</option></term>
+        <listitem>
+          <para>means that the user can optionally specify additional
+            arguments at the end. The ellipses (...) indicate one or more of
+            this parameter is allowed.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>RETURN VALUE</title>
+
+    <para>What the program or function returns if successful.</para>
+  </refsect1>
+  <refsect1>
+    <title>ERRORS</title>
+
+    <para>Return codes, either exit status or errno settings.</para>
+  </refsect1>
+  <refsect1>
+    <title>EXAMPLES</title>
+
+    <para>Give some example uses of the program.</para>
+  </refsect1>
+  <refsect1>
+    <title>ENVIRONMENT</title>
+
+    <para>Environment variables this program might care about.</para>
+  </refsect1>
+  <refsect1>
+    <title>FILES</title>
+
+    <para>All files used by the program. Typical usage is like this:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><filename>/usr/man</filename></term>
+        <listitem><para>default man tree</para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><filename>/usr/man/man*/*.*</filename></term>
+        <listitem><para>unformatted (nroff source) man pages</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>NOTES</title>
+
+    <para>Miscellaneous commentary.</para>
+  </refsect1>
+  <refsect1>
+    <title>CAVEATS</title>
+
+    <para>Things to take special care with, sometimes called WARNINGS.</para>
+  </refsect1>
+  <refsect1>
+    <title>DIAGNOSTICS</title>
+
+    <para>All the possible error messages the program can print out, what
+      they mean, and how to correct them if applicable.</para>
+  </refsect1>
+  <refsect1>
+    <title>BUGS</title>
+
+    <para>Things that are broken or just don't work quite right.</para>
+  </refsect1>
+  <refsect1>
+    <title>RESTRICTIONS</title>
+
+    <para>Bugs you don't plan to fix. :-)</para>
+  </refsect1>
+  <refsect1>
+    <title>AUTHOR</title>
+
+    <para>Who wrote it (or AUTHORS if multiple).</para>
+  </refsect1>
+  <refsect1>
+    <title>HISTORY</title>
+
+    <para>Programs derived from other sources sometimes have this.</para>
+  </refsect1>
+  <refsect1>
+    <title>SEE ALSO</title>
+
+    <para>Other man pages to check out, like man(1), man(7), mandb(8),
+      catman(8).</para>
+  </refsect1>
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:2
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->