[PATCH] pldd.1: Document glibc's unbreakage of tool.

* [PATCH] pldd.1: Document glibc's unbreakage of tool.
@ 2019-05-11  7:20 G. Branden Robinson
  2019-05-13  9:48 ` Florian Weimer
  2019-07-29 19:07 ` Michael Kerrisk (man-pages)
  0 siblings, 2 replies; 12+ messages in thread
From: G. Branden Robinson @ 2019-05-11  7:20 UTC (permalink / raw)
  To: mtk.manpages; +Cc: linux-man, libc-alpha


[-- Attachment #1.1: Type: text/plain, Size: 148 bytes --]

...plus a patch with some suggested wording fixes.

...plus a patch with some suggestions on improving the formatting and
markup.

Regards,
Branden

[-- Attachment #1.2: 0001-pldd.1-Document-glibc-s-unbreakage-of-tool.patch --]
[-- Type: text/x-diff, Size: 1229 bytes --]

From fddc56cb731f711143bad6202210d974ace7b7fe Mon Sep 17 00:00:00 2001
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Date: Sat, 11 May 2019 16:25:54 +1000
Subject: [PATCH 1/3] pldd.1: Document glibc's unbreakage of tool.

glibc 2.30 isn't released yet, but a fix has been committed, and Debian
has even cherry-picked it for Debian GNU/Linux 10 ("buster").  pldd
works nicely now.

Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
---
 man1/pldd.1 | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/man1/pldd.1 b/man1/pldd.1
index 90e259989..dab6cb32c 100644
--- a/man1/pldd.1
+++ b/man1/pldd.1
@@ -97,11 +97,11 @@ $ \fBgdb \-ex "set confirm off" \-ex "set height 0" \-ex "info shared" \e\fP
 .EE
 .in
 .SH BUGS
-Since glibc 2.19,
+From glibc 2.19 to 2.29,
 .B pldd
-is broken: it just hangs when executed.
-.\" FIXME . https://sourceware.org/bugzilla/show_bug.cgi?id=18035
-It is unclear if it will ever be fixed.
+was broken: it just hung when executed.
+.\" glibc commit 1a4c27355e146b6d8cc6487b998462c7fdd1048f
+This problem was fixed in glibc 2.30.
 .SH EXAMPLE
 .EX
 $ \fBecho $$\fP               # Display PID of shell
-- 
2.20.1


[-- Attachment #1.3: 0002-pldd.1-wfix.patch --]
[-- Type: text/x-diff, Size: 1676 bytes --]

From d1ee216ecb3400c2f14aed4a8689b34ec9d2d3da Mon Sep 17 00:00:00 2001
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Date: Sat, 11 May 2019 16:30:10 +1000
Subject: [PATCH 2/3] pldd.1: wfix

* Establish the abbreviations DSO and PID in the lead paragraph since
  they are used later.
* Parallelize descriptions of help, usage, and version options with the
  "and exit" language used in getent(1), iconv(1), locale(1),
  localedef(1), memusage(1), memusagestat(1), mtrace(1), pldd(1),
  sprof(1), time(1), iconvconfig(8), zdump(8), and zic(8).

Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
---
 man1/pldd.1 | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/man1/pldd.1 b/man1/pldd.1
index dab6cb32c..035368e20 100644
--- a/man1/pldd.1
+++ b/man1/pldd.1
@@ -33,20 +33,20 @@ pldd \- display dynamic shared objects linked into a process
 .SH DESCRIPTION
 The
 .B pldd
-command displays a list of the dynamic shared objects that are
-linked into the process with the specified process ID.
+command displays a list of the dynamic shared objects (DSOs) that are
+linked into the process with the specified process ID (PID).
 The list includes the libraries that have been dynamically loaded using
 .BR dlopen (3).
 .SH OPTIONS
 .TP
 .BR \-? ", " \-\-help
-Display program help message.
+Display a help message and exit.
 .TP
 .B \-\-usage
-Display a short usage message.
+Display a short usage message and exit.
 .TP
 .BR \-V ", " \-\-version
-Display the program version.
+Display program version information and exit.
 .SH EXIT STATUS
 On success,
 .B pldd
-- 
2.20.1


[-- Attachment #1.4: 0003-pldd.1-srcfix-ffix-wfix-wsfix.patch --]
[-- Type: text/x-diff, Size: 3941 bytes --]

From 9285fe1b80cfbb52cfeff33372338a8c4728d47b Mon Sep 17 00:00:00 2001
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Date: Sat, 11 May 2019 16:38:39 +1000
Subject: [PATCH 3/3] pldd.1: srcfix, ffix, wfix, wsfix

* [srcfix] Migrate Synopsis section from no-fill mode to no-adjust mode.
  This way you can break the pieces of a synopsis output line across
  multiple input lines, use the easy one-font macros, and worry less
  about quotation issues.  (My best recommendation would be to go ahead
  and use groff_man's .SY/.YS extensions--but not .OP--for synopsis
  sections, but I think this was considered and rejected a couple of
  years ago.)

* [wfix] Actually list the available options in the synopsis.  There
  aren't many for pldd and they won't even line-wrap on an 80-column
  terminal.  (not technically a ffix)

* [srcfix] Use .RS for indentation instead of low-level .in requests.
  It's my belief that .RS and .RE pairs require less bookkeeping.

* [srcfix] Use \c (the output line continuation escape) in examples to
  facilitate style (bold, italic) changes within a line.  The result is
  more attractive and intuitive, particularly enabling italicization of
  paramaters in examples.

* [srcfix] Use font macros instead of font escapes in examples.  This is
  more readable, and helped to expose the next problem.

* [ffix] Consistently escape all hyphens used as option dashes in gdb
  example.

* [wsfix] Eliminate hard tab from input file, replacing it (in an
  example) with an appropriate number of non-adjustable spaces.
  (Whether this is a srcfix or wsfix depends on the output device and
  user configuration, which is, I submit, why we don't want to use hard
  tabs in the first place.)

Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
---
 man1/pldd.1 | 48 +++++++++++++++++++++++++++++++-----------------
 1 file changed, 31 insertions(+), 17 deletions(-)

diff --git a/man1/pldd.1 b/man1/pldd.1
index 035368e20..33245d0d5 100644
--- a/man1/pldd.1
+++ b/man1/pldd.1
@@ -26,10 +26,15 @@
 .SH NAME
 pldd \- display dynamic shared objects linked into a process
 .SH SYNOPSIS
-.nf
-.BI "pldd " "pid"
-.BI pldd " option"
-.fi
+.na
+.B pldd
+.I pid
+.PP
+.B pldd
+.RB [ \-? | \-\-help ]
+.RB [ \-\-usage ]
+.RB [ \-V | \-\-version ]
+.ad
 .SH DESCRIPTION
 The
 .B pldd
@@ -71,14 +76,17 @@ have a similar command.
 .SH NOTES
 The command
 .PP
-.in +4n
+.RS 4n
 .EX
-lsof \-p PID
+$ \c
+.B lsof \-p \c
+.I pid
 .EE
-.in
+.RE
 .PP
 also shows output that includes the dynamic shared objects
-that are linked into a process.
+that are linked into the process
+.IR pid .
 .PP
 The
 .BR gdb (1)
@@ -87,15 +95,19 @@ command also shows the shared libraries being used by a process,
 so that one can obtain similar output to
 .B pldd
 using a command such as the following
-(to monitor the process with the specified
-.IR pid ):
+(to monitor the process with the specified PID):
 .PP
-.in +4n
+.RS 4n
 .EX
-$ \fBgdb \-ex "set confirm off" \-ex "set height 0" \-ex "info shared" \e\fP
-        \fB-ex "quit" \-p $pid | grep '^0x.*0x'\fP
+$ \c
+.B gdb \-ex "set confirm off" \-ex "set height 0" \-ex "info shared" \e
+.RS 8n
+.B \-ex quit \-p \c
+.I pid \c
+.B | grep \(aq\(ti0x.*0x\(aq
+.RE
 .EE
-.in
+.RE
 .SH BUGS
 From glibc 2.19 to 2.29,
 .B pldd
@@ -104,10 +116,12 @@ was broken: it just hung when executed.
 This problem was fixed in glibc 2.30.
 .SH EXAMPLE
 .EX
-$ \fBecho $$\fP               # Display PID of shell
+$ \c
+.BR "echo $$" "              # Display PID of the running shell."
 1143
-$ \fBpldd $$\fP               # Display DSOs linked into the shell
-1143:	/usr/bin/bash
+$ \c
+.BR "pldd $$" "              # Display DSOs linked into the shell."
+1143:\ \ \ /usr/bin/bash
 linux\-vdso.so.1
 /lib64/libtinfo.so.5
 /lib64/libdl.so.2
-- 
2.20.1


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply related	[flat|nested] 12+ messages in thread