Patchwork pldd.1: Document glibc's unbreakage of tool.

login
register
mail settings
Submitter G. Branden Robinson
Date May 11, 2019, 7:20 a.m.
Message ID <20190511072049.2w7pp723iszp3gra@localhost.localdomain>
Download mbox | patch
Permalink /patch/32643/
State New
Headers show

Comments

G. Branden Robinson - May 11, 2019, 7:20 a.m.
...plus a patch with some suggested wording fixes.

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

Regards,
Branden
Florian Weimer - May 13, 2019, 9:48 a.m.
* 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
G. Branden Robinson - May 13, 2019, 2:17 p.m.
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
walter harms - May 13, 2019, 2:34 p.m.
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
Florian Weimer - May 17, 2019, 3:44 p.m.
* 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
G. Branden Robinson - May 17, 2019, 3:51 p.m.
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
Carlos O'Donell - May 17, 2019, 3:56 p.m.
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.
Joseph Myers - May 20, 2019, 4:58 p.m.
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.

Patch

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