__ini_value: add man.rst

cdist/conf/type/__ini_value/man.rst

@@ -0,0 +1,127 @@
+cdist-type__ini_value(7)
+========================
+
+NAME
+----
+cdist-type__ini_value - Handles ini- and conf-style configuration options
+
+
+DESCRIPTION
+-----------
+This cdist type allow changes to more advanced key-value based configurations.
+Most commonly this would be ini- or conf-style configurations.
+
+The type can have following states:
+
+    present
+        The line exists with the correct value.
+
+    commented
+        The key-value is outcommented.
+
+    absent
+        The key-value line does not exist in the given section.
+
+
+REQUIRED PARAMETERS
+-------------------
+file
+    The file to modify.
+
+delimiter
+    The delimiter which seperates each key-value pair.
+
+
+OPTIONAL PARAMETERS
+-------------------
+state
+    One of the states defined in the above section. Defaults to `present`.
+
+section
+    The section where the value is located at. It always need to be surrounded
+    by square brackets as common for ini files. If not, the section will not be
+    found. If no section is specified, the block before any section is meant.
+
+key
+    The key to identify the key-value pair. Must be set if the state is not
+    absent.
+
+value
+    The value assigned to the key. Must be set if the state is not absent.
+    Else, an empty value is assigned to the given key.
+
+comment
+    The comment which should be placed above the configuration line.
+
+indentation
+    The indentation the key-value pair should have. Will be applied on inserts,
+    but also be enforced if ``--normalize`` is set.
+
+comment-sign
+    This declares the comment signs that are valid to use in the configuration
+    file. Each parameter must declare a single character only; multiple
+    parameters are possible. It uses the first specified sign as comment
+    character if this type needs to insert comments.
+
+
+BOOLEAN PARAMETERS
+------------------
+normalize
+    This parameter enforces that the parameter is always pretty in the
+    configuration file. Even if a key-value pair is correct as-is, it will
+    correct the line to be pretty and perfect.
+
+
+MESSAGES
+--------
+The type currently fails to give a correct information of what he did cause of
+the following construct. It has two `awk` scripts which do the job:
+
+1. The explorer script which will outputs a single state of the given
+   key-value. Because the current state can contain much more states than the
+   state that should be, one state is returned like `wrongvalue` even if
+   `commented` is correct, too. Therefor, it vanishes the information that the
+   line is commented, too, even this could be a nice information that the
+   messaging system could emit.
+
+2. The `code-remote` script also goes through the whole file and print out the
+   same file except the line line that should be changed. This is done because
+   it can not be garanteed that an other type already modifed the file, which
+   may moved the key-value to an other position. Then, the script replaces the
+   line which a pretty-printed key-value pair.
+
+So the detected state is not important for the remote script, as it only needs
+to know that it must be run cause of differences and what the state should be.
+So if there are a state like `wrongvalue`, it triggers to correction of the
+line, but it do not care if it was `wrongvalue`, `wrongformat` or `commented`
+which trigged the run. Because of this need, the explorer retuns only an
+easy-to-use value to detect if something needs to be changed.
+
+Therefor, it is unable to correctly emit messages with the current base.
+
+
+EXAMPLES
+--------
+
+.. code-block:: sh
+
+    # set a value in a configuration
+    __ini_value fancy-id --file /etc/foo/bar.ini --section '[welcome]' \
+        --key hi --value baz --delimiter ' = '
+
+    # outcomment a value
+    __ini_value foo --file /etc/bar/foo.conf --state commented \
+        --key noop --value true --delimiter ' = ' --comment 'not this time!'
+
+
+AUTHORS
+-------
+Matthias Stecher <matthiasstecher at gmx.de>
+
+
+COPYING
+-------
+Copyright \(C) 2021 Matthias Stecher. You can redistribute it
+and/or modify it under the terms of the GNU General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.