update rotatelogs docs to reflect the support for -l/UTC-offset

with size-based rotation

move examples to a formal section in the customary order

add an example of logging at midnight with the date in the
filename

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@596830 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/docs/manual/programs/rotatelogs.xml b/docs/manual/programs/rotatelogs.xml
index 86ebb94476a3569548d22497efac5f66bf4168f6..5e8c65d3fc7841984faabf4843faefb0fb78a684 100644 (file)
--- a/docs/manual/programs/rotatelogs.xml
+++ b/docs/manual/programs/rotatelogs.xml
@@ -27,33 +27,7 @@
 
 <summary>
      <p><code>rotatelogs</code> is a simple program for use in
-     conjunction with Apache's piped logfile feature.  For example:</p>
-
-<example>
-     CustomLog "|bin/rotatelogs /var/logs/logfile 86400" common
-</example>
-        
-     <p>This creates the files /var/logs/logfile.nnnn where nnnn  is
-     the system time at which the log nominally starts (this time
-     will always be a multiple of the rotation time, so  you  can
-     synchronize cron scripts with it).  At the end of each rotation
-     time (here after 24 hours) a new log is started.</p>
-
-<example>
-     CustomLog "|bin/rotatelogs /var/logs/logfile 5M" common
-</example>
-
-     <p>This configuration will rotate the logfile whenever it reaches
-     a size of 5 megabytes.</p>
-
-<example>
-     ErrorLog "|bin/rotatelogs /var/logs/errorlog.%Y-%m-%d-%H_%M_%S 5M"
-</example>
-     <p>This configuration will rotate the error logfile whenever it
-     reaches a size of 5 megabytes, and the suffix to the logfile name
-     will be created of the form
-     <code>errorlog.YYYY-mm-dd-HH_MM_SS</code>.</p>
- 
+     conjunction with Apache's piped logfile feature.</p>
 </summary>
 
 <section id="synopsis"><title>Synopsis</title>
@@ -61,8 +35,8 @@
      <p><code><strong>rotatelogs</strong>
      [ -<strong>l</strong> ]
      <var>logfile</var>
-     [ <var>rotationtime</var> [ <var>offset</var> ]] |
-     [ <var>filesize</var>M ]</code></p>
+     <var>rotationtime</var>|<var>filesize</var>M 
+     [ <var>offset</var> ]</code></p>
 </section>
 
 <section id="options"><title>Options</title>
@@ -71,8 +45,10 @@
 
 <dt><code>-l</code></dt>
 <dd>Causes the use of local time rather than GMT as the base for the
-interval. Note that using <code>-l</code> in an environment which changes the
-GMT offset (such as for BST or DST) can lead to unpredictable results!</dd>
+interval or for <code>strftime(3)</code> formatting with size-based 
+rotation.  Note that using <code>-l</code> in an environment which
+changes the GMT offset (such as for BST or DST) can lead to unpredictable
+results!</dd>
 
 <dt><code><var>logfile</var></code></dt>
 
@@ -91,16 +67,55 @@ the current period.</dd>
 
 <dd>The number of minutes offset from UTC.  If omitted, zero is
 assumed and UTC is used.  For example, to use local time in the zone
-UTC -5 hours, specify a value of <code>-300</code> for this argument.</dd>
+UTC -5 hours, specify a value of <code>-300</code> for this argument.
+In most cases, <code>-l</code> should be used instead of specifying
+an offset.</dd>
 
 <dt><code><var>filesize</var>M</code></dt>
 
 <dd>The maximum file size in megabytes followed by the letter
 <code>M</code> to specify size rather than time.  Use this parameter
-in place of both rotationtime and offset.</dd>
+in place of rotationtime.</dd>
 </dl>
 </section>
 
+<section id="examples"><title>Examples</title>
+
+<example>
+     CustomLog "|bin/rotatelogs /var/logs/logfile 86400" common
+</example>
+        
+     <p>This creates the files /var/logs/logfile.nnnn where nnnn  is
+     the system time at which the log nominally starts (this time
+     will always be a multiple of the rotation time, so  you  can
+     synchronize cron scripts with it).  At the end of each rotation
+     time (here after 24 hours) a new log is started.</p>
+
+<example>
+     CustomLog "|bin/rotatelogs -l /var/logs/logfile.%Y.%m.%d 86400" common
+</example>
+        
+     <p>This creates the files /var/logs/logfile.yyyy.mm.dd where
+     yyyy is the year, mm is the month, and dd is the day of the month.
+     Logging will switch to a new file every day at midnight, local time.</p>
+
+<example>
+     CustomLog "|bin/rotatelogs /var/logs/logfile 5M" common
+</example>
+
+     <p>This configuration will rotate the logfile whenever it reaches
+     a size of 5 megabytes.</p>
+
+<example>
+     ErrorLog "|bin/rotatelogs /var/logs/errorlog.%Y-%m-%d-%H_%M_%S 5M"
+</example>
+     <p>This configuration will rotate the error logfile whenever it
+     reaches a size of 5 megabytes, and the suffix to the logfile name
+     will be created of the form
+     <code>errorlog.YYYY-mm-dd-HH_MM_SS</code>.</p>
+ 
+</section>
+
 <section id="portability"><title>Portability</title>
 
 <p>The following logfile format string substitutions should be