1007126 - various flaws in the man pages

Status: RESOLVED FIXED

(NSS :: Documentation, defect)

Description

[Elio Maldonado]

As reported by Hubert Kario:

Hubert Kario 2014-04-28 12:29:51 EDT
certutil man page errors (I used :

description of "-d [prefix]directory" in "NSS recognizes the following prefixes" is confusing, it's not explicit if the prefix is "sql" or "sql:"

description of "-1 | --keyUsage" has: "digital signature", should be "digitalSignature". Also is this really a Netscape extension? AFAIK, that's a standard x.509 V3 extension and "-5 | --nsCertType" sets the Netscape specific extension.

Comment 26 Hubert Kario 2014-04-28 12:36:37 EDT

I used nss-tools-3.15.3-11.el6.x86_64

Comment 27 Hubert Kario 2014-04-28 12:45:11 EDT

more errors in certutil man page:
 -e argument is formatted as if it was an option for -d argument

 same for:
 -u and -t
 -6 and -5
 -7 and -6

Comment 28 Hubert Kario 2014-04-28 12:46:59 EDT

cmsutil man page errors (nss-tools-3.15.3-11.el6.x86_64):

the -D and -C options are not in alphabetic order


Comment 29 Hubert Kario 2014-04-28 12:54:58 EDT
crlutil man page errors (nss-tools-3.15.3-11.el6.x86_64):

 -G Option is specified twice (the second specification is before Arguments and has no description)

 Options and arguments are not in alphabetical order

Comment 30 Hubert Kario 2014-04-28 13:05:01 EDT

modutil man page

"other execute:       0001", the 0001 is formatted badly

"This line can be set added to the ~/.bashrc file to make the change permanent." should probably be "This line can be set added to the ~/.bashrc file to make the change permanent for the user."

Comment 31 Hubert Kario 2014-04-28 13:11:35 EDT

pk12util man page

synopsis gets formatted badly on narrow (80 column) terminal:

       pk12util [-i p12File [-h tokenname] [-v] [common-options]]
                [-l p12File [-h tokenname] [-r] [common-options]]
                [-o p12File -n certname [-c keyCipher] [-C certCipher] [-m|--key_len keyLen] [-n|--cert_key_len certKeyLen] [common-options]]
                [common-options are: [-d [sql:]directory] [-P dbprefix] [-k slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword]]

 Arguments are not in alphabetical order.

listing of "Symmetric CBC ciphers for PKCS#5 V2", "PKCS#12 PBE ciphers" and "PKCS#5 PBE ciphers" has badly formatted first item

Comment 32 Hubert Kario 2014-04-28 13:20:30 EDT

signtool man page:

 -G and -J options are in wrong position (not alphabetical order)

 -G references page 1241 (?!), also double reference to "Generating Test Object-Signing Certificates"

Comment 33 Hubert Kario 2014-04-28 13:22:20 EDT

signver man page:

 "This line can be set added to the ~/.bashrc file to make the change permanent." should be "This line can be set added to the ~/.bashrc file to make the change permanent for the user."

Comment 34 Hubert Kario 2014-04-28 13:27:16 EDT
ssltap man page:
options are not sorted alphabetically

Comment 1

[Elio Maldonado]

Regarding the poor formatting seen in certutil, it's due to the older version of the xmlto converter using on RHEL-6.6 as I pointed out on https://bugzilla.redhat.com/show_bug.cgi?id=606022#c3

Regarding pk12util - synopsis gets formatted badly on narrow (80 column) terminal:
This one is a hard one to fix because we are using xml docbook with with the xmlto converted to generate the nroff pages. I have investigated but don't think I can come with a clean solution for quite some time.

I'll attach a patch that addresses most of the issues pointed out next.

Comment 2

[Elio Maldonado]

Attachment: Adress most of the problems reported

Comment 3

[Elio Maldonado]

Attachment: Addresses the defects pointed out by hkario

applied downstream for rhel-6.6 and adapted to current upstream sources.

Comment 4

[Robert Relyea]

Comment on attachment 8427792 [details] [diff] [review]
Addresses the defects pointed out by hkario

Review of attachment 8427792 [details] [diff] [review]:
-----------------------------------------------------------------

r+

Comment 5

[Elio Maldonado]

Pushed https://hg.mozilla.org/projects/nss/rev/6354c19569c7