doc: make the library API pages a little more readable

Use of the the '.B' and '.BI' man documentation macros
had rendered the three library API pages less readable
than they could be. In addition, sometimes the pointer
indicator and an identifier were separated by a space.

So, this commit will trade those macros for some '.RI'
and '.RB' macros plus treat the pointers consistently.

[ plus we no longer italicize sort 'stacks' brackets ]

Signed-off-by: Jim Warner <james.warner@comcast.net>

diff --git a/doc/procps.3 b/doc/procps.3
index de74ad0aef5437066da570331408f794e3a2f99f..5be15174d5cfe18ae57e2d034b84b048c14b87fc 100644 (file)
--- a/doc/procps.3
+++ b/doc/procps.3
@@ -16,7 +16,7 @@
 .\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 .\" %%%LICENSE_END
 .\"
-.TH PROCPS 3 "January 2022" "libproc-2"
+.TH PROCPS 3 "July 2022" "libproc-2"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .nh
@@ -32,34 +32,34 @@ the files they access in the /proc pseudo filesystem:
 .RS +4
 #include <procps/\fBnamed_interface\fR.h>
 
-.BI "int procps_new   (struct info **" info );
-.BI "int procps_ref   (struct info  *" info );
-.BI "int procps_unref (struct info **" info );
+.RI "int\fB procps_new  \fR (struct info **" info );
+.RI "int\fB procps_ref  \fR (struct info  *" info );
+.RI "int\fB procps_unref\fR (struct info **" info );
 
-.BI "struct result *procps_get ("
-.BI "    struct info *" info ,
+.RB "struct result *" procps_get " ("
+.RI "    struct info *" info ,
 .RI "[   const char *" name ",      ]   \fBdiskstats\fR api only"
-.BI "    enum item " item );
+.RI "    enum item " item );
 
-.BI "struct stack *procps_select ("
-.BI "    struct info *" info ,
+.RB "struct stack *" procps_select " ("
+.RI "    struct info *" info ,
 .RI "[   const char *" name ",      ]   \fBdiskstats\fR api only"
-.BI "    enum item *" items ,
-.BI "    int " numitems );
+.RI "    enum item *" items ,
+.RI "    int " numitems );
 
-.BI "struct reaped *procps_reap ("
-.BI "    struct info *" info ,
+.RB "struct reaped *" procps_reap " ("
+.RI "    struct info *" info ,
 .RI "[   enum reap_type " what ",   ]   \fBstat\fR api only"
-.BI "    enum item *" items ,
-.BI "    int " numitems );
-
-.BI "struct stack **procps_sort ("
-.BI "    struct info *" info ,
-.BI "    struct stack *" stacks[] ,
-.BI "    int " numstacked ,
-.BI "    enum item " sortitem ,
-.BI "    enum sort_order " order );
-.RE
+.RI "    enum item *" items ,
+.RI "    int " numitems );
+
+.RB "struct stack **" procps_sort " ("
+.RI "    struct info *" info ,
+.RI "    struct stack *" stacks [],
+.RI "    int " numstacked ,
+.RI "    enum item " sortitem ,
+.RI "    enum sort_order " order );
+
 .fi
 
 The above functions and structures are generic but the specific

diff --git a/doc/procps_misc.3 b/doc/procps_misc.3
index ad3629e4ba309969ccde74aa09c27caa69aa9972..ae270d7ad64641da963e2d4887fb4528e908c69a 100644 (file)
--- a/doc/procps_misc.3
+++ b/doc/procps_misc.3
@@ -17,7 +17,7 @@
 .\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 .\" %%%LICENSE_END
 .\"
-.TH PROCPS_MISC 3 "January 2022" "libproc-2"
+.TH PROCPS_MISC 3 "July 2022" "libproc-2"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .nh
@@ -30,27 +30,27 @@ procps_misc \- API for miscellaneous information in the /proc filesystem
 Platform Particulars
 .RS 4
 .PP
-.B "long         procps_cpu_count (void);"
-.B "long         procps_hertz_get (void);"
-.B "unsigned int procps_pid_length (void);"
-.B "int          procps_linux_version (void);"
+.RB "long         " procps_cpu_count " (void);
+.RB "long         " procps_hertz_get " (void);
+.RB "unsigned int " procps_pid_length " (void);
+.RB "int          " procps_linux_version " (void);
 .RE
 .PP
 Runtime Particulars
 .PP
 .RS 4
-.BI "int    procps_loadavg (double * " av1 ", double * " av5 ", double * " av15 ");"
-.BI "int    procps_uptime (double * " uptime_secs ", double * " idle_secs ");"
-.B  "char * procps_uptime_sprint (void);"
-.B  "char * procps_uptime_sprint_short (void);"
+.RI "int  \fB procps_loadavg\fR (double *" av1 ", double *" av5 ", double *" av15 ");"
+.RI "int  \fB procps_uptime\fR (double *" uptime_secs ", double *" idle_secs ");"
+.RB "char *" procps_uptime_sprint " (void);"
+.RB "char *" procps_uptime_sprint_short " (void);"
 .RE
 .PP
 Namespace Particulars
 .PP
 .RS 4
-.BI "int          procps_ns_get_id (const char * " name ");"
-.BI "const char * procps_ns_get_name (int " id ");"
-.BI "int          procps_ns_read_pid (int " pid ", struct procps_ns * " nsp ");"
+.RI "int       \fB  procps_ns_get_id\fR (const char *" name ");"
+.RI "const char\fB *procps_ns_get_name\fR (int " id ");"
+.RI "int       \fB  procps_ns_read_pid\fR (int " pid ", struct procps_ns *" nsp ");"
 .RE
 
 Link with \fI\-lproc-2\fP.

diff --git a/doc/procps_pids.3 b/doc/procps_pids.3
index 663118e2a01a19f63e699faf0a8e2538a357500f..c7b874d213b548e6bc29ad58823cbdd03b8fb265 100644 (file)
--- a/doc/procps_pids.3
+++ b/doc/procps_pids.3
@@ -16,7 +16,7 @@
 .\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 .\" %%%LICENSE_END
 .\"
-.TH PROCPS_PIDS 3 "January 2022" "libproc-2"
+.TH PROCPS_PIDS 3 "July 2022" "libproc-2"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .nh
@@ -27,41 +27,40 @@ procps_pids \- API to access process information in the /proc filesystem
 .nf
 #include <procps/pids.h>
 
-.BI "int procps_pids_new   (struct pids_info **" info ", enum pids_item *" items ", int " numitems );
-.BI "int procps_pids_ref   (struct pids_info  *" info );
-.BI "int procps_pids_unref (struct pids_info **" info );
+.RI "int\fB procps_pids_new  \fR (struct pids_info **" info ", enum pids_item *" items ", int " numitems );
+.RI "int\fB procps_pids_ref  \fR (struct pids_info  *" info );
+.RI "int\fB procps_pids_unref\fR (struct pids_info **" info );
 
 
-.BI "struct pids_stack *procps_pids_get ("
-.BI "    struct pids_info *" info ,
-.BI "    enum pids_fetch_type " which );
+.RB "struct pids_stack *" procps_pids_get " ("
+.RI "    struct pids_info *" info ,
+.RI "    enum pids_fetch_type " which );
 
-.BI "struct pids_fetch *procps_pids_reap ("
-.BI "    struct pids_info *" info ,
-.BI "    enum pids_fetch_type " which );
+.RB "struct pids_fetch *" procps_pids_reap " ("
+.RI "    struct pids_info *" info ,
+.RI "    enum pids_fetch_type " which );
 
-.BI "struct pids_fetch *procps_pids_select ("
-.BI "    struct pids_info *" info ,
-.BI "    unsigned *" these ,
-.BI "    int " numthese ,
-.BI "    enum pids_select_type " which );
+.RB "struct pids_fetch *" procps_pids_select " ("
+.RI "    struct pids_info *" info ,
+.RI "    unsigned *" these ,
+.RI "    int " numthese ,
+.RI "    enum pids_select_type " which );
 
-.BI "struct pids_stack **procps_pids_sort ("
-.BI "    struct pids_info *" info ,
-.BI "    struct pids_stack *" stacks[] ,
-.BI "    int " numstacked ,
-.BI "    enum pids_item " sortitem ,
-.BI "    enum pids_sort_order " order );
+.RB "struct pids_stack **" procps_pids_sort " ("
+.RI "    struct pids_info *" info ,
+.RI "    struct pids_stack *" stacks [],
+.RI "    int " numstacked ,
+.RI "    enum pids_item " sortitem ,
+.RI "    enum pids_sort_order " order );
 
+.RB "int " procps_pids_reset " ("
+.RI "    struct pids_info *" info ,
+.RI "    enum pids_item *" newitems ,
+.RI "    int " newnumitems );
 
-.BI "int procps_pids_reset ("
-.BI "    struct pids_info *" info ,
-.BI "    enum pids_item *" newitems ,
-.BI "    int " newnumitems );
-
-.BI "struct pids_stack *fatal_proc_unmounted ("
-.BI "    struct pids_info *" info ,
-.BI "    int " return_self );
+.RB "struct pids_stack *" fatal_proc_unmounted " ("
+.RI "    struct pids_info *" info ,
+.RI "    int " return_self );
 
 .fi