Bug 994127

This is already covered in the accompanying HTML documentation.

Does that preclude the feature from being covered in the man page?  If that is the case, perhaps the man page should be entirely replaced with a simple message that says "see the HTML documentation."

You must understand that, as an administrator, it's not convenient to be reading HTML docs on a server.  Especially if we have to go digging in them to find major software features.

Further, I would like to point out that there are much less useful features which are documented in the manual.  There's a fully working example for inserting log messages into a database.  Is this more or less common than enabling asynchronous writes?

Asynchronous writes are of interest to all but the smallest environments.  By contrast, I don't think many people are going to be sending their logs to a named pipe or database.

All that would be necessary is a single line saying "prefixing the file name with a - will cause writes to be asynchronous."

First of all: Yes, the man page is lacking quite a bit.

(In reply to John Koelndorfer from comment #3)
> Does that preclude the feature from being covered in the man page?  If that

Certainly not.

> is the case, perhaps the man page should be entirely replaced with a simple
> message that says "see the HTML documentation."

Surely there is some threshold to what amount of information is desirable to have in one place.

> You must understand that, as an administrator, it's not convenient to be
> reading HTML docs on a server.  Especially if we have to go digging in them
> to find major software features.

I agree that the man pages are the traditional way of providing documentation on the command line. But I would argue that elinks is not that much worse. There might be people arguing that info(1) is the only one true way.

> Further, I would like to point out that there are much less useful features
> which are documented in the manual.  There's a fully working example for
> inserting log messages into a database.  Is this more or less common than
> enabling asynchronous writes?

The problem in this case is that the upstream has chosen to use the html files as the primary source of documentation and the man page is getting rusty.

> Asynchronous writes are of interest to all but the smallest environments. 
> By contrast, I don't think many people are going to be sending their logs to
> a named pipe or database.
>
> All that would be necessary is a single line saying "prefixing the file name
> with a - will cause writes to be asynchronous."

It would be necessary to periodically check the man page for differences to the latest docs, otherwise sooner of later 
somebody comes along complaining their favorite feature is not included.

I'll get to updating the man page, eventually, but that is a low priority item, which is hopefully understandable.
In the meantime, upstream happily accepts suggestions for improvements.

This request was not resolved in time for the current release.
Red Hat invites you to ask your support representative to
propose this request, if still desired, for consideration in
the next release of Red Hat Enterprise Linux.

Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

http://rhn.redhat.com/errata/RHEA-2014-1540.html