> In the short-run, can't you achieve your goal the same way with this:
>
> pod2mdoc -> doclifter -> docbook2mdoc -> man
>
> Eventually, we can re-write man to accept more sophisticated formats
> directly instead of being tied to mdoc(7), but this would be transparent
> to end-users.
>
> Thoughts?
Another approach is to extend the usage() in every program so that it
provides more information.
For example, ssh-keygen(1)'s usage spits out:
% ssh-keygen -?
usage: ssh-keygen [options]
Options:
-A Generate non-existent host keys for all key types.
-a number Number of KDF rounds for new key format or moduli primality tests.
-B Show bubblebabble digest of key file.
-b bits Number of bits in the key to create.
-C comment Provide new comment.
-c Change comment in private and public key files.
-D pkcs11 Download public key from pkcs11 token.
-e Export OpenSSH to foreign format key file.
-F hostname Find hostname in known hosts file.
-f filename Filename of the key file.
-G file Generate candidates for DH-GEX moduli.
-g Use generic DNS resource record format.
-H Hash names in known_hosts file.
-h Generate host certificate instead of a user certificate.
-I key_id Key identifier to include in certificate.
-i Import foreign format to OpenSSH key file.
-J number Screen this number of moduli lines.
-j number Start screening moduli at specified line.
-K checkpt Write checkpoints to this file.
-k Generate a KRL file.
-L Print the contents of a certificate.
-l Show fingerprint of key file.
-M memory Amount of memory (MB) to use for generating DH-GEX moduli.
-m key_fmt Conversion format for -e/-i (PEM|PKCS8|RFC4716).
-N phrase Provide new passphrase.
-n name,... User/host principal names to include in certificate
-O option Specify a certificate option.
-o Enforce new private key format.
-P phrase Provide old passphrase.
-p Change passphrase of private key file.
-Q Test whether key(s) are revoked in KRL.
-q Quiet.
-R hostname Remove host from known_hosts file.
-r hostname Print DNS resource record.
-S start Start point (hex) for generating DH-GEX moduli.
-s ca_key Certify keys with CA key.
-T file Screen candidates for DH-GEX moduli.
-t type Specify type of key to create.
-u Update KRL rather than creating a new one.
-V from:to Specify certificate validity interval.
-v Verbose.
-W gen Generator to use for generating DH-GEX moduli.
-y Read private key file and print public key.
-Z cipher Specify a cipher for new private key format.
-z serial Specify a serial number.
It probably is not much more work to add the remaining bits from
the old (crufty) manual page to the usage() code in the program.
Then the semantic markup would all be in one place -- in the source
files. There would be no need for seperate manual pages, and the
pipeline could be simply:
ssh-keygen -? -> usage2pod -> pod2mdoc -> doclifter -> docbook2mdoc -> man
More food for thought.
