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

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

[G. Branden Robinson]

[-- 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 --]

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

[Florian Weimer]

* G. Branden Robinson:

>  .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.

I'm not sure if it makes sense to document this in the manual page.  I
expect that the fix will propagate to affected distributions fairly
quickly, now that it is available upstream.  It's certainly more likely
that users will receive a glibc update with the fix than a manpage
update with this change.

Thanks,
Florian

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

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 2189 bytes --]

Hi Florian!  Response inline.

At 2019-05-13T11:48:19+0200, Florian Weimer wrote:
> * G. Branden Robinson:
> 
> >  .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.
> 
> I'm not sure if it makes sense to document this in the manual page.

It might not; another resonable approach might be to nuke the "Bugs"
section of the man page entirely.  However, see below.

> I expect that the fix will propagate to affected distributions fairly
> quickly, now that it is available upstream.

True for fast-moving distributions; as I noted in the commit message,
Debian 10 has already got it backported to its glibc 2.29.

> It's certainly more likely that users will receive a glibc update with
> the fix than a manpage update with this change.

Desktop systems will get both; stripped-down systems will likely follow
your scenario.  On the other hand I generally read man pages on my
full-blown {desk,lap}top, not some embedded or target system.  So I can
imagine a scenario where somebody is targeting a "stable" or legacy
system with glibc 2.29 or older and is wondering why the F "pldd"
doesn't work.  They type "man pldd" (as a last resort, of course) on
their dev box, and lo and behold, all is explained.

Michael K. is pretty diligent about having man-pages track behavior
changes as they come and go in the Linux kernel, and my patch is an
attempt to match that tradition.  However, it might not make sense or be
his preference for the glibc-related man pages.

My primary concern is to get what is now a false statement corrected or
removed.  pldd is not still broken.

I have an update for the fiddly third patch, but once Michael follows up
I'll continue that branch of the thread on linux-man only; I'm confident
libc-alpha does not care about the fine details of *roff markup.

Regards,
Branden

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

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

[walter harms]

Am 13.05.2019 11:48, schrieb Florian Weimer:
> * G. Branden Robinson:
> 
>>  .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.
> 
> I'm not sure if it makes sense to document this in the manual page.  I
> expect that the fix will propagate to affected distributions fairly
> quickly, now that it is available upstream.  It's certainly more likely
> that users will receive a glibc update with the fix than a manpage
> update with this change.
> 

IMHO it should be noted in the BUGS section.
You can not rely that you have always the lastest version of libc
(at least i do not have) but you may notice a different behavior
and it is simply very helpful to have a hint that certain versions
are broken. (if someone cares: my problem was with a64l. It suddenly
changed behavior ...)

just my 2 cents,
re,
 wh

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

[Florian Weimer]

* G. Branden Robinson:

>> I'm not sure if it makes sense to document this in the manual page.
>
> It might not; another resonable approach might be to nuke the "Bugs"
> section of the man page entirely.  However, see below.
>
>> I expect that the fix will propagate to affected distributions fairly
>> quickly, now that it is available upstream.
>
> True for fast-moving distributions; as I noted in the commit message,
> Debian 10 has already got it backported to its glibc 2.29.

I'm pretty sure Debian 10 does not use glibc 2.28.

My point is that the glibc change will get backported, but any man-pages
change will not, so it will be quite some time until the latter shows up
on developer workstations.  And due to glibc backporting, the version
information there will be misleading.

Thanks,
Florian

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

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 824 bytes --]

At 2019-05-17T17:44:41+0200, Florian Weimer wrote:
> I'm pretty sure Debian 10 does not use glibc 2.28.

No, and for that matter I can't be sure that the next release of glibc
will be numbered 2.30.  :)

> My point is that the glibc change will get backported, but any
> man-pages change will not, so it will be quite some time until the
> latter shows up on developer workstations.  And due to glibc
> backporting, the version information there will be misleading.

Backports and distributor patches are a fact of life in the present
ecosystem, but an upstream version still communicates valuable
information.  My opinion.

What would you prefer?  That the man page not document the bug at all?
Was it a mistake in your view to have added the information about the
bug to the man page in the first place?

Regards,
Branden

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

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

[Carlos O'Donell]

On Fri, May 17, 2019 at 11:51 AM G. Branden Robinson
<g.branden.robinson@gmail.com> wrote:
> What would you prefer?  That the man page not document the bug at all?
> Was it a mistake in your view to have added the information about the
> bug to the man page in the first place?

I think having the glibc upstream version information is useful.

Cheers,
Carlos.

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

[Joseph Myers]

On Fri, 17 May 2019, Carlos O'Donell wrote:

> On Fri, May 17, 2019 at 11:51 AM G. Branden Robinson
> <g.branden.robinson@gmail.com> wrote:
> > What would you prefer?  That the man page not document the bug at all?
> > Was it a mistake in your view to have added the information about the
> > bug to the man page in the first place?
> 
> I think having the glibc upstream version information is useful.

Likewise - if a bug is worth documenting there I think it's unavoidable 
that the version numbers describe when things changed in glibc upstream.

What's more of an issue is when the BUGS section gets out of date or the 
descriptions of the conditions for an issue are misleading.  pow(3) is a 
case in point; it says "On 64-bits" meaning "on systems using the generic 
implementation" (i.e., it's written from an assumption that x86_64 and 
i386 are the only architectures and that i386 is the default), and that 
issue was fixed in 2.28, while the "If x is negative" described there was 
both i386-specific (not mentioned as such) and fixed in 2.16.

-- 
Joseph S. Myers
joseph@codesourcery.com

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

[Michael Kerrisk (man-pages)]

Hi Branden,

On 5/11/19 9:20 AM, G. Branden Robinson wrote:
> ...plus a patch with some suggested wording fixes.
> 
> ...plus a patch with some suggestions on improving the formatting and
> markup.

Sorry for the late reply. I actually applied some of your
changes a few days back (they're already in Git).

You often have good inputs, but your idiosyncratic submission
style does make it harder than necessary for me to deal with
that input. Please:

* One patch per mail
* Patches best inline; if you are worried your mailer may
  break the patch, then both inline and as an attachment.
* Your patch 3 does so many things at the same time that it's
  impossible to apply. Some of the things I agree with. Others
  not. 
* Some of your points in patch 3 are really suggestions
  suggestions for global changes in the manual pages.
  Obviously, they would need discussion, and shouldn't
  be done piecemeal, page at a time. I made some of the
  uncontroversial changes from this patch manually.

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

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

[Michael Kerrisk (man-pages)]

On 5/17/19 5:56 PM, Carlos O'Donell wrote:
> On Fri, May 17, 2019 at 11:51 AM G. Branden Robinson
> <g.branden.robinson@gmail.com> wrote:
>> What would you prefer?  That the man page not document the bug at all?
>> Was it a mistake in your view to have added the information about the
>> bug to the man page in the first place?
> 
> I think having the glibc upstream version information is useful.

And so do I. My compromise in such cases is to write something like:
this:

BUGS
       From  glibc  2.19 to 2.29, pldd was broken: it just hung when exe‐
       cuted.  This problem was fixed in glibc 2.30, and the fix has been
       backported to earlier glibc versions in some distributions.

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

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

[Carlos O'Donell]

On 7/29/19 3:18 PM, Michael Kerrisk (man-pages) wrote:
> On 5/17/19 5:56 PM, Carlos O'Donell wrote:
>> On Fri, May 17, 2019 at 11:51 AM G. Branden Robinson
>> <g.branden.robinson@gmail.com> wrote:
>>> What would you prefer?  That the man page not document the bug at all?
>>> Was it a mistake in your view to have added the information about the
>>> bug to the man page in the first place?
>>
>> I think having the glibc upstream version information is useful.
> 
> And so do I. My compromise in such cases is to write something like:
> this:
> 
> BUGS
>         From  glibc  2.19 to 2.29, pldd was broken: it just hung when exe‐
>         cuted.  This problem was fixed in glibc 2.30, and the fix has been
>         backported to earlier glibc versions in some distributions.
> 
> Thanks,

Thank you for being accurate and informative.

-- 
Cheers,
Carlos.

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

[Michael Kerrisk (man-pages)]

Hello Joseph,

On 5/20/19 6:58 PM, Joseph Myers wrote:
> On Fri, 17 May 2019, Carlos O'Donell wrote:
> 
>> On Fri, May 17, 2019 at 11:51 AM G. Branden Robinson
>> <g.branden.robinson@gmail.com> wrote:
>>> What would you prefer?  That the man page not document the bug at all?
>>> Was it a mistake in your view to have added the information about the
>>> bug to the man page in the first place?
>>
>> I think having the glibc upstream version information is useful.
> 
> Likewise - if a bug is worth documenting there I think it's unavoidable 
> that the version numbers describe when things changed in glibc upstream.
> 
> What's more of an issue is when the BUGS section gets out of date or the 
> descriptions of the conditions for an issue are misleading.  pow(3) is a 
> case in point; it says "On 64-bits" meaning "on systems using the generic 
> implementation" (i.e., it's written from an assumption that x86_64 and 
> i386 are the only architectures and that i386 is the default) and that> issue was fixed in 2.28,

So should the text now read something like: "Before glibc 2.28, on 64-bit
systems [this bug existed]"?

> while the "If x is negative" described there was 
> both i386-specific (not mentioned as such) and fixed in 2.16.

And similarly, should the text now read something like: "On i386 systems
and glibc versions earlier than 2.16..."?

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/