Add 17.12.0 documentation

Built with `quattor-documentation-builder -c -m src/ -o output/ --info` with some cleanup and whitespace trimming.

docs/CAF/Application.md

@@ -43,7 +43,7 @@ Applications can extend or overwrite the default methods.
 - version(): string
 
     Returns the version number as defined in $self->{'VERSION'}, or
-    <unknown> if not defined.
+    <unknown> if not defined.
 
 - hostname(): string
 
@@ -64,7 +64,7 @@ Applications can extend or overwrite the default methods.
     Returns the option value coming from the command line and/or
     configuration file. Scalar can be a string, or a reference to a hash
     or an array containing the option's value. option() is a wrapper
-    on top of AppConfig->get($opt). 
+    on top of AppConfig->get($opt).
 
     If the option doesn't exist, returns `undef`, except if the `default`
     argument has been specified: in this case this value is returned but

docs/CAF/Exception.md

@@ -0,0 +1,57 @@
+
+### NAME
+
+CAF::Exception - provides basic methods for failure and exception handling
+
+#### Private methods
+
+- \_get\_noaction
+
+    Return NoAction setting:
+
+    - Return 0 is `keeps_state` is true
+
+        Any other value of `keeps_state` is ignored. (In particular,
+        you cannot use `keeps_state` to enable NoAction).
+
+    - Return value of `noAction` method (when defined)
+    - `CAF::Object::NoAction` otherwise
+
+    Supports an optional `msg` that is prefixed to reporter.
+
+- \_reset\_exception\_fail
+
+    Reset previous fail attribute and/or exception.
+
+    `msg` is a suffix when reporting the old `fail` attribute
+    and/or exception error (with debug level 1).
+
+    `EC` is a `LC::Exception::Context` instance that is checked for an
+    existing error, which is set to ignore if it exists.
+
+    Always returns SUCCESS.
+
+- \_function\_catch
+
+    Execute function reference `funcref` with arrayref `$args` and hashref `$opts`.
+
+    Method resets any existing fail attribute and error from `LC::Exception::Context` instance `EC`.
+
+    When an exception thrown is thrown, it is catched and reset. No error is reported
+    and undef is returned in this case and the fail attribute is set with the exception
+    error text.
+
+- \_safe\_eval
+
+    Run function reference `funcref` with arrayref `argsref` and hashref `optsref`.
+
+    Return and set fail attribute with `failmsg` (`$@` is added when set) on die
+    or in case of an error (`undef` returned by `funcref`).
+    In case of success, report `msg` (stringified result is added unless `sensitive` attribute is set)
+    at verbose level.
+
+    Note that `_safe_eval` doesn't work with functions
+    that don't return a defined value when they succeed.
+
+    Resets previous fail attribute and or exceptions
+    (via the `LC::Exception::Context` instance `EC`).

docs/CAF/FileWriter.md

@@ -72,7 +72,9 @@ This is a wrapper class for `IO::String` with customised close based on
 
     - `backup`
 
-        Path for the backup file, if this one has to be re-written.
+        Create a backup file when the file already exists and will be modified.
+        The value is used as a suffix to create the backup filename
+        (e.g. `.old`).
 
     - `keeps_state`
 

docs/CAF/Path.md

@@ -42,41 +42,6 @@ undef on failure and store the error message in the `fail` attribute.
 
 #### Methods
 
-- \_get\_noaction
-
-    Return NoAction setting:
-
-    - Return 0 is `keeps_state` is true
-
-        Any other value of `keeps_state` is ignored. (In particular,
-        you cannot use `keeps_state` to enable NoAction).
-
-    - Return value of `CAF::Object::NoAction` otherwise.
-
-    Supports an optional `msg` that is prefixed to reporter.
-
-- \_reset\_exception\_fail
-
-    Reset previous exceptions and/or fail attribute.
-
-- \_function\_catch
-
-    Execute function reference `funcref` with arrayref `$args` and hashref `$opts`.
-
-    Method resets/ignores any existing errors and fail attribute, and catches any exception thrown.
-    No error is reported, it returns undef in this case and the fail attribute is set.
-
-- \_safe\_eval
-
-    Run function reference `funcref` with arrayref `argsref` and hashref `optsref`.
-
-    Return and set fail attribute with `failmsg` on die or an error (`undef` returned
-    by `funcref`), or print (at verbose level) `msg` on success (respectively $@ and
-    stringified result are appended). Note that `_safe_eval` doesn't work with functions
-    that don't return a defined value when they succeed.
-
-    Resets previous exceptions and/or fail attribute
-
 - LC\_Check
 
     Execute function `<LC::Check::<function`>> with arrayref `$args` and hashref `$opts`.
@@ -140,7 +105,7 @@ undef on failure and store the error message in the `fail` attribute.
     Returns CHANGED is something was cleaned-up, SUCCESS if nothing was done
     and undef on failure (and sets the fail attribute).
 
-    The &lt;backup> is a suffix for `dest`.
+    The <backup> is a suffix for `dest`.
 
     If backup is undefined, use `backup` attribute.
     (Pass an empty string to disable backup with `backup` attribute defined)
@@ -278,7 +243,7 @@ undef on failure and store the error message in the `fail` attribute.
     does not exist to start with, success is immediately returned,
     and no backup of `dest` is created).
 
-    The &lt;backup> is a suffix for the cleanup of `dest`
+    The <backup> is a suffix for the cleanup of `dest`
     (and passed to `cleanup` method).
 
     (The basedir of `dest` is created using `directory` method.)

docs/CAF/Process.md

@@ -72,6 +72,17 @@ secure.
             By default, commands modify the state and thus `keeps_state` is
             false.
 
+        - `sensitive`
+
+            A boolean specifying whether the arguments contain sensitive information
+            (like passwords). If `sensitive` is true, the commandline will not be reported
+            (by default when `log` option is used, the commandline is reported
+            with verbose level).
+
+            This does not cover command output. If the output (stdout and/or stderr) contains
+            sensitve information, make sure to handle it yourself via `stdout` and/or `stderr`
+            options (or by using the `output` method).
+
         These options will only be used by the execute method.
 
 - \_LC\_Process
@@ -81,7 +92,7 @@ secure.
     `noaction_value` is is the value to return with `NoAction`.
 
     `msg` and `postmsg` are used to construct log message
-    `<<msg` command: <COMMAND>\[ &lt;postmsg>\]>>.
+    `<<msg` command: <COMMAND>\[ <postmsg>\]>>.
 
 #### Public methods
 

docs/CAF/TextRender.md

@@ -53,7 +53,7 @@ This class simplyfies the generation of structured text like config files.
 
             .INI format (using `Config::Tiny`)
 
-        (Previously available module <general> was removed in 15.12.
+        (Previously available module <general> was removed in 15.12.
         Component writers needing this functionality can use
         the **CCM::TextRender** subclass instead).
 

docs/CCM/CacheManager::Element.md

@@ -153,10 +153,17 @@ The class <EDG::WP4::CCM::CacheManager::Element> is a base class for
     - convert\_nlist
 
         Array ref of anonymous methods to convert the argument
-        (nlist of elements) to another representation/format.
+        (dict of elements) to another representation/format.
 
         Each element is already processed before the conversion.
 
+    - convert\_key
+
+        Array ref of anonymous methods to convert the key(s) of the dicts
+        to another representation/format.
+
+        At the end, a stringification of the result is used as key.
+
     The arrayref of anonymous methods are applied as follows:
     convert methods `[a, b, c]` will produce `$new = c(b(a($old)))`.
     (An exception is thrown if these methods are not code references).

docs/CCM/Options.md

@@ -57,16 +57,16 @@ Available convenience methods:
     Add actions defined in hashref to the supported actions.
 
     When creating a new module derived from EDG::WP4::CCM::Options,
-    add methods named "action\_<something>", and add then via this method
+    add methods named "action\_<something>", and add then via this method
     to the \_actions hashref.
 
     This will create a commandline option "--something", if selected,
-    will execute the action\_&lt;something> method.
+    will execute the action\_<something> method.
 
     The hashref key is the action name, the value is the help text.
 
     (Returns the \_actions hashref for unittesting purposes)
 
 - action
 
-    Run first of the predefined actions via the action\_&lt;actionname> methods
+    Run first of the predefined actions via the action\_<actionname> methods

docs/CCM/Path.md

@@ -103,7 +103,7 @@ to manipulate absolute paths
     or compiled regular expressions.
 
     These child subpaths are safe to represent as their unescaped value
-    wrapped in `{}` when <toString> method is called (e.g. during stringification).
+    wrapped in `{}` when <toString> method is called (e.g. during stringification).
 
     Parent paths who have a safe-to escape parent path of their own should be added
     already escaped.

docs/CCM/TextRender.md

@@ -32,31 +32,31 @@ difference the support of a `EDG::WP4::CCM::CacheManager::Element` instance as c
             - scalar
 
                 converted in a single line
-                    <key> <value>
+                    <key> <value>
 
             - arrayref of scalars
 
                 converted in multiple lines as follows
-                    &lt;key> &lt;scalar element0>
-                    &lt;key> &lt;scalar element1>
+                    <key> <scalar element0>
+                    <key> <scalar element1>
                     ...
 
             - hashref
 
                 generates a block with format
                     <"key">
-                        &lt;recursive rendering of the value>
-                    &lt;/"key">
+                        <recursive rendering of the value>
+                    </"key">
 
             - arrayref of hashref
 
                 generates series of blocks
                     <"key">
-                        &lt;recursive rendering of the element0>
-                    &lt;/"key">
+                        <recursive rendering of the element0>
+                    </"key">
                     <"key">
-                        &lt;recursive rendering of the element1>
-                    &lt;/"key">
+                        <recursive rendering of the element1>
+                    </"key">
                     ...
 
             (Whitespace in the block name is enforced with double quotes.)
@@ -149,6 +149,18 @@ difference the support of a `EDG::WP4::CCM::CacheManager::Element` instance as c
 
             Caveat: is preceded by `joincomma` option.
 
+        - unescapekey
+
+            Unescape all dict keys.
+
+        - lowerkey
+
+            Convert all dict keys to lowercase.
+
+        - upperkey
+
+            Convert all dict keys to uppercase.
+
         Other `getTree` options
 
         - depth

docs/Unittesting/Quattor.md

@@ -121,6 +121,13 @@ that control the following variables:
 
     You can add paths using the `set_immutable` function.
 
+- `%status`
+
+    The content of this hash (keys are the absolute path names) indicates
+    current `CAF::Path::status` (`mode`, `mtime`, `owner` and/or `group`).
+
+    You can add paths using the `set_status` function.
+
 #### Redefined functions
 
 In order to achieve this, the following functions are redefined
@@ -238,6 +245,10 @@ automatically:
 
     `remove_any` and store args in `caf_path` using `add_caf_path`.
 
+- `CAF::Path::status`
+
+    Set and compare status.
+
 - `CAF::Path::_listdir`
 
     Mock underlying \_listdir method that does the actual opendir/readdir/closedir.
@@ -256,6 +267,7 @@ The following functions are exported by default:
 - `set_file_contents`
 
     For file `$filename`, sets the initial `$contents` the component should see.
+    It also sets the default [FileWriter](../CAF/FileWriter.md) permissions (`mode` 644).
 
     Returns the contents on success, undef otherwise.
 
@@ -342,7 +354,11 @@ The following functions are exported by default:
 - set\_immutable
 
     Make [path](../components/path.md) immutable. Pass a false `bool` to make the path mutable again
-    (not <undef>, default is to make the path immutable).
+    (not <undef>, default is to make the path immutable).
+
+- set\_status
+
+    (Re)set status of [path](../components/path.md) to the options (`mode`, `mtime`, `owner` and/or `group`).
 
 - is\_mutable
 

docs/Unittesting/Quattor::Doc.md

@@ -22,7 +22,7 @@ Should be used mainly as follows:
         Array reference of directories to test for podfiles.
         Default dirs are the relative paths `target/lib/perl`
         and `target/doc/pod` (use the exported `@DOC_TEST_PATHS`
-        list of defaults or resp. `$DOC_TARGET_PERL` and <$DOC\_TARGET\_POD>)
+        list of defaults or resp. `$DOC_TARGET_PERL` and <$DOC\_TARGET\_POD>)
 
     - podfiles
 

docs/Unittesting/Quattor::TextRender.md

@@ -86,7 +86,7 @@ Run tests based on gather\_tt results; returns nothing.
 
 #### gather\_pan
 
-Same as Test::Quattor::Object `gather_pan`, but with <relpath> set
+Same as Test::Quattor::Object `gather_pan`, but with <relpath> set
 to the instance 'basepath'. (With `panpath` and `pannamespace` as arguments)
 
 #### make\_namespace

docs/components-grid/condorconfig.md

@@ -1,16 +1,16 @@
 
 ### NAME
 
-The _condorconfig_ component manages the configuration file of 
-Condor.  
+The _condorconfig_ component manages the configuration file of
+Condor.
 
 ### DESCRIPTION
 
 The _condorconfig_ component manages the configuration file (default
 is `/opt/condor/etc/condor.conf`) for Condor.  All of the condor
 parameters are available with exactly the same name in Quattor.  See
 the condor documentation for the names and descriptions of the
-parameters. 
+parameters.
 
 ### RESOURCES