[PATCH] rpc.5: ffix

[PATCH] rpc.5: ffix

[G. Branden Robinson]

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

Is there a recommended best practice for itemized (but not enumerated)
lists?  I don't know that my own is widely shared, so I did not make
such a change here.

But if I were to do so, I would either recast this page's 3-item list
into prose or use the indented paragraph macro with a bullet symbol for
a tag:

.IP \(bu
name of server for the RPC program
.IP \(bu
RPC program number
.IP \(bu
aliases

Of course,

.TP
\(bu
name of server for the RPC program
[etc.]

would be equivalent.

Any advice?

>SNIP<

rpc.5: ffix

* Remove nop argument from HP macros.
* Remove nop DT macro.
* Replace LP macro with more commonly-used PP macro.

The above do not change the output whatsoever (confirmed with -Z).

* Use .I macro instead of font escapes, obtaining italic correction.

To see the above distinction, use -Tps, -Tpdf, or similar before and
after the change.

diff --git a/man5/rpc.5 b/man5/rpc.5
index 44b5acb0e..49831fd78 100644
--- a/man5/rpc.5
+++ b/man5/rpc.5
@@ -16,25 +16,26 @@ The
 file contains user readable names that
 can be used in place of RPC program numbers.
 Each line has the following information:
-.HP 10
+.HP
 name of server for the RPC program
 .br
 .ns
-.HP 10
+.HP
 RPC program number
 .br
 .ns
-.HP 10
+.HP
 aliases
-.LP
+.PP
 Items are separated by any number of blanks and/or
 tab characters.
 A \(aq#\(aq indicates the beginning of a comment; characters from
 the \(aq#\(aq to the end of the line are not interpreted by routines
 which search the file.
-.LP
-Here is an example of the \fI/etc/rpc\fP file from the Sun RPC Source
-distribution.
+.PP
+Here is an example of the
+.I /etc/rpc
+file from the Sun RPC Source distribution.
 .ft CW
 .nf
 #
@@ -72,7 +73,6 @@ nsed            100038
 nsemntd         100039
 .fi
 .ft
-.DT
 .SH FILES
 .TP
 .I /etc/rpc

Regards,
Branden

[-- Attachment #1.2: man-pages-rpc5-ffix.diff --]
[-- Type: text/x-diff, Size: 1567 bytes --]

commit 1f173880b25aa60a9bf838f7c4738f8dc0372959
Author: G. Branden Robinson <g.branden.robinson-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
Date:   Fri May 5 23:12:44 2017 -0400

    rpc.5: ffix
    
    * Remove nop argument from HP macros.
    * Remove nop DT macro.
    * Replace LP macro with more commonly-used PP macro.
    
    The above do not change the output whatsoever (confirmed with -Z).
    
    * Use .I macro instead of font escapes, obtaining italic correction.
    
    To see the above distinction, use -Tps, -Tpdf, or similar before and
    after the change.

diff --git a/man5/rpc.5 b/man5/rpc.5
index 44b5acb0e..49831fd78 100644
--- a/man5/rpc.5
+++ b/man5/rpc.5
@@ -16,25 +16,26 @@ The
 file contains user readable names that
 can be used in place of RPC program numbers.
 Each line has the following information:
-.HP 10
+.HP
 name of server for the RPC program
 .br
 .ns
-.HP 10
+.HP
 RPC program number
 .br
 .ns
-.HP 10
+.HP
 aliases
-.LP
+.PP
 Items are separated by any number of blanks and/or
 tab characters.
 A \(aq#\(aq indicates the beginning of a comment; characters from
 the \(aq#\(aq to the end of the line are not interpreted by routines
 which search the file.
-.LP
-Here is an example of the \fI/etc/rpc\fP file from the Sun RPC Source
-distribution.
+.PP
+Here is an example of the
+.I /etc/rpc
+file from the Sun RPC Source distribution.
 .ft CW
 .nf
 #
@@ -72,7 +73,6 @@ nsed            100038
 nsemntd         100039
 .fi
 .ft
-.DT
 .SH FILES
 .TP
 .I /etc/rpc

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

Re: [PATCH] rpc.5: ffix

[Michael Kerrisk (man-pages)]

Hello Branden,

On 05/06/2017 05:26 AM, G. Branden Robinson wrote:
> Is there a recommended best practice for itemized (but not enumerated)
> lists?  I don't know that my own is widely shared, so I did not make
> such a change here.

Not really any standard, but the existing formatting is certainly suboptimal.
I applied your patch, and then made a change more or less as you suggest
below.

Cheers,

Michael


> But if I were to do so, I would either recast this page's 3-item list
> into prose or use the indented paragraph macro with a bullet symbol for
> a tag:
> 
> .IP \(bu
> name of server for the RPC program
> .IP \(bu
> RPC program number
> .IP \(bu
> aliases
> 
> Of course,
> 
> .TP
> \(bu
> name of server for the RPC program
> [etc.]
> 
> would be equivalent.
> 
> Any advice?
> 
>> SNIP<
> 
> rpc.5: ffix
> 
> * Remove nop argument from HP macros.
> * Remove nop DT macro.
> * Replace LP macro with more commonly-used PP macro.
> 
> The above do not change the output whatsoever (confirmed with -Z).
> 
> * Use .I macro instead of font escapes, obtaining italic correction.
> 
> To see the above distinction, use -Tps, -Tpdf, or similar before and
> after the change.
> 
> diff --git a/man5/rpc.5 b/man5/rpc.5
> index 44b5acb0e..49831fd78 100644
> --- a/man5/rpc.5
> +++ b/man5/rpc.5
> @@ -16,25 +16,26 @@ The
>  file contains user readable names that
>  can be used in place of RPC program numbers.
>  Each line has the following information:
> -.HP 10
> +.HP
>  name of server for the RPC program
>  .br
>  .ns
> -.HP 10
> +.HP
>  RPC program number
>  .br
>  .ns
> -.HP 10
> +.HP
>  aliases
> -.LP
> +.PP
>  Items are separated by any number of blanks and/or
>  tab characters.
>  A \(aq#\(aq indicates the beginning of a comment; characters from
>  the \(aq#\(aq to the end of the line are not interpreted by routines
>  which search the file.
> -.LP
> -Here is an example of the \fI/etc/rpc\fP file from the Sun RPC Source
> -distribution.
> +.PP
> +Here is an example of the
> +.I /etc/rpc
> +file from the Sun RPC Source distribution.
>  .ft CW
>  .nf
>  #
> @@ -72,7 +73,6 @@ nsed            100038
>  nsemntd         100039
>  .fi
>  .ft
> -.DT
>  .SH FILES
>  .TP
>  .I /etc/rpc
> 
> Regards,
> Branden
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html