[v1,08/10] man: Improve formatting of SYNOPSIS of commands

Commit Message

Alejandro Colomar June 19, 2024, 11:25 p.m. UTC

Signed-off-by: Alejandro Colomar <[e-mail]>
---
 man/keyctl.1      | 426 ++++++++++++++++++++++++++++++++++------------
 man/request-key.8 |  12 +-
 2 files changed, 324 insertions(+), 114 deletions(-)

Patch

diff --git a/man/keyctl.1 b/man/keyctl.1
index 59eabf7..59172d4 100644
--- a/man/keyctl.1
+++ b/man/keyctl.1
@@ -11,118 +11,320 @@ 
 .SH NAME
 keyctl \- key management facility control
 .SH SYNOPSIS
-\fBkeyctl\fR \-\-version
-.br
-\fBkeyctl\fR supports [<cap> | --raw]
-.br
-\fBkeyctl\fR id [<keyring>]
-.br
-\fBkeyctl\fR show [\-x] [<keyring>]
-.br
-\fBkeyctl\fR add [\-x] <type> <desc> <data> <keyring>
-.br
-\fBkeyctl\fR padd [\-x] <type> <desc> <keyring>
-.br
-\fBkeyctl\fR request <type> <desc> [<dest_keyring>]
-.br
-\fBkeyctl\fR request2 <type> <desc> <info> [<dest_keyring>]
-.br
-\fBkeyctl\fR prequest2 <type> <desc> [<dest_keyring>]
-.br
-\fBkeyctl\fR update [\-x] <key> <data>
-.br
-\fBkeyctl\fR pupdate [\-x] <key>
-.br
-\fBkeyctl\fR newring <name> <keyring>
-.br
-\fBkeyctl\fR revoke <key>
-.br
-\fBkeyctl\fR clear <keyring>
-.br
-\fBkeyctl\fR link <key> <keyring>
-.br
-\fBkeyctl\fR unlink <key> [<keyring>]
-.br
-\fBkeyctl\fR move [-f] <key> <from_keyring> <to_keyring>
-.br
-\fBkeyctl\fR search <keyring> <type> <desc> [<dest_keyring>]
-.br
-\fBkeyctl\fR restrict_keyring <keyring> [<type> [<restriction>]]
-.br
-\fBkeyctl\fR read <key>
-.br
-\fBkeyctl\fR pipe <key>
-.br
-\fBkeyctl\fR print <key>
-.br
-\fBkeyctl\fR list <keyring>
-.br
-\fBkeyctl\fR rlist <keyring>
-.br
-\fBkeyctl\fR describe <keyring>
-.br
-\fBkeyctl\fR rdescribe <keyring> [sep]
-.br
-\fBkeyctl\fR chown <key> <uid>
-.br
-\fBkeyctl\fR chgrp <key> <gid>
-.br
-\fBkeyctl\fR setperm <key> <mask>
-.br
-\fBkeyctl\fR new_session [<name>]
-.br
-\fBkeyctl\fR session
-.br
-\fBkeyctl\fR session \- [<prog> <arg1> <arg2> ...]
-.br
-\fBkeyctl\fR session <name> [<prog> <arg1> <arg2> ...]
-.br
-\fBkeyctl\fR instantiate [\-x] <key> <data> <keyring>
-.br
-\fBkeyctl\fR pinstantiate [\-x] <key> <keyring>
-.br
-\fBkeyctl\fR negate <key> <timeout> <keyring>
-.br
-\fBkeyctl\fR reject <key> <timeout> <error> <keyring>
-.br
-\fBkeyctl\fR timeout <key> <timeout>
-.br
-\fBkeyctl\fR security <key>
-.br
-\fBkeyctl\fR reap [\-v]
-.br
-\fBkeyctl\fR purge <type>
-.br
-\fBkeyctl\fR purge [\-i] [\-p] <type> <desc>
-.br
-\fBkeyctl\fR purge \-s <type> <desc>
-.br
-\fBkeyctl\fR get_persistent <keyring> [<uid>]
-.br
-\fBkeyctl\fR dh_compute <private> <prime> <base>
-.br
-\fBkeyctl\fR dh_compute_kdf <private> <prime> <base> <output_length> <hash_type>
-.br
-\fBkeyctl\fR dh_compute_kdf_oi [\-x] <private> <prime> <base> <output_length> <hash_type>
-.br
-\fBkeyctl\fR pkey_query <key> <pass> [k=v]*
-.br
-\fBkeyctl\fR pkey_encrypt <key> <pass> <datafile> [k=v]* ><encfile>
-.br
-\fBkeyctl\fR pkey_decrypt <key> <pass> <encfile> [k=v]* ><datafile>
-.br
-\fBkeyctl\fR pkey_sign <key> <pass> <datafile> [k=v]* ><sigfile>
-.br
-\fBkeyctl\fR pkey_decrypt <key> <pass> <datafile> <sigfile> [k=v]*
-.br
-\fBkeyctl\fR watch [\-f<filters>] <key>
-.br
-\fBkeyctl\fR watch_add <fd> <key>
-.br
-\fBkeyctl\fR watch_rm <fd> <key>
-.br
-\fBkeyctl\fR watch_session [\-f <filters>] [-n <name>] \\
-                <notifylog> <gclog> <fd> <prog> [<arg1> <arg2> ...]
+.SY keyctl
+.B \-\-version
+.YS
+.SY keyctl
+.B supports
+.RI [ cap \~|\~\fB--raw\fP]
+.YS
+.SY keyctl
+.B id
+.RI [ keyring ]
+.YS
+.SY keyctl
+.B show
+.RB [ \-x ]
+.RI [ keyring ]
+.YS
+.SY keyctl
+.B add
+.RB [ \-x ]
+.I type
+.I desc
+.I data
+.I keyring
+.YS
+.SY keyctl
+.B padd
+.RB [ \-x ]
+.I type
+.I desc
+.I keyring
+.YS
+.SY keyctl
+.B request
+.I type
+.I desc
+.RI [ dest_keyring ]
+.YS
+.SY keyctl
+.B request2
+.I type
+.I desc
+.I info
+.RI [ dest_keyring ]
+.YS
+.SY keyctl
+.B prequest2
+.I type
+.I desc
+.RI [ dest_keyring ]
+.YS
+.SY keyctl
+.B update
+.RB [ \-x ]
+.I key
+.I data
+.YS
+.SY keyctl
+.B pupdate
+.RB [ \-x ]
+.I key
+.YS
+.SY keyctl
+.B newring
+.I name
+.I keyring
+.YS
+.SY keyctl
+.B revoke
+.I key
+.YS
+.SY keyctl
+.B clear
+.I keyring
+.YS
+.SY keyctl
+.B link
+.I key
+.I keyring
+.YS
+.SY keyctl
+.B unlink
+.I key
+.RI [ keyring ]
+.YS
+.SY keyctl
+.B move
+.RB [ -f ]
+.I key
+.I from_keyring
+.I to_keyring
+.YS
+.SY keyctl
+.B search
+.I keyring
+.I type
+.I desc
+.RI [ dest_keyring ]
+.YS
+.SY keyctl
+.B restrict_keyring
+.I keyring
+.RI [ type
+.RI [ restriction ]]
+.YS
+.SY keyctl
+.B read
+.I key
+.YS
+.SY keyctl
+.B pipe
+.I key
+.YS
+.SY keyctl
+.B print
+.I key
+.YS
+.SY keyctl
+.B list
+.I keyring
+.YS
+.SY keyctl
+.B rlist
+.I keyring
+.YS
+.SY keyctl
+.B describe
+.I keyring
+.YS
+.SY keyctl
+.B rdescribe
+.I keyring
+.RB [ sep ]
+.YS
+.SY keyctl
+.B chown
+.I key
+.I uid
+.YS
+.SY keyctl
+.B chgrp
+.I key
+.I gid
+.YS
+.SY keyctl
+.B setperm
+.I key
+.I mask
+.YS
+.SY keyctl
+.B new_session
+.RI [ name ]
+.YS
+.SY keyctl
+.B session
+.YS
+.SY keyctl
+.B session
+.B \-
+.RI [ prog
+.IR args \~.\|.\|.]
+.YS
+.SY keyctl
+.B session
+.I name
+.RI [ prog
+.RI [ args \~.\|.\|.]]
+.YS
+.SY keyctl
+.B instantiate
+.RB [ \-x ]
+.I key
+.I data
+.I keyring
+.YS
+.SY keyctl
+.B pinstantiate
+.RB [ \-x ]
+.I key
+.I keyring
+.YS
+.SY keyctl
+.B negate
+.I key
+.I timeout
+.I keyring
+.YS
+.SY keyctl
+.B reject
+.I key
+.I timeout
+.I error
+.I keyring
+.YS
+.SY keyctl
+.B timeout
+.I key
+.I timeout
+.YS
+.SY keyctl
+.B security
+.I key
+.YS
+.SY keyctl
+.B reap
+.RB [ \-v ]
+.YS
+.SY keyctl
+.B purge
+.I type
+.YS
+.SY keyctl
+.B purge
+.RB [ \-i ]
+.RB [ \-p ]
+.I type
+.I desc
+.YS
+.SY keyctl
+.B purge
+.B \-s
+.I type
+.I desc
+.YS
+.SY keyctl
+.B get_persistent
+.I keyring
+.RI [ uid ]
+.YS
+.SY keyctl
+.B dh_compute
+.I private
+.I prime
+.I base
+.YS
+.SY keyctl
+.B dh_compute_kdf
+.I private
+.I prime
+.I base
+.I output_length
+.I hash_type
+.YS
+.SY keyctl
+.B dh_compute_kdf_oi
+.RB [ \-x ]
+.I private
+.I prime
+.I base
+.I output_length
+.I hash_type
+.YS
+.SY keyctl
+.B pkey_query
+.I key
+.I pass
+.RI [ k \fB=\fP v \~.\|.\|.]
+.YS
+.SY keyctl
+.B pkey_encrypt
+.I key
+.I pass
+.I datafile
+.RI [ k \fB=\fP v \~.\|.\|.\&]
+.I encfile
+.YS
+.SY keyctl
+.B pkey_decrypt
+.I key
+.I pass
+.I encfile
+.RI [ k \fB=\fP v \~.\|.\|.\&]
+.I datafile
+.YS
+.SY keyctl
+.B pkey_sign
+.I key
+.I pass
+.I datafile
+.RI [ k \fB=\fP v \~.\|.\|.\&]
+.I sigfile
+.YS
+.SY keyctl
+.B pkey_decrypt
+.I key
+.I pass
+.I datafile
+.I sigfile
+.RI [ k \fB=\fP v \~.\|.\|.]
+.YS
+.SY keyctl
+.B watch
+.RB [ \-f \~\fIfilters\fP]
+.I key
+.YS
+.SY keyctl
+.B watch_add
+.I fd
+.I key
+.YS
+.SY keyctl
+.B watch_rm
+.I fd
+.I key
+.YS
+.SY keyctl
+.B watch_session
+.RB [ \-f \~\fIfilters\fP]
+.RB [ \-n \~\fIname\fP]
+.I notifylog
+.I gclog
+.I fd
+.I prog
+.RI [ args \~.\|.\|.]
+.YS
 .SH DESCRIPTION
 This program is used to control the key management facility in various ways
 using a variety of subcommands.
diff --git a/man/request-key.8 b/man/request-key.8
index d49ca78..08f2ace 100644
--- a/man/request-key.8
+++ b/man/request-key.8
@@ -11,8 +11,16 @@ 
 .SH NAME
 request\-key \- handle key instantiation callback requests from the kernel
 .SH SYNOPSIS
-\fB/sbin/request\-key \fR<op> <key> <uid> <gid> <threadring> <processring>
-	<sessionring> [<info>]
+.SY /sbin/request\-key
+.I op
+.I key
+.I uid
+.I gid
+.I threadring
+.I processring
+.I sessionring
+.RI [ info ]
+.YS
 .SH DESCRIPTION
 This program is invoked by the kernel when the kernel is asked for a key that
 it doesn't have immediately available. The kernel creates a partially set up