Bug 736772 - RFE: authconfig man page is incomplete
RFE: authconfig man page is incomplete
Status: CLOSED WONTFIX
Product: Fedora
Classification: Fedora
Component: authconfig (Show other bugs)
15
Unspecified Unspecified
unspecified Severity low
: ---
: ---
Assigned To: Tomas Mraz
Fedora Extras Quality Assurance
:
Depends On: 698374
Blocks:
  Show dependency treegraph
 
Reported: 2011-09-08 12:14 EDT by Andrew McNabb
Modified: 2012-08-07 15:07 EDT (History)
1 user (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: 698374
Environment:
Last Closed: 2012-08-07 15:07:36 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)
patch adding an OPTIONS section to the man page (8.71 KB, patch)
2011-09-08 13:47 EDT, Andrew McNabb
no flags Details | Diff
runs /usr/sbin/authconfig.py and converts its output to the man page format (666 bytes, text/plain)
2011-09-08 13:48 EDT, Andrew McNabb
no flags Details

  None (edit)
Description Andrew McNabb 2011-09-08 12:14:30 EDT
The authconfig man page states:

"The list of options mentioned here in the manual page is not exhaustive,  please refer to authconfig --help for the complete list of the options."

The documentation would be much more helpful if it were complete and had a standard "OPTIONS" section as seems to be standard practice.

+++ This bug was initially created as a clone of Bug #698374 +++

The authconfig man page does not have any information about the --enablemkhomedir option.

--- Additional comment from tmraz@redhat.com on 2011-09-08 04:30:22 EDT ---

It is described in the authconfig --help output. The man page clearly states that it does not describe all the options of authconfig.
Comment 1 Tomas Mraz 2011-09-08 13:02:34 EDT
I will apply patches that improve the manual page if you provide them.
Comment 2 Andrew McNabb 2011-09-08 13:47:58 EDT
Created attachment 522173 [details]
patch adding an OPTIONS section to the man page

I am attaching a patch that adds an OPTIONS section to the man page.  The text comes from the output of `/usr/sbin/authconfig --help`.  I will also attach a simple script that I used to create this in case any changes need to be made.
Comment 3 Andrew McNabb 2011-09-08 13:48:56 EDT
Created attachment 522174 [details]
runs /usr/sbin/authconfig.py and converts its output to the man page format
Comment 4 Tomas Mraz 2011-09-08 15:58:13 EDT
I hoped for some value-added documentation. What's the point of duplicating exactly the same information at two places with the additional need to keep the two places in sync?
Comment 5 Andrew McNabb 2011-09-08 16:40:15 EDT
This is a starting point, and I can think of a number of reasons that this is an improvement:

1) Man pages get mirrored online, so they show up in searches.

2) All of the documentation is in one place (specific options can be read alongside the rest of the man page).

3) It gives a place to add more extensive information for each option in an organized way.

4) A lot of the information in the DESCRIPTION section can be moved down into the OPTIONS section.

Anyway, value-added information can't be added for each option until there's at least a structure in place for it.  The OPTIONS section is the standard way to do that.
Comment 6 Fedora End Of Life 2012-08-07 15:07:38 EDT
This message is a notice that Fedora 15 is now at end of life. Fedora
has stopped maintaining and issuing updates for Fedora 15. It is
Fedora's policy to close all bug reports from releases that are no
longer maintained. At this time, all open bugs with a Fedora 'version'
of '15' have been closed as WONTFIX.

(Please note: Our normal process is to give advanced warning of this
occurring, but we forgot to do that. A thousand apologies.)

Package Maintainer: If you wish for this bug to remain open because you
plan to fix it in a currently maintained version, feel free to reopen
this bug and simply change the 'version' to a later Fedora version.

Bug Reporter: Thank you for reporting this issue and we are sorry that
we were unable to fix it before Fedora 15 reached end of life. If you
would still like to see this bug fixed and are able to reproduce it
against a later version of Fedora, you are encouraged to click on
"Clone This Bug" (top right of this page) and open it against that
version of Fedora.

Although we aim to fix as many bugs as possible during every release's
lifetime, sometimes those efforts are overtaken by events. Often a
more recent Fedora release includes newer upstream software that fixes
bugs or makes them obsolete.

The process we are following is described here:
http://fedoraproject.org/wiki/BugZappers/HouseKeeping

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