This service will be undergoing maintenance at 20:00 UTC, 2017-04-03. It is expected to last about 30 minutes
Bug 185318 - logrotate's man page needs the `extension' option description to be corrected
logrotate's man page needs the `extension' option description to be corrected
Status: CLOSED ERRATA
Product: Red Hat Enterprise Linux 4
Classification: Red Hat
Component: logrotate (Show other bugs)
4.0
All Linux
medium Severity medium
: ---
: ---
Assigned To: Peter Vrabec
Jay Turner
:
Depends On:
Blocks: 189992
  Show dependency treegraph
 
Reported: 2006-03-13 13:05 EST by Jiri TRAVNICEK, alias JITR {temporarily not reading bugmail}
Modified: 2015-01-07 19:12 EST (History)
1 user (show)

See Also:
Fixed In Version: RHBA-2006-0696
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2006-10-11 15:09:51 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Jiri TRAVNICEK, alias JITR {temporarily not reading bugmail} 2006-03-13 13:05:57 EST
Description of problem:

The description of logrotate's `extension' option in man page `logrotate(8)'
doesn't well correspond with the real behaviour of the mentioned option.


Version-Release number of selected component (if applicable):

logrotate-3.7.1-5.RHEL4 (CentOS/RHEL 4.2)
logrotate-3.7.1-10.i386.rpm (FC 4)
logrotate-3.7.3-2.2.1.i386.rpm (FC devel)
...


How reproducible:

See the man page for `logrotate(8)'. ;-)


Steps to Reproduce:

1. run `man logrotate'
2. forward to `extension' option description
3. read it
4. try to use the option
5. see it doesn't work as expected
6. be depressed, again (regarding bug 97790, step 3.)

  
Actual results:

The description says:
   Log files are given the final extension ext after rotation.  If
   compression  is  used, the compression extension (normally .gz)
   appears after ext.


Expected results:

The descriptuion should describe the functionality clearly and unambiguously.
See bug 97790 and bug 171611 for the confusion it makes. The bug 171611, comment
#4 suggests a replacement text. The rationale in bug 97790, comment #1 explains
the real functionality including example. I think it's a Good Idea to include
the example in the man page.


Additional info:

The man page should describe program clearly. Unless you include an off-line
copy of Bugzilla database for further clatification. The references prove the
description is not good. The fact I had to search for info on this option proves
that, too.

The worst worst problem is, the current description seems to be clear and
unambiguous. It, however, doesn't correspond with the real functionality. So the
users are still confused as logrotate doesn't seem to do what they expect.

I don't know where to grab the latest version. Google searches seemed to yield a
"concurrent" project with the same name. I chose to get the version from
development version of Fedora Core, hoping to get the lastest available version
(see the version-release list above). The man page's description didn't change
since RHEL 2.1 and is still the same in the lastest version.
Comment 1 Peter Vrabec 2006-03-14 05:13:30 EST
Do u agree with this? I think it's clear enought.

extension ext
Log files with ext extension can keep it after the rotation.  If compression  is
  used,   the  compression  extension (normally .gz) appears after ext. For
example you have a logfile named mylog.foo and want to rotate it to
mylog.1.foo.gz instead of mylog.foo.1.gz.

I'm afraid I won't be able to fix this problem in RHEL-4, but I gonna do it for
devel, so it should appears in RHEL-5.
Comment 5 Jiri TRAVNICEK, alias JITR {temporarily not reading bugmail} 2006-04-08 21:19:47 EDT
(In reply to comment #1)

Hello, I apologize for taking such a long time to react. I'm in a huge delay
processing my personal e-mail. :-(

> Do u agree with this? I think it's clear enought.
> 
> {...}

Looks better than the current one, though I would rather explain it without
complicating things with compression extension issues. As late as things are
cleared out this way I'd mention the compession-related stuff. My proposal
follows (language and/or other bugfixes/modifications welcome, ;-) text in curly
brackets are comments and not a literal part of the proposal):

extension ext
Log files with ext extension can keep it after the rotation. This causes the
numeric extension to be added before the extension ext, not after it. {The last
sentence is optional.} For example you have a logfile named mylog.foo and want
to rotate it to mylog.1.foo instead of mylog.foo.1. If compression is used,
however, the compression extension (normally .gz) always appears after ext. For
example you have a logfile named mylog.foo it will rotate to mylog.1.foo.gz, not
to mylog.1.gz.foo (which quite certainly is a nonsense {This note is optional.}).

I guess it is clearly obvious what the proposal is inspired by. ;-) Do you think
this would be any better?
 
> I'm afraid I won't be able to fix this problem in RHEL-4, but I gonna do it for
> devel, so it should appears in RHEL-5.

No problemo. :-) A "documentation bug" doesn't affect program functionality once
located and systematically ignored by the system administrator. The point is to
make things better at least for the future.
Comment 6 Jiri TRAVNICEK, alias JITR {temporarily not reading bugmail} 2006-04-08 21:32:09 EDT
(In reply to comment #5)

To bugfix my own proposal -- I missed a word in the last sentence:

For example you have a logfile...

An `if' should be insrted:

For example, if you have a logfile...

And yes, there are probably commas missing several times, but my Czech grammar
ain't that perfect not to say about English.
Comment 11 Jiri TRAVNICEK, alias JITR {temporarily not reading bugmail} 2006-05-01 15:49:24 EDT
Peter, as I can see, you have already fixed the man page in RawHide. But it
seems you did it according to the proposition you stated in comment #1. Have you
later considered my version in comment #2 (including bugfix in comment #3)?
(Unfortunately I posted it quite late -- after you fixed this, according to the
timestamp of `logrotate-3.7.3/logrotate.8' in the `logrotate-3.7.3-3.src.rpm' SRPM.)
Comment 12 Peter Vrabec 2006-05-02 05:01:07 EDT
I think explanation of extension option in comment #1 is understandable. I'd like to fix it in 
RHEL-4 in same way. 
Comment 13 Jiri TRAVNICEK, alias JITR {temporarily not reading bugmail} 2006-05-04 16:53:38 EDT
Well, it seems a bit awkward to me, but I don't want to argue about this...
Perhaps it would be better if someome else commented on this?

I acknowledge your version is shorter, which is certainly a plus. But IMHO it's
more complicated than mine because you explain things with compression in mind.
This option doesn't necessarily have anything to do with compression and I'd
personally prefer the explanation to concentrate purely on this option
regardless of the compression issue. After this explanation the effect of
compression being used could optionally be discussed.

Well, this is my point of view, and I won't really argue about it. You've got
the last word and I'm not gonna say anything more on this subject (unless
explicitly asked).
Comment 20 Red Hat Bugzilla 2006-10-11 15:09:51 EDT
An advisory has been issued which should help the problem
described in this bug report. This report is therefore being
closed with a resolution of ERRATA. For more information
on the solution and/or where to find the updated files,
please follow the link below. You may reopen this bug report
if the solution does not work for you.

http://rhn.redhat.com/errata/RHBA-2006-0696.html

Note You need to log in before you can comment on or make changes to this bug.