generated rotatelogs docs

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

2 files changed, 83 insertions, 56 deletions

diff --git a/docs/man/rotatelogs.8 b/docs/man/rotatelogs.8
index a8875f751f..8ce61467aa 100644
--- a/docs/man/rotatelogs.8
+++ b/docs/man/rotatelogs.8
@@ -19,7 +19,7 @@
 .el .ne 3
 .IP "\\$1" \\$2
 ..
-.TH "ROTATELOGS" 8 "2004-06-20" "Apache HTTP Server" "rotatelogs"
+.TH "ROTATELOGS" 8 "2007-11-20" "Apache HTTP Server" "rotatelogs"
 
 .SH NAME
 rotatelogs \- Piped logging program to rotate Apache logs
@@ -27,13 +27,35 @@ rotatelogs \- Piped logging program to rotate Apache logs
 .SH "SYNOPSIS"
  
 .PP
-\fBrotatelogs\fR [ -\fBl\fR ] \fIlogfile\fR [ \fIrotationtime\fR [ \fIoffset\fR ]] | [ \fIfilesize\fRM ]
+\fBrotatelogs\fR [ -\fBl\fR ] \fIlogfile\fR \fIrotationtime\fR|\fIfilesize\fRM [ \fIoffset\fR ]
  
 
 .SH "SUMMARY"
  
 .PP
-rotatelogs is a simple program for use in conjunction with Apache's piped logfile feature\&. For example:
+rotatelogs is a simple program for use in conjunction with Apache's piped logfile feature\&.
+ 
+
+.SH "OPTIONS"
+ 
+ 
+.TP
+-l
+Causes the use of local time rather than GMT as the base for the interval or for strftime(3) formatting with size-based rotation\&. Note that using -l in an environment which changes the GMT offset (such as for BST or DST) can lead to unpredictable results!  
+.TP
+\fIlogfile\fR
+The path plus basename of the logfile\&. If \fIlogfile\fR includes any '%' characters, it is treated as a format string for strftime(3)\&. Otherwise, the suffix \fI\&.nnnnnnnnnn\fR is automatically added and is the time in seconds\&. Both formats compute the start time from the beginning of the current period\&.  
+.TP
+\fIrotationtime\fR
+The time between log file rotations in seconds\&.  
+.TP
+\fIoffset\fR
+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 -300 for this argument\&. In most cases, -l should be used instead of specifying an offset\&.  
+.TP
+\fIfilesize\fRM
+The maximum file size in megabytes followed by the letter M to specify size rather than time\&. Use this parameter in place of rotationtime\&.  
+ 
+.SH "EXAMPLES"
  
 .nf
 
@@ -46,6 +68,15 @@ This creates the files /var/logs/logfile\&.nnnn where nnnn is the system time at
  
 .nf
 
+     CustomLog "|bin/rotatelogs -l /var/logs/logfile\&.%Y\&.%m\&.%d 86400" common
+
+.fi
+ 
+.PP
+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\&.
+ 
+.nf
+
      CustomLog "|bin/rotatelogs /var/logs/logfile 5M" common
 
 .fi
@@ -62,26 +93,6 @@ This configuration will rotate the logfile whenever it reaches a size of 5 megab
 .PP
 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 errorlog\&.YYYY-mm-dd-HH_MM_SS\&.
  
-
-.SH "OPTIONS"
- 
- 
-.TP
--l
-Causes the use of local time rather than GMT as the base for the interval\&. Note that using -l in an environment which changes the GMT offset (such as for BST or DST) can lead to unpredictable results!  
-.TP
-\fIlogfile\fR
-The path plus basename of the logfile\&. If \fIlogfile\fR includes any '%' characters, it is treated as a format string for strftime(3)\&. Otherwise, the suffix \fI\&.nnnnnnnnnn\fR is automatically added and is the time in seconds\&. Both formats compute the start time from the beginning of the current period\&.  
-.TP
-\fIrotationtime\fR
-The time between log file rotations in seconds\&.  
-.TP
-\fIoffset\fR
-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 -300 for this argument\&.  
-.TP
-\fIfilesize\fRM
-The maximum file size in megabytes followed by the letter M to specify size rather than time\&. Use this parameter in place of both rotationtime and offset\&.  
- 
 .SH "PORTABILITY"
  
 .PP
diff --git a/docs/manual/programs/rotatelogs.html.en b/docs/manual/programs/rotatelogs.html.en
index bb657dd80c..64e0ab1bf4 100644
--- a/docs/manual/programs/rotatelogs.html.en
+++ b/docs/manual/programs/rotatelogs.html.en
@@ -23,36 +23,11 @@
 </div>
 
      <p><code>rotatelogs</code> is a simple program for use in
-     conjunction with Apache's piped logfile feature.  For example:</p>
-
-<div class="example"><p><code>
-     CustomLog "|bin/rotatelogs /var/logs/logfile 86400" common
-</code></p></div>
-	 
-     <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>
-
-<div class="example"><p><code>
-     CustomLog "|bin/rotatelogs /var/logs/logfile 5M" common
-</code></p></div>
-
-     <p>This configuration will rotate the logfile whenever it reaches
-     a size of 5 megabytes.</p>
-
-<div class="example"><p><code>
-     ErrorLog "|bin/rotatelogs /var/logs/errorlog.%Y-%m-%d-%H_%M_%S 5M"
-</code></p></div>
-     <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>
 </div>
 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#synopsis">Synopsis</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#options">Options</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#portability">Portability</a></li>
 </ul></div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
@@ -62,8 +37,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>
 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
 <h2><a name="options" id="options">Options</a></h2>
@@ -72,8 +47,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>
 
@@ -92,16 +69,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>
 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
+<h2><a name="examples" id="examples">Examples</a></h2>
+
+<div class="example"><p><code>
+     CustomLog "|bin/rotatelogs /var/logs/logfile 86400" common
+</code></p></div>
+	 
+     <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>
+
+<div class="example"><p><code>
+     CustomLog "|bin/rotatelogs -l /var/logs/logfile.%Y.%m.%d 86400" common
+</code></p></div>
+	 
+     <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>
+
+<div class="example"><p><code>
+     CustomLog "|bin/rotatelogs /var/logs/logfile 5M" common
+</code></p></div>
+
+     <p>This configuration will rotate the logfile whenever it reaches
+     a size of 5 megabytes.</p>
+
+<div class="example"><p><code>
+     ErrorLog "|bin/rotatelogs /var/logs/errorlog.%Y-%m-%d-%H_%M_%S 5M"
+</code></p></div>
+     <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>
+ 
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
 <h2><a name="portability" id="portability">Portability</a></h2>
 
 <p>The following logfile format string substitutions should be