[DTrace-devel] [PATCH 3/7] man: fix manpage

[Eugene Loh]

Reviewed-by: Eugene Loh <eugene.loh at oracle.com>
with two extremely picky comments below...

On 12/6/22 16:50, Kris Van Hees via DTrace-devel wrote:
> diff --git a/cmd/dtrace.1 b/cmd/dtrace.8
> @@ -1,511 +1,202 @@
>   '\" te
>   .\" Oracle Linux DTrace.
> -.\" Copyright (c) 2009, 2014, Oracle and/or its affiliates. All Rights Reserved.
> +.\" Copyright (c) 2009, 2022, Oracle and/or its affiliates. All Rights Reserved.
>   .\" Licensed under the Universal Permissive License v 1.0 as shown at
>   .\" http://oss.oracle.com/licenses/upl.
> -.TH dtrace 1M "22 Oct 2014" "Oracle Linux" "Linux Programmer's Manual"
> +.TH dtrace 8 "22 Oct 2014" "Oracle Linux" "Linux Programmer's Manual"
>   .SH NAME
>   dtrace \- DTrace dynamic tracing compiler and tracing utility
>   .SH SYNOPSIS
> -.LP
> -.nf
> -\fBdtrace\fR [\fB-CeFGHhlqSvVwZ\fR] [\fB-b\fR \fIbufsz\fR] [\fB-c\fR \fIcmd\fR]
> -     [\fB-D\fR \fIname\fR [\fI=value\fR]] [\fB-I\fR \fIpath\fR] [\fB-L\fR \fIpath\fR] [\fB-o\fR \fIoutput\fR]
> -     [\fB-s\fR \fIscript\fR] [\fB-U\fR \fIname\fR] [\fB-x\fR \fIarg\fR [\fI=val\fR]]
> -     [\fB-X\fR a | c | s | t] [\fB-p\fR \fIpid\fR]
> -     [\fB-P\fR \fIprovider\fR [[\fIpredicate\fR] \fIaction\fR]]
> -     [\fB-m\fR [\fIprovider:\fR] \fImodule\fR [[\fIpredicate\fR] \fIaction\fR]]
> -     [\fB-f\fR [[\fIprovider:\fR] \fImodule:\fR] \fIfunction\fR [[\fIpredicate\fR] \fIaction\fR]]
> -     [\fB-n\fR [[[\fIprovider:\fR] \fImodule:\fR] \fIfunction:\fR] \fIname\fR [[\fIpredicate\fR] \fIaction\fR]]
> -     [\fB-i\fR \fIprobe-id\fR [[\fIpredicate\fR] \fIaction\fR]]
> -.fi
> +.SY dtrace
> +.OP \-CeFGHhlqSvVwZ
> +.OP \-b bufsz
> +.OP \-c cmd
> +.br
> +.OP \-D name\ [=value]
> +.OP \-I path
> +.OP \-L path
> +.OP \-o output
> +.br
> +.OP \-s script
> +.OP \-U name
> +.OP \-x arg\ [=val]
> +.br
> +.OP \-X a\ |\ c\ |\ s\ |\ t
> +.OP \-p pid
> +.br
> +.OP \-P provider\ [[predicate]\ action]
> +.br
> +.OP \-m [provider\:]\ module\ [[predicate]\ action]
> +.br
> +.OP \-f [[provider\:]\ module\:]\ function\ [[predicate]\ action]
> +.br
> +.OP \-n [[[provider\:]\ module\:]\ function\:]name\ [[predicate]\ action]
> +.br
> +.OP \-i probe-id\ [[predicate]\ action]
> +.SY

The formatting is really hard to read, but I think it ultimately boils 
down to this:

         dtrace [-CeFGHhlqSvVwZ] [-b bufsz] [-c cmd]
                [-D name [=value]] [-I path] [-L path] [-o output]
                [-s script] [-U name] [-x arg [=val]]
                [-X a | c | s | t] [-p pid]
                [-P provider [[predicate] action]]
-              [-m [provider:] module [[predicate] action]]
+              [-m [provider] module [[predicate] action]]
-              [-f [[provider:] module:] function [[predicate] action]]
+              [-f [[provider] module] function [[predicate] action]]
-              [-n [[[provider:] module:] function:] name [[predicate] 
action]]
+              [-n [[[provider] module] function]name [[predicate] action]]
                [-i probe-id [[predicate] action]]

Consider the -m option.  Here, "provider:" has lost its colon; why?  And 
both before and after the patch, there is a space between the provider 
and the module;  why?  In reality, it isn't "provider module" but 
"provider:module".

Same for the -f option.  Both "provider:" and "module:" lose their 
colons.  And there are spaces in the probe descriptions (between 
provider, module, and function).

Similarly for the -n option, although this time there is no space 
between the function and probe name.

> [...many lines deleted...]
>
>   \fB\fB-o\fR \fIoutput\fR\fR
> -.ad
> -.sp .6
> -.RS 4n
>   Specify the \fIoutput\fR file for the \fB-G\fR,  \fB-h\fR, and \fB-l\fR options, or for the traced data itself. If the \fB-G\fR option is present and the \fB-s\fR option's argument is of the form \fB\fIfilename\fR.d\fR and \fB-o\fR is not present, the default output file is \fB\fIfilename\fR.o\fR. Otherwise the default output file is \fBd.out\fR.

That "output" line hasn't changed, but there is an extraneous space 
between -G and -h.  The man page used to be full of such things but (if 
I understand correctly) the style has changed so that the right-hand 
margin is no longer justified and therefore there is no more padding 
inside each line.  So, that extraneous space now sticks out.