On 4/1/14, Theo de Raadt <[email protected]> wrote:
>> 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.
sorry to crash your party, but i think you've got something there
with the usage() example. this could reduce man executable to
a one line shell script (or a builtin):
$ cat /usr/bin/man
#!/bin/sh
while [ $# -gt 0 ] ; do $1 -h | ${PAGER:-more} ; shift ; done
Yeah?
--patrick
> 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.
>
>
