This request was evaluated by Red Hat Product Management for inclusion in a Red
Hat Enterprise Linux major release.  Product Management has requested further
review of this request by Red Hat Engineering, for potential inclusion in a Red
Hat Enterprise Linux Major release.  This request is not yet committed for
inclusion.

The work on the man pages has begun and we have a temporary git repo for it.

L O C A T I O N S
--------------------
git repo (viewing): 
http://fedorapeople.org/gitweb?p=emaldonado/public_git/manpagesnss.git;a=summary

git repo (checking out): 
git clone git://fedorapeople.org/~emaldonado/manpagesnss.git

Q U I C K  S E T U P
-----------------------
1. Check out the man page repository. This can be done anonymously.
git clone git://fedorapeople.org/~emaldonado/manpagesnss.git

2. Build a manpage.
xmlto man tool-name.xml

3. Build an HTML page.
man2html tool-name.1 > tool-name.html

4. Build all the manpages
make all

Since RHEL 6.2 External Beta has begun, and this bug remains
unresolved, it has been rejected as it is not proposed as
exception or blocker.

Red Hat invites you to ask your support representative to
propose this request, if appropriate and relevant, in the
next release of Red Hat Enterprise Linux.

The man pages will ready in time for RHEL-6.5. The review of the man pages will now be done upstream https://bugzilla.mozilla.org/show_bug.cgi?id=835486

The former added the to the source tree with ability to build them but https://bugzilla.mozilla.org/show_bug.cgi?id=836477 is the review bug

*** Bug 980379 has been marked as a duplicate of this bug. ***

Created attachment 862576 [details]
man pages for the nss security tools

plus patch to certutil.xml to pick up an upstream bug fix from nss-3.15.4.

Comment on attachment 862576 [details]
man pages for the nss security tools

Let me split the nss.spec file changes and the patch as the latter doesn't show up.

Created attachment 862577 [details]
changes to the spec file in patch format

Created attachment 862578 [details]
certutil man page fix applied upstrean on nss-3.15.4

Comment on attachment 862577 [details]
changes to the spec file in patch format

Could you avoid the intermediary copying?
Instead of ...

+# and copy them here
+for m in "%{allTools}"; do 
+  cp ./nss/doc/nroff/${m}.1 .
+done
...
+# Copy the man pages for the nss tools
+for f in "%{allTools}"; do 
+   install -c -m 644 ${f}.1 $RPM_BUILD_ROOT%{_mandir}/man1/${f}.1
+done


... would it work to simply do (see the modified install line):

+# Copy the man pages for the nss tools
+for f in "%{allTools}"; do 
+   install -c -m 644 ./nss/doc/nroff/${f}.1 $RPM_BUILD_ROOT%{_mandir}/man1/${f}.1
+done


The patch looks ok to me. r=kaie
However, if you can simplify it in the proposed way, please do.

(In reply to Kai Engert (:kaie) from comment #21)
Thanks for the review.

> Comment on attachment 862577 [details]
> changes to the spec file in patch format
> 
> Could you avoid the intermediary copying?
> Instead of ...
> 
> +# and copy them here
> +for m in "%{allTools}"; do 
> +  cp ./nss/doc/nroff/${m}.1 .
> +done
> ...
> +# Copy the man pages for the nss tools
> +for f in "%{allTools}"; do 
> +   install -c -m 644 ${f}.1 $RPM_BUILD_ROOT%{_mandir}/man1/${f}.1
> +done
> 
> 
> ... would it work to simply do (see the modified install line):
> 
> +# Copy the man pages for the nss tools
> +for f in "%{allTools}"; do 
> +   install -c -m 644 ./nss/doc/nroff/${f}.1
> $RPM_BUILD_ROOT%{_mandir}/man1/${f}.1
> +done
> 
No, that wouldn't work because by the time the build reaches the %install phase the build directory has has been deleted. Rathther tahn copyong here, at the top, a tider way is

# and copy them to the dist directory for %%install to find them
%{__mkdir_p} ./dist/doc/nroff
%{__cp} ./nss/doc/nroff/* ./dist/doc/nroff

and at intstall we can have
# Copy the man pages for the nss tools
for f in "%{allTools}"; do 
   install -c -m 644 ./dist/doc/nroff/${m}.1 $RPM_BUILD_ROOT%{_mandir}/man1/${f}.1
done

Eventually, it should be the build/doc/Makefile that copies the man pages to the dist directory and I plan to submit such a patch upstream for you to review along with other improvements. For the time being doing it in the spec file is the simplest way.

Created attachment 892047 [details]
Adress some of flaws pointed out by Hubert

This partial fix to show some progress and get some feedback. 

--------------------------------------------------------
certutil man page errors -- To be fixed in a later version of the patch

----------------------------------------------------------
cmsutil man page errors:
the -D and -C options are not in alphabetic order
duplicate "SEE ALSO"

Addressed both.

--------------------------------------------------------
crlutil man page errors:
 -G Option is specified twice (the second specification is before 
  Arguments and has no description)
 Options and arguments are not in alphabetical order

Addressed.

--------------------------------------------------------
modutil man page
"other execute:       0001", the 0001 is formatted badly

Addressed 

"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."

Addressed.

--------------------------------------------------------
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]]

Not addressed. This one is a hard one to fix because we are using xml docbook to generate the nroff pages. I'm investigating.

 Arguments are not in alphabetical order.
Addressed

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

Addressed but not in the proper, it's a bit of a hack. Not easy to do in xml and I need to try a better Visual XML editor / validator.

--------------------------------------------------------
signtool man page:

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

Addressed.

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

Adressed.

--------------------------------------------------------
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."

Addressed.

--------------------------------------------------------
ssltap man page:
options are not sorted alphabetically

Adressed.

Created attachment 892069 [details]
Adress some of the flaws pointed out by Hubert - V2

Improved patch with a few certtul.xml fixes and specially pk12util.xml fixes were I got rid of ugly emprary hacks. Using Bluefish along with xmlcopyditor and some cleanup helped. There is more to do.

Created attachment 892672 [details]
Address most of the defects pointed by hkario - v4

Additonal fixes for certutil that were missing in the prior version.

Created attachment 892674 [details]
Address most of the defects pointed by hkario - v4

Added certutil.xml fixed that were missed in the previous one.

(In reply to Hubert Kario from comment #27)
> 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

I couldn't see the bad formatting when I did on fedora-20 or rhel-7 but it show up when doing it on rhel-6.6 as you have indicated. 

The man pages are generated from docbook xml using the xmlto tool. I suspect there lies the problem. Running $ rpm -q xmlto shows me:
rhel-6.6:  xmlto-0.0.23-3.el6.i686    -- 
rhel-7.0:  xmlto-0.0.25-7.el7.x86_64  -- good
fedora-20: xmlto-0.0.25-7.fc20.x86_64 -- good

I problem is likely caused by the older version of xmlto we have on rhel-6.6.

Comment on attachment 892674 [details]
Address most of the defects pointed by hkario - v4

See https://brewweb.devel.redhat.com/taskinfo?taskID=7417776 for a scratch build with this patch applied.

Comment on attachment 892674 [details]
Address most of the defects pointed by hkario - v4

Hubert, I think this patch addresses almost all of the issues you have raised save two dealing with formatting - certutil and pk12util. I have also submitted a version upstream.

Comment on attachment 892674 [details]
Address most of the defects pointed by hkario - v4

r- on the basis that I don't see fixes for:

signtool man page:

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

ssltap man page:

 options are not sorted alphabetically

pk12util man page:

 Arguments are not in alphabetical order.



Besides that:

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

The fix I had in mind, was to make only the "sql:" part bolded/highlighted in the man page.



I didn't check if the formatting fixes were effective. Specifically:

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

pk12util man page:

 synopsis gets formatted badly on narrow (80 column) terminal

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

I've tested the formatting fixes using nss-3.15.3-11.1.el6.manpages.4.x86_64

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

(We probably should report that as a bug in rhel-6, since this is not a problem in rhel-7 or Fedora)

errors in crlutil man page:

 Arguments not sorted

errors in pk12util:

 The synopsis still gets badly formatted at 80 column terminal

 Arguments not sorted

errors in signtool man page:

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

ssltap man page:

 options are not sorted alphabetically

(In reply to Hubert Kario from comment #42)
> Comment on attachment 892674 [details]
> Address most of the defects pointed by hkario - v4
> 
> r- on the basis that I don't see fixes for:
> 
> signtool man page:
> 
>  -G and -J options are in wrong position (not alphabetical order)
> 
> ssltap man page:
> 
>  options are not sorted alphabetically
> 
> pk12util man page:
> 
>  Arguments are not in alphabetical order.

Yes, I missed those, Comming.
> 
> 
> 
> Besides that:
> 
> certutil man page errors:
>  description of "-d [prefix]directory" in "NSS 
>  recognizes the following prefixes" is confusing, it's not explicit if the
> prefix 
>  is "sql" or "sql:"
> 
> The fix I had in mind, was to make only the "sql:" part bolded/highlighted
> in the man page.

Oh, that's easy to do
> 
> 
> 
> I didn't check if the formatting fixes were effective. Specifically:
> 
> 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
> 
> pk12util man page:
> 
>  synopsis gets formatted badly on narrow (80 column) terminal
> 
>  listing of "Symmetric CBC ciphers for PKCS#5 V2",
>  "PKCS#12 PBE ciphers" and "PKCS#5 PBE ciphers" has badly formatted
>  first ite

That's because I was trying to mimic the nice output pkc12util --help which is very difficult, if not imposible with docbook xml. I'll follow the approach used by crypto-util's genkey. Not perfect but better for this purpose.

(In reply to Hubert Kario from comment #43)
> I've tested the formatting fixes using nss-3.15.3-11.1.el6.manpages.4.x86_64
> 
> 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
> 
> (We probably should report that as a bug in rhel-6, since this is not a
> problem in rhel-7 or Fedora)

Reported in Bug 1096478.

Created attachment 894337 [details]
Addresses most of the review comments

https://brewweb.devel.redhat.com/taskinfo?taskID=7440040 is a scratch build with the patch applied.

(In reply to Elio Maldonado Batiz from comment #44)
> (In reply to Hubert Kario from comment #42)
> > 
> > pk12util man page:
> > 
> >  synopsis gets formatted badly on narrow (80 column) terminal
> > 
> >  listing of "Symmetric CBC ciphers for PKCS#5 V2",
> >  "PKCS#12 PBE ciphers" and "PKCS#5 PBE ciphers" has badly formatted
> >  first ite
> 
> That's because I was trying to mimic the nice output pkc12util --help which
> is very difficult, if not imposible with docbook xml. I'll follow the
> approach used by crypto-util's genkey. Not perfect but better for this
> purpose.

If you want to match `pk12util --help` output, I don't see why we couldn't show the "pk12util" command multiple times in "SYNOPSIS". I mean, `git-branch`, `grep` and `mplayer` do it, why couldn't we?

Comment on attachment 894337 [details]
Addresses most of the review comments

errors (based on nss-3.15.3-11.1.el6.manpages.6.x86_64.rpm):

signtool man page:
 -G and -J options are defined twice

crlutil man page:
 Arguments not sorted


the good:
ssltap fixed
pk12 arguments sorting fixed
certutil sql: and dbm: highlight fixed

Created attachment 894811 [details]
Addresses most of the review comments

-G and -J options defined once and crlutil man page arguments sorted
https://brewweb.devel.redhat.com/taskinfo?taskID=7443788 is the scratch build with this patch applied

Created attachment 894820 [details]
temporary workaround to faulty indendation

For information purpose, not for review. In the build I also applied this suplementary patch, a temporay workaround the formatting problems based on recommendations that Ondrej Vasik gave me on Bug 1096478. I use it like this:
....
# build the man pages clean
pushd ./nss
%{__make} clean_docs build_docs
# workaround until bug 1096478 is resolved
patch -b ./doc/nroff/certutil.1 $RPM_SOURCE_DIR/indentation.patch
popd
...

Comment on attachment 894811 [details]
Addresses most of the review comments

Looks ok, unfortunately it looks like brew already deleted the scratch build so I checked only the patch.

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/RHBA-2014-1378.html