path: root/patches/logrotate-3.7.1/manpage.patch

Closes: #101272, #335060
Patches from: J S Bygott <jsb_no_spm@jsbygott.fsnet.co.uk>

General fixes to manpages.


---
 logrotate.8 |  151 +++++++++++++++++++++++++++++++++---------------------------
 1 file changed, 84 insertions(+), 67 deletions(-)

Index: logrotate-3.7.1/logrotate.8
===================================================================
--- logrotate-3.7.1.orig/logrotate.8
+++ logrotate-3.7.1/logrotate.8
@@ -3,7 +3,8 @@
 .SH NAME
 logrotate \- rotates, compresses, and mails system logs
 .SH SYNOPSIS
-\fBlogrotate\fR [-dv] [-f|--force] [-s|--state \fIfile\fR] \fIconfig_file\fR+
+\fBlogrotate\fR [\fB\-dv\fR] [\fB\-f\fR|\fB\-\-force\fR]
+[\fB\-s\fR|\fB-\-state\ \fIstatefile\fR] \fIconfig_file\fR ..
 .SH DESCRIPTION
 \fBlogrotate\fR is designed to ease administration of systems that generate
 large numbers of log files.  It allows automatic rotation, compression, 
@@ -11,16 +12,16 @@ removal, and mailing of log files.  Each
 weekly, monthly, or when it grows too large.
 .P
 Normally, \fBlogrotate\fR is run as a daily cron job.  It will not modify
-a log multiple times in one day unless the criterium for that log is
-based on the log's size and \fBlogrotate\fR is being run multiple times
-each day, or unless the \fB-f\fR or \fB-force\fR option is used. 
+a log more than once in one day unless the criterion for that log is
+based on the log's size and \fBlogrotate\fR is being run more than once
+each day, or unless the \fB-f\fR or \fB-\-force\fR option is used. 
 .P
 Any number of config files may be given on the command line. Later config
 files may override the options given in earlier files, so the order
-in which the \fBlogrotate\fR config files are listed in is important.
+in which the \fBlogrotate\fR config files are listed is important.
 Normally, a single config file which includes any other config files
 which are needed should be used.  See below for more information on how
-to use the \fIinclude\fR directive to accomplish this.  If a directory
+to use the \fBinclude\fR directive to accomplish this.  If a directory
 is given on the command line, every file in that directory is used as
 a config file.
 .P
@@ -36,37 +37,42 @@ Turns on debug mode and implies \fB-v\fR
 be made to the logs or to the \fBlogrotate\fR state file.
 
 .TP
-\fB-f, -\-force\fR
+\fB-f\fR, \fB-\-force\fR
 Tells \fBlogrotate\fR to force the rotation, even if it doesn't think
 this is necessary.  Sometimes this is useful after adding new entries to
-\fBlogrotate\fR, or if old log files have been removed by hand, as the
-new files will be created, and logging will continue correctly.
+a \fBlogrotate\fR config file, or if old log files have been removed
+by hand, as the new files will be created, and logging will continue
+correctly.
 
 .TP
-\fB-m, -\-mail <command>\fR
+\fB-m\R, \B-\-mail <command>\fR
 Tells \fBlogrotate\fR which command to use when mailing logs. This
 command should accept two arguments: 1) the subject of the message, and
 2) the recipient. The command must then read a message on standard input
-and mail it to the recipient. The default mail command is \fB/bin/mail
+and mail it to the recipient. The default mail command is \fB/usr/bin/mail
 -s\fR.
 
 .TP
-\fB-s, -\-state <statefile>\fR
+\fB-s\fR, \fB-\-state <statefile>\fR
 Tells \fBlogrotate\fR to use an alternate state file.  This is useful
-if logrotate is being run as a different user for various sets of
+if \fBlogrotate\fR is being run as a different user for various sets of
 log files.  The default state file is \fI/var/lib/logrotate/status\fR.
 
 .TP
 \fB-\-usage\fR
 Prints a short usage message.
 
+.TP
+\fB-v\fR, \fB--verbose\fR
+Display messages during rotation.
+
 .SH CONFIGURATION FILE
 
 \fBlogrotate\fR reads everything about the log files it should be handling
 from the series of configuration files specified on the command line.  Each
 configuration file can set global options (local definitions override
 global ones, and later definitions override earlier ones) and specify
-a logfile to rotate. A simple configuration file looks like this:
+some logfiles to rotate. A simple configuration file looks like this:
 
 .nf
 .ta +3i
@@ -77,7 +83,7 @@ compress
     rotate 5
     weekly
     postrotate
-	/sbin/killall -HUP syslogd
+        /sbin/killall -HUP syslogd
     endscript
 }
 
@@ -87,7 +93,7 @@ compress
     size=100k
     sharedscripts
     postrotate
-	/sbin/killall -HUP httpd
+        /sbin/killall -HUP httpd
     endscript
 }
 
@@ -97,7 +103,7 @@ compress
     olddir /var/log/news/old
     missingok
     postrotate
-	kill -HUP `cat /var/run/inn.pid`
+        kill -HUP `cat /var/run/inn.pid`
     endscript
     nocompress
 }
@@ -107,9 +113,9 @@ compress
 The first few lines set global options; in the example, logs are
 compressed after they are rotated.  Note that comments may appear
 anywhere in the config file as long as the first non-whitespace
-character on the line is a #.
+character on the line is a \fB#\fR.
 
-The next section of the config files defined how to handle the log file
+The next section of the config file defines how to handle the log file
 \fI/var/log/messages\fR. The log will go through five weekly rotations before
 being removed. After the log file has been rotated (but before the old
 version of the log has been compressed), the command 
@@ -117,13 +123,13 @@ version of the log has been compressed),
 
 The next section defines the parameters for both
 \fI/var/log/httpd/access.log\fR and \fI/var/log/httpd/error.log\fR.
-They are rotated whenever is grows over 100k is size, and the old logs
+Each is rotated whenever it grows over 100k in size, and the old log
 files are mailed (uncompressed) to www@my.org after going through 5
 rotations, rather then being removed. The \fBsharedscripts\fR means that
 the \fBpostrotate\fR script will only be run once, not once for each
-log which is rotated. Note that the double quotes around the first filename
-at the beginning of this section allows logrotate to rotate logs with
-spaces in the name. Normal shell quoting rules apply, with ', ", and \\
+log which is rotated. Note that log file names may be enclosed in
+quotes (and that quotes are required if the name contains spaces).
+Normal shell quoting rules apply, with \fB'\fR, \fB"\fR, and \fB\\\fR
 characters supported.
 
 The last section defines the parameters for all of the files in
@@ -135,29 +141,33 @@ Please use wildcards with caution.  If y
 rotate all files, including previously rotated ones.  A way around this
 is to use the \fBolddir\fR directive or a more exact wildcard (such as *.log).
 
+If the directory \fI/var/log/news\fR does not exist, this will cause 
+\fBlogrotate\fR to report an error. This error cannot be stopped with
+the \fBmissingok\fR directive.
+
 Here is more information on the directives which may be included in
 a \fBlogrotate\fR configuration file:
 
 .TP
 \fBcompress\fR
-Old versions of log files are compressed with \fBgzip\fR by default. See also
-\fBnocompress\fR. 
+Old versions of log files are compressed with \fBgzip\fR(1) by default.
+See also \fBnocompress\fR. 
 
 .TP
 \fBcompresscmd\fR
 Specifies which command to use to compress log files.  The default is
-\fBgzip\fR.  See also \fBcompress\fR.
+\fBgzip\fR(1).  See also \fBcompress\fR.
 
 .TP
 \fBuncompresscmd\fR
 Specifies which command to use to uncompress log files.  The default is
-\fBgunzip\fR.
+\fBgunzip\fR(1).
 
 .TP
 \fBcompressext\fR
 Specifies which extension to use on compressed logfiles, if compression
-is enabled.  The default follows that of the configured compression
-command.
+is enabled.  The default follows that of the default compression
+command (.gz).
 
 .TP
 \fBcompressoptions\fR
@@ -174,9 +184,9 @@ as the old log file stays in place.
 
 .TP
 \fBcopytruncate\fR
-Truncate the original log file in place after creating a copy,
-instead of moving the old log file and optionally creating a new one,
-It can be used when some program can not be told to close its logfile
+Truncate the original log file to zero size in place after creating a copy,
+instead of moving the old log file and optionally creating a new one.
+It can be used when some program cannot be told to close its logfile
 and thus might continue writing (appending) to the previous log file forever.
 Note that there is a very small time slice between copying the file and
 truncating it, so some logging data might be lost.
@@ -188,7 +198,7 @@ as the old log file stays in place.
 Immediately after rotation (before the \fBpostrotate\fR script is run)
 the log file is created (with the same name as the log file just rotated).
 \fImode\fR specifies the mode for the log file in octal (the same
-as \fBchmod(2)\fR), \fIowner\fR specifies the user name who will own the
+as \fBchmod\fR(2)), \fIowner\fR specifies the user name who will own the
 log file, and \fIgroup\fR specifies the group the log file will belong
 to. Any of the log file attributes may be omitted, in which case those
 attributes for the new file will use the same values as the original log
@@ -207,20 +217,20 @@ instead of simply adding a number.
 .TP
 \fBdelaycompress\fR
 Postpone compression of the previous log file to the next rotation cycle.
-This has only effect when used in combination with \fBcompress\fR.
-It can be used when some program can not be told to close its logfile
+This only has effect when used in combination with \fBcompress\fR.
+It can be used when some program cannot be told to close its logfile
 and thus might continue writing to the previous log file for some time.
 
 .TP
 \fBextension \fIext\fR
 Log files are given the final extension \fIext\fR after rotation. If 
-compression is used, the compression extension (normally \fB.gz\fR)
+compression is used, the compression extension (normally \fI.gz\fR)
 appears after \fIext\fR.
 
 .TP
 \fBifempty\fR
-Rotate the log file even if it is empty, overiding the \fBnotifempty\fR
-option (ifempty is the default).
+Rotate the log file even if it is empty, overriding the \fBnotifempty\fR
+option (\fBifempty\fR is the default).
 
 .TP
 \fBinclude \fIfile_or_directory\fR
@@ -231,12 +241,12 @@ before processing of the including file 
 which are ignored are files which are not regular files (such as
 directories and named pipes) and files whose names end with one of
 the taboo extensions, as specified by the \fBtabooext\fR directive.
-The \fBinclude\fR directive may not appear inside of a log file
+The \fBinclude\fR directive may not appear inside a log file
 definition.
 
 .TP
 \fBmail \fIaddress\fR
-When a log is rotated out-of-existence, it is mailed to \fIaddress\fR. If
+When a log is rotated out of existence, it is mailed to \fIaddress\fR. If
 no mail should be generated by a particular log, the \fBnomail\fR directive
 may be used.
 
@@ -268,8 +278,7 @@ Log files are rotated the first time \fB
 
 .TP
 \fBnocompress\fR
-Old versions of log files are not compressed with \fBgzip\fR. See also
-\fBcompress\fR. 
+Old versions of log files are not compressed. See also \fBcompress\fR. 
 
 .TP
 \fBnocopy\fR
@@ -292,7 +301,7 @@ Do not postpone compression of the previ
 
 .TP
 \fBnomail\fR
-Don't mail old log files to any address.
+Do not mail old log files to any address.
 
 .TP
 \fBnomissingok\fR
@@ -300,12 +309,12 @@ If a log file does not exist, issue an e
 
 .TP
 \fBnoolddir\fR
-Logs are rotated in the same directory the log normally resides in (this 
+Logs are rotated in the directory they normally reside in (this 
 overrides the \fBolddir\fR option).
 
 .TP
 \fBnosharedscripts\fR
-Run \fBprerotate\fR and \fBpostrotate\fR scripts for every script which
+Run \fBprerotate\fR and \fBpostrotate\fR scripts for every log which
 is rotated (this is the default, and overrides the \fBsharedscripts\fR
 option).
 
@@ -326,16 +335,15 @@ overriden by the \fBnoolddir\fR option.
 \fBpostrotate\fR/\fBendscript\fR
 The lines between \fBpostrotate\fR and \fBendscript\fR (both of which
 must appear on lines by themselves) are executed after the log file is
-rotated. These directives may only appear inside of a log file definition.
-See \fBprerotate\fR as well.
+rotated. These directives may only appear inside a log file definition.
+See also \fBprerotate\fR.
 
 .TP
 \fBprerotate\fR/\fBendscript\fR
 The lines between \fBprerotate\fR and \fBendscript\fR (both of which
 must appear on lines by themselves) are executed before the log file is
 rotated and only if the log will actually be rotated. These directives
-may only appear inside of a log file definition.  See \fBpostrotate\fR
-as well.
+may only appear inside a log file definition.  See also \fBpostrotate\fR.
 
 .TP
 \fBfirstaction\fR/\fBendscript\fR
@@ -351,33 +359,34 @@ The lines between \fBlastaction\fR and \
 must appear on lines by themselves) are executed once after all log
 files that match the wildcarded pattern are rotated, after postrotate script
 is run and only if at least one log is rotated. These directives may only
-appear inside of a log file definition. See \fBlastaction\fR as well.
+appear inside a log file definition. See also \fBlastaction\fR.
 
 .TP
 \fBrotate \fIcount\fR
-Log files are rotated <count> times before being removed or mailed to the
+Log files are rotated \fIcount\fR times before being removed or mailed to the
 address specified in a \fBmail\fR directive. If \fIcount\fR is 0, old versions
 are removed rather then rotated.
 
 .TP
-\fBsize \fIsize\fR
-Log files are rotated when they grow bigger then \fIsize\fR bytes. If
-\fIsize\fR is followed by \fIM\fR, the size if assumed to be in megabytes.
-If the \fIk\fR is used, the size is in kilobytes. So \fBsize 100\fR,
-\fIsize 100k\fR, and \fIsize 100M\fR are all valid.
-
-.TP
 \fBsharedscripts\fR
-Normally, \fBprescript\fR and \fBpostscript\fR scripts are run for each
+Normally, \fBprerotate\fR and \fBpostrotate\fR scripts are run for each
 log which is rotated, meaning that a single script may be run multiple
 times for log file entries which match multiple files (such as the 
-/var/log/news/* example). If \fBsharedscript\fR is specified, the scripts
+\fI/var/log/news/*\fR example). If \fBsharedscripts\fR is specified, the scripts
 are only run once, no matter how many logs match the wildcarded pattern.
 However, if none of the logs in the pattern require rotating, the scripts
-will not be run at all. This option overrides the \fbnosharedscripts\fR
+will not be run at all. This option overrides the \fBnosharedscripts\fR
 option.
 
 .TP
+\fBsize \fIsize\fR[\fBG\fR|\fBM\fR|\fBk\fR]
+Log files are rotated when they grow bigger then \fIsize\fR bytes. If
+\fIsize\fR is followed by \fIM\fR, the size if assumed to be in megabytes.
+If the \fIG\fR suffix is used, the size is in gigabytes.
+If the \fIk\fR suffix is used, the size is in kilobytes. So \fBsize 100\fR,
+\fIsize 100k\fR, \fIsize 100M\fR and \fIsize 1G\fR are all valid.
+
+.TP
 \fBstart \fIcount\fR
 This is the number to use as the base for rotation. For example, if
 you specify 0, the logs will be created with a .0 extension as they are
@@ -388,18 +397,21 @@ number of times specified with the \fBco
 .TP
 \fBtabooext\fR [+] \fIlist\fR
 The current taboo extension list is changed (see the \fBinclude\fR directive
-for information on the taboo extensions). If a + precedes the list of
-extensions, the current taboo extension list is augmented, otherwise it
+for information on the taboo extensions). If a \fB+\fR precedes \fIlist\fR,
+the current taboo extension list is augmented by \fIlist\fR, otherwise it
 is replaced. At startup, the taboo extension list 
-contains .rpmorig, .rpmsave, ,v, .swp, .rpmnew, and ~.
+contains .rpmorig, .rpmsave, .dpkg-dist, .dpkg-old, .dpkg-new, .disabled,
+,v, .swp, .rpmnew, and ~. The members of the list are separated by spaces,
+not commas.
+
 
 .TP
 \fBweekly\fR
 Log files are rotated if the current weekday is less then the weekday
 of the last rotation or if more then a week has passed since the last
 rotation. This is normally the same as rotating logs on the first day
-of the week, but it works better if \fIlogrotate\fR is not run every
-night.
+of the week, but if \fBlogrotate\fR is not being run every night a log 
+rotation will happen at the first valid opportunity.
 
 .SH FILES
 .PD 0
@@ -411,11 +423,16 @@ Default state file.
 Configuration options.
 
 .SH SEE ALSO
-.IR gzip (1)
+.BR gzip (1)
+
+.SH NOTES
+The \fBkillall\fR(1) program in Debian is found in the \fIpsmisc\fR package.
 
 .SH AUTHORS
 .nf
 Erik Troan <ewt@redhat.com>
 .nf
 Preston Brown <pbrown@redhat.com>
+.nf
+Corrections and changes for Debian by Paul Martin <pm@debian.org>
 .fi