This bug appears to have been reported against 'rawhide' during the Fedora 14 development cycle.
Changing version to '14'.

More information and reason for this action is here:
http://fedoraproject.org/wiki/BugZappers/HouseKeeping

This package has changed ownership in the Fedora Package Database.  Reassigning to the new owner of this component.

The work on the man pages is in progress and we have a temporary git repo for it.
To check out: git clone git://fedorapeople.org/~emaldonado/manpagesnss.git
To build a specific manpage: xmlto man tool-name.xml
To build an HTML page: man2html tool-name.1 > tool-name.html
To build all the manpages: make all

If you haven't done so, install the xmlto package.

Created attachment 452421 [details]
certutil man output as a text file

The Makefile requires Fedora-13 or better or RHEL-6.
See https://developer.mozilla.org/en/NSS_reference/NSS_tools 
for a text capture of most of the manpages output.

Created attachment 454705 [details]
certutil man output as text

Replaced copyright section with a license section as per feedback.

Comment on attachment 454705 [details]
certutil man output as text

Clearly this is just the first pass, so the r- shouldn't be a surprise. Here are my comments:

I'm keeping my comments to things that clear up the text. I've listed everything as problem and suggested solution, so that other possible solutions can be proposed rather than mine.

General comment... there appears to be some non-printing special characters in the text version.
The utility talks about managing certificate and key databases, but then talks about usage with tokens. We should probably be upfront that the tools manages certs and keys in both NSS databases and other NSS tokens (such as smart cards).

--------------------------------------------------------------------

Paragraph 1: 

Problem. You say that the utility is to 'create and modify' certificates, then you say it's also to  'list, generate, modify...'. This is a bit confusing that it creates and modifies and it also modifies. I think a careful reading says it creates and modifies databases and it also modifies certificates, which is a little less redundant.

Suggested solution. I think if you change 'also' to 'specifically'.

"The Certificate Database tool, certutil, is a command-line utility that
can create and modify certificate and key databases. It can specifically
list, generate, modify, or delete certificates..."

-----------------------------------------------------------------------

Paragraph 2:

Problem: "The key and certificate management process generally begins with creating keys in the key database."

This isn't quite correct. Certificate issuance begins here, but certificate management could begin at importing certs and keys.

Possible solution. Simply change "key and certificate management process" to "certificate issuance process". It's a little clunky because certificate issuance comes out of the blue, but at least it's now correct. (maybe a note about certificate issuance as part of the certificate management process would fix the "out of the blue" issue?).

-----------------------------------------------------------------------

Paragraph 3:

Problem 1: There is a little bit of confusion here, particularly when taken together with the argument portion. These options are called:
 
      options
      command options
      certificate operations
      actions.

Later arguments are sometimes called 'options'. We should be consistant. Users, in general, would expect arguments and options to be synonymous, so I suggest calling them command options.

Problem 2: "Run the command option and -H to see the arguements available for each command option." This sounds like certutil will list out the arguments for just the given command when combined with -H. This is not the case. -H always lists all the options.

Problem 3: Not all command options are "uppercase". Specifically --merge, --update-merge. Not all upper case single letter options are command options (-X and -P are arguments).

Solutions: Make paragraph 3 read:

"Command Options and Arguments

Runing certutil always requires one and only one command option to specify the type of certificate operations. Each command option may take zero or more arguments. The command option -H will list all the command options and their relevant arguments.

Command Options

Command options are typically upper case."

Other wordings are possible. BTW I think the mapping of valid argument options should also appear in the man page, not just the -H command. Fix up the other occurances of options, making sure the really refer to command options.

----------------------------------------------------------------------

Options -F:

Problem: Litronic no longer exists, we probably should drop references to the smart card.
Solution: Delete the (for example, the Litronic card).

Options -G:

Same command as -F about Litronic

Option --merge

Problem: "This is used to merge legacy NSS databases (cert8.db and key3.db) into the newer SQLite databases (cert9.db key4.db)."
This statement is only partially correct and a little misleading. The --merge command option is to merge two databases irrespective of type (you can merge old databases into new databases, new databases into old, a new database into another new database, an old into an old, even a database into a token). It's purpose is to merge two updated (new)databases into a single database.

Option --update-merge

This statement here is OK. The --update-merge command option only works from old to new.

----------------------------------------------------------------

"Option arguements modify an action and are lower case"

Problem 1: This is only only place we call them options arguments.
Problem 2: Some arguments are numbers or symbols.

Suggested Solution: "Arguments modify a command option and are usually lower case, numbers, or symbols.


Argument -d:
Problem: "[sql:]directory"

The sql: isn't the only valid prefix. NSS recognizes the following prefixes:

rdb:
sql:
dbm:
extern:

The rdb: is deprecated, so you can skip it. extern: is reserved for future use. dbm: explicitly requests the older database. sql: explicitly requests the newer database. If no database reqester has been specified, The default type is retrieved from NSS_DEFAULT_DB_TYPE. If NSS_DEFAULT_DB_TYPE is not set then dbm: is the default. We should at least document both sql: and dbm:

NOTE: related is the line "If the prefix sql: is not used, then the tool assumes the given databases are the old format" is incorrect, per the above description.


Argument -h

Problem: The whole discussion about internal slot numbers is only partially right, and probably irrelevant. (The FIPS token will have only one slot). Best to simply say that 'internal' is the internal database slot and be done with it.

Argument -k

Problem: It seems like the two separate -k options should probably be merged. We should also specify where one finds a key id (there are lots of key id's in our system, so we need to be more specific than just 'id').

Argument -m

Question: Is it still true that the default serial number is '0'? I thought we fixed that. Please check.

Argument: -P (note this is upper case).

Problem: "This option is provided as a special case." Should be 'This argument' and should be more specific.

Suggestion solution:"This argument is provided to support legacy servers. Most apps do not use a database prefix."


Argument: -q

Problem: we should include the current curve list in the man page.

Argument: -t

Problem: A number of options here are deprecated and are noops (-w, for instance), or are effectively read only (-u, which means 'user', That bit is now set whenever a matching key is found for a certificate, and can't be explicitly set by the user). Also the descriptions of T and C are wrong. "C" is Trusted CA (implies c). "T" is Trusted CA for client auth (ssl server only). T should not appear in any position except the SSL position on any example.

Argument: -v

Problem: I think this description is wrong. Please verify.

Arguments: -1 -2 -3 -4 -5 -6 and maybe some of the --ext options may cause certutil to prompt for more information. We should specify that this is the case and specify what certutil will prompt for.

--------------------------------------------------

Examples: 

Problems: Many... Please try each of these examples. Many of them won't work on RH (like the examples that use ECC). Some will generate prompts, but the examples don't say the will. Finally there are a lot of improper uses of the -t flag which should be cleaned up.

In the text version, the actual command indents in, which is confusing because it looks like a new heading when it's not.

I'll review the remaining examples, once "verified to work" versions have been  included

----------------------------------------------------------------

Remainder:

IRC: do we really want dogtag-pki to the the irc channel?

Authors: should we include Mozilla, Google, and Oracle?

This bug appears to have been reported against 'rawhide' during the Fedora 19 development cycle.
Changing version to '19'.

(As we did not run this process for some time, it could affect also pre-Fedora 19 development
cycle bugs. We are very sorry. It will help us with cleanup during Fedora 19 End Of Life. Thank you.)

More information and reason for this action is here:
https://fedoraproject.org/wiki/BugZappers/HouseKeeping/Fedora19

nss-softokn-3.15-3.fc19, nss-util-3.15-1.fc19, nss-3.15-5.fc19, nspr-4.10-2.fc19 has been submitted as an update for Fedora 19.
https://admin.fedoraproject.org/updates/FEDORA-2013-11174/nss-3.15-5.fc19,nss-softokn-3.15-3.fc19,nss-util-3.15-1.fc19,nspr-4.10-2.fc19

Package nss-softokn-3.15-3.fc19, nss-util-3.15-1.fc19, nss-3.15-5.fc19, nspr-4.10-2.fc19:
* should fix your issue,
* was pushed to the Fedora 19 testing repository,
* should be available at your local mirror within two days.
Update it with:
# su -c 'yum update --enablerepo=updates-testing nss-softokn-3.15-3.fc19 nss-util-3.15-1.fc19 nss-3.15-5.fc19 nspr-4.10-2.fc19'
as soon as you are able to.
Please go to the following url:
https://admin.fedoraproject.org/updates/FEDORA-2013-11174/nss-3.15-5.fc19,nss-softokn-3.15-3.fc19,nss-util-3.15-1.fc19,nspr-4.10-2.fc19
then log in and leave karma (feedback).

nss-softokn-3.15-3.fc19, nss-util-3.15-1.fc19, nss-3.15-5.fc19, nspr-4.10-2.fc19 has been pushed to the Fedora 19 stable repository.  If problems still persist, please make note of it in this bug report.

nss-3.15.1-1.fc19,nss-softokn-3.15.1-1.fc19 has been submitted as an update for Fedora 19.
https://admin.fedoraproject.org/updates/nss-3.15.1-1.fc19,nss-softokn-3.15.1-1.fc19

nss-3.15.1-1.fc19, nss-softokn-3.15.1-1.fc19, nss-util-3.15.1-1.fc19 has been pushed to the Fedora 19 stable repository.  If problems still persist, please make note of it in this bug report.

nss-util-3.15.1-1.fc18,nss-softokn-3.15.1-1.fc18,nss-3.15.1-1.fc18 has been submitted as an update for Fedora 18.
https://admin.fedoraproject.org/updates/nss-util-3.15.1-1.fc18,nss-softokn-3.15.1-1.fc18,nss-3.15.1-1.fc18

nss-util-3.15.1-1.fc18, nss-softokn-3.15.1-1.fc18, nss-3.15.1-1.fc18 has been pushed to the Fedora 18 stable repository.  If problems still persist, please make note of it in this bug report.