doc: Add man pages to Sphinx documentation

This allows you to generate our manpages directly from the Sphinx
documentation. This commit is more or less copied directly from the
current man pages.

The goal is to integrate these more closely with the current Sphinx
documentation via include directives to prevent duplication and keep all
documentation consistent.

Signed-off-by: Sol Jerome <sol.jerome@gmail.com>

1 files changed, 126 insertions, 0 deletions

diff --git a/doc/man/bcfg2-lint.conf.txt b/doc/man/bcfg2-lint.conf.txt
new file mode 100644
index 000000000..6e0d237ee
--- /dev/null
+++ b/doc/man/bcfg2-lint.conf.txt
@@ -0,0 +1,126 @@
+.. vim: ft=rst
+
+bcfg2-lint.conf
+===============
+
+Description
+-----------
+
+bcfg2-lint.conf includes configuration parameters for bcfg2-lint.
+
+File format
+-----------
+
+The file is INI-style and consists of sections and options. A section
+begins with the name of the sections in square brackets and continues
+until the next section begins.
+
+Options are specified in the form "name=value".
+
+The file is line-based each newline-terminated line represents either a
+comment, a section name or an option.
+
+Any line beginning with a hash (#) is ignored, as are lines containing
+only whitespace.
+
+The file consists of one *[lint]* section, up to one *[errors]* section,
+and then any number of plugin-specific sections, documented below. (Note
+that this makes it quite feasible to combine your *bcfg2-lint.conf* into
+your :manpage:`bcfg2.conf(5)` file, if you so desire).
+
+Global options
+--------------
+
+These options apply to *bcfg2-lint* generally, and must be in the
+*[lint]* section.
+
+plugins
+    A comma-delimited list of plugins to run. By default, all plugins
+    are run. This can be overridden by listing plugins on the command
+    line. See :manpage:`bcfg2-lint(8)` for a list of the available
+    plugins.
+
+Error handling
+--------------
+
+Error handling is configured in the *[errors]* section. Each option
+should be the name of an error and one of *error*, *warning*, or
+*silent*, which tells :program:`bcfg2-lint` how to handle the
+warning. Error names and their defaults can be displayed by running
+:program:`bcfg2-lint` with the *--list-errors* option.
+
+Plugin options
+--------------
+
+These options apply only to a single plugin. Each option should be in a
+section named for its plugin; for instance, options for the InfoXML
+plugin would be in a section called *[InfoXML]*.
+
+If a plugin is not listed below, then it has no configuration.
+
+In many cases, the behavior of a plugin can be configured by modifying
+how errors from it are handled. See ERROR HANDLING, above.
+
+Comments
+++++++++
+
+The *Comments* plugin configuration specifies which VCS keywords and
+comments are required for which file types. The valid types of file are
+*global* (all file types), *bundler* (non-templated bundle files),
+*genshibundler* (templated bundle files), *properties* (property files),
+*cfg* (non-templated Cfg files), *genshi* or *cheetah* (templated Cfg
+files), *infoxml* (info.xml files), and *probe* (probe files).
+
+The specific types (i.e., types other than "global") all supplement
+global; they do not override it. The exception is if you specify an
+empty option, e.g.:
+
+    cfg_keywords =
+
+By default, the *$Id$* keyword is checked for and nothing else.
+
+Multiple keywords or comments should be comma-delimited.
+
+    * *<type>_keywords*
+
+Ensure that files of the specified type have the given VCS keyword. Do
+*not* include the dollar signs. I.e.:
+
+    infoxml_keywords = Revision
+
+*not*
+
+    infoxml_keywords = $Revision$
+
+    * *<type>_comments*
+
+Ensure that files of the specified type have a comment containing the
+given string. In XML files, only comments are checked. In plain text
+files, all lines are checked since comment characters may vary.
+
+InfoXML
++++++++
+
+required_attrs
+    A comma-delimited list of attributes to require on *<Info>* tags.
+    Default is "owner,group,mode".
+
+MergeFiles
+++++++++++
+
+threshold
+    The threshold at which MergeFiles will suggest merging config files
+    and probes. Default is 75% similar.
+
+Validate
+++++++++
+
+schema
+    The full path to the XML Schema files. Default is
+    `/usr/share/bcfg2/schema`. This can be overridden with the
+    *--schema* command-line option.
+
+See Also
+--------
+
+:manpage:`bcfg2-lint(8)`