Poll on manpages

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

Poll on manpages

OpenSSL - User mailing list

The next release of OpenSSL splits the “help” for commands into sections, like this:

 

; ./apps/openssl rehash --help

Usage: rehash [options] [directory...]

 

General options:

-help        Display this summary

-h           Display this summary

-compat      Create both new- and old-style hash links

-old         Use old-style hash to generate links

-n           Do not remove existing links

 

Output options:

-v           Verbose output

 

Parameters:

directory    One or more directories to process (optional)

 

Should the order of options in the manpages follow this layout?  Should there be a blank line (in the SYNOPSIS section!) between the option sections?  Please take a look at https://github.com/openssl/openssl/pull/10885 which does this for s_client.  You can see just the changed file here: https://github.com/openssl/openssl/blob/71d8c19554a65cf0717f6b7e7b34849456e76888/doc/man1/openssl-s_client.pod.in

 

Replies to me will be summarized for the list.  Thanks!

 

Reply | Threaded
Open this post in threaded view
|

Re: Poll on manpages

Ethan Rahn
Rich,

If no-one else tells you, keeping the docs up to date is amazing work and thank you for it.

My general thought is that all docs should be consistent with one another for ease of cross referncing and skimming and the manpages should follow the same layout.

Cheers,

Ethan

On Tue, Jan 28, 2020 at 11:21 AM Salz, Rich via openssl-users <[hidden email]> wrote:

The next release of OpenSSL splits the “help” for commands into sections, like this:

 

; ./apps/openssl rehash --help

Usage: rehash [options] [directory...]

 

General options:

-help        Display this summary

-h           Display this summary

-compat      Create both new- and old-style hash links

-old         Use old-style hash to generate links

-n           Do not remove existing links

 

Output options:

-v           Verbose output

 

Parameters:

directory    One or more directories to process (optional)

 

Should the order of options in the manpages follow this layout?  Should there be a blank line (in the SYNOPSIS section!) between the option sections?  Please take a look at https://github.com/openssl/openssl/pull/10885 which does this for s_client.  You can see just the changed file here: https://github.com/openssl/openssl/blob/71d8c19554a65cf0717f6b7e7b34849456e76888/doc/man1/openssl-s_client.pod.in

 

Replies to me will be summarized for the list.  Thanks!