Better output.conf documentation

2 files changed, 42 insertions, 9 deletions

diff --git a/doc/configuration/output.html.part.in b/doc/configuration/output.html.part.in
index 7a52242b3..6767e850f 100644
--- a/doc/configuration/output.html.part.in
+++ b/doc/configuration/output.html.part.in
@@ -4,8 +4,12 @@
 
 ###PALUDISENVIRONMENTONLY###
 
+<p><strong>Usually you do not need an <code>output.conf</code> at all.</strong> The defaults are generally fine.</p>
+
 <p>The <code>output.conf</code> file controls how Paludis handles output from subcommands such as building and
-installing a package, or syncing a repository.</p>
+installing a package, or syncing a repository. The basic configuration is set in
+<code>$SHAREDIR/environments/paludis/default_output.conf</code>, and additional configuration can be specified by the
+user in <code>output.conf</code> in the normal configuration directory.</p>
 
 <p>There are currently two basic settings that can be set in <code>output.conf</code>:</p>
 
@@ -19,3 +23,26 @@ always_keep_output_logs = false
 quiet = false
 </pre>
 
+<p>For more advanced usage, two additional variables allow additional output managers to be specified:
+
+<pre>
+# extra_output_loggers may be used to define additional output managers that
+# handle normal output.
+extra_output_loggers =
+
+# extra_message_loggers may be used to define additional output managers that
+# handle messages.
+extra_message_loggers =
+</pre>
+
+<p>For example, if you wish to send messages to syslog, you could use:</p>
+
+<pre>
+extra_message_loggers = my_syslog_messages
+
+[manager my_syslog_messages]
+handler = command
+stdout_command = logger -t paludis
+stderr_command = logger -t paludis
+</pre>
+
diff --git a/paludis/environments/paludis/default_output.conf b/paludis/environments/paludis/default_output.conf
index b654babc6..4d6012cd8 100644
--- a/paludis/environments/paludis/default_output.conf
+++ b/paludis/environments/paludis/default_output.conf
@@ -7,11 +7,17 @@
 #
 # We use a few user-settable variables:
 #
-# always_keep_output_logs may be set to 'true' to always keep output logs, even
-# if a build succeeds.
+#   always_keep_output_logs may be set to 'true' to always keep output logs,
+#   even if a build succeeds.
 #
-# quiet may be set to 'true' to show only messages, rather than all output, when
-# carrying out an action.
+#   quiet may be set to 'true' to show only messages, rather than all output,
+#   when carrying out an action.
+#
+#   extra_output_loggers may be used to define additional output managers that
+#   handle normal output.
+#
+#   extra_message_loggers may be used to define additional output managers that
+#   handle messages.
 
 # First, we define some basic rules. If we're running exclusively, use the
 # 'exclusive' manager:
@@ -82,9 +88,9 @@ child = standard
 [manager log_output]
 handler = conditional_alias
 condition_variable = always_keep_output_logs
-if_true = log_output_keep_always
-if_false = log_output_keep_failures
-if_unset = log_output_keep_failures
+if_true = log_output_keep_always ${extra_output_loggers}
+if_false = log_output_keep_failures ${extra_output_loggers}
+if_unset = log_output_keep_failures ${extra_output_loggers}
 
 # Our output log goes to a file, which gets discarded if we succeed or if it's
 # empty. The summary_output options are used to display a message showing the
@@ -137,7 +143,7 @@ format_info = I %{message}%{newline}
 format_warn = W %{message}%{newline}
 format_error = E %{message}%{newline}
 format_log = L %{message}%{newline}
-child = log_messages_always
+child = log_messages_always ${extra_message_loggers}
 
 # Our messages log goes to a file, which gets discarded only if it is empty:
 [manager log_messages_always]