[RFC] Various pages: srcfix. Replace .PD 0 with .TQ.

[RFC] Various pages: srcfix. Replace .PD 0 with .TQ.

[Alejandro Colomar]

Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
---

Hi Branden,

Could you please review this Linux man-pages patch?
If you like it, I'll apply the same changes to all of the pages.

Thanks,

Alex

 man2/bpf.2   | 60 ++++++++++++++++++++++++----------------------------
 man2/fcntl.2 | 12 +++++------
 2 files changed, 33 insertions(+), 39 deletions(-)

diff --git a/man2/bpf.2 b/man2/bpf.2
index 8ae3eae80..155f20e3a 100644
--- a/man2/bpf.2
+++ b/man2/bpf.2
@@ -1075,16 +1075,14 @@ However they may not store kernel pointers within
 the maps and are presently limited to the following helper functions:
 .\" [Linux 5.6] mtk: The list of available functions is, I think, governed
 .\" by the check in net/core/filter.c::bpf_base_func_proto().
-.IP * 3
-get_random
-.PD 0
-.IP *
-get_smp_processor_id
-.IP *
-tail_call
-.IP *
-ktime_get_ns
-.PD 1
+.TP
+* get_random
+.TQ
+* get_smp_processor_id
+.TQ
+* tail_call
+.TQ
+* ktime_get_ns
 .PP
 Unprivileged access may be blocked by writing the value 1 to the file
 .IR /proc/sys/kernel/unprivileged_bpf_disabled .
@@ -1148,40 +1146,38 @@ The JIT compiler for eBPF is currently
 .\" and by checking the documentation for bpf_jit_enable in
 .\" Documentation/sysctl/net.txt
 available for the following architectures:
-.IP * 3
-x86-64 (since Linux 3.18; cBPF since Linux 3.0);
+.TP
+* x86-64 (since Linux 3.18; cBPF since Linux 3.0);
 .\" commit 0a14842f5a3c0e88a1e59fac5c3025db39721f74
-.PD 0
-.IP *
-ARM32 (since Linux 3.18; cBPF since Linux 3.4);
+.TQ
+* ARM32 (since Linux 3.18; cBPF since Linux 3.4);
 .\" commit ddecdfcea0ae891f782ae853771c867ab51024c2
-.IP *
-SPARC 32 (since Linux 3.18; cBPF since Linux 3.5);
+.TQ
+* SPARC 32 (since Linux 3.18; cBPF since Linux 3.5);
 .\" commit 2809a2087cc44b55e4377d7b9be3f7f5d2569091
-.IP *
-ARM-64 (since Linux 3.18);
+.TQ
+* ARM-64 (since Linux 3.18);
 .\" commit e54bcde3d69d40023ae77727213d14f920eb264a
-.IP *
-s390 (since Linux 4.1; cBPF since Linux 3.7);
+.TQ
+* s390 (since Linux 4.1; cBPF since Linux 3.7);
 .\" commit c10302efe569bfd646b4c22df29577a4595b4580
-.IP *
-PowerPC 64 (since Linux 4.8; cBPF since Linux 3.1);
+.TQ
+* PowerPC 64 (since Linux 4.8; cBPF since Linux 3.1);
 .\" commit 0ca87f05ba8bdc6791c14878464efc901ad71e99
 .\" commit 156d0e290e969caba25f1851c52417c14d141b24
-.IP *
-SPARC 64 (since Linux 4.12);
+.TQ
+* SPARC 64 (since Linux 4.12);
 .\" commit 7a12b5031c6b947cc13918237ae652b536243b76
-.IP *
-x86-32 (since Linux 4.18);
+.TQ
+* x86-32 (since Linux 4.18);
 .\" commit 03f5781be2c7b7e728d724ac70ba10799cc710d7
-.IP *
-MIPS 64 (since Linux 4.18; cBPF since Linux 3.16);
+.TQ
+* MIPS 64 (since Linux 4.18; cBPF since Linux 3.16);
 .\" commit c6610de353da5ca6eee5b8960e838a87a90ead0c
 .\" commit f381bf6d82f032b7410185b35d000ea370ac706b
-.IP *
-riscv (since Linux 5.1).
+.TQ
+* riscv (since Linux 5.1).
 .\" commit 2353ecc6f91fd15b893fa01bf85a1c7a823ee4f2
-.PD
 .SH EXAMPLES
 .\" [[FIXME]] SRC BEGIN (bpf.c)
 .EX
diff --git a/man2/fcntl.2 b/man2/fcntl.2
index e01a02d86..0b4ae51fe 100644
--- a/man2/fcntl.2
+++ b/man2/fcntl.2
@@ -1209,7 +1209,6 @@ which is a bit mask specified by ORing together zero or more of
 the following bits:
 .PP
 .RS
-.PD 0
 .TP
 .B DN_ACCESS
 A file was accessed
@@ -1217,7 +1216,7 @@ A file was accessed
 .BR pread (2),
 .BR readv (2),
 and similar)
-.TP
+.TQ
 .B DN_MODIFY
 A file was modified
 .RB ( write (2),
@@ -1226,7 +1225,7 @@ A file was modified
 .BR truncate (2),
 .BR ftruncate (2),
 and similar).
-.TP
+.TQ
 .B DN_CREATE
 A file was created
 .RB ( open (2),
@@ -1237,18 +1236,18 @@ A file was created
 .BR symlink (2),
 .BR rename (2)
 into this directory).
-.TP
+.TQ
 .B DN_DELETE
 A file was unlinked
 .RB ( unlink (2),
 .BR rename (2)
 to another directory,
 .BR rmdir (2)).
-.TP
+.TQ
 .B DN_RENAME
 A file was renamed within this directory
 .RB ( rename (2)).
-.TP
+.TQ
 .B DN_ATTRIB
 The attributes of a file were changed
 .RB ( chown (2),
@@ -1256,7 +1255,6 @@ The attributes of a file were changed
 .BR utime (2),
 .BR utimensat (2),
 and similar).
-.PD
 .RE
 .IP
 (In order to obtain these definitions, the
-- 
2.36.1

Re: [RFC] Various pages: srcfix. Replace .PD 0 with .TQ.

[G. Branden Robinson]

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

Hi, Alex!

At 2022-05-21T17:00:41+0200, Alejandro Colomar wrote:
> Hi Branden,
> 
> Could you please review this Linux man-pages patch?
> If you like it, I'll apply the same changes to all of the pages.

I am uncertain about this change.  I like the idea of getting rid of
`PD` calls, but I think there in value in having `TQ` possess semantics
of "here is another tag that is related to the previous one after a TP
call".

You are (ab)using TQ here to avoid inter-paragraph space.  As I noted in
a message of a few minutes ago on the groff mailing list[1], it might be
better to wait for what settles out of a discussion of the `BL` /`EL`
macro pair I have (not yet formally) proposed for a post-1.23.0 groff
man(7) extension.

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2022-05/

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

Re: [RFC] Various pages: srcfix. Replace .PD 0 with .TQ.

[Alejandro Colomar]

Hi Branden,

On 5/21/22 17:28, G. Branden Robinson wrote:
> I am uncertain about this change.  I like the idea of getting rid of
> `PD` calls, but I think there in value in having `TQ` possess semantics
> of "here is another tag that is related to the previous one after a TP
> call".

Agree.  I prefer to keep the meaning of TQ as a continuation of TP.

> You are (ab)using TQ here to avoid inter-paragraph space.  As I noted in
> a message of a few minutes ago on the groff mailing list[1], it might be
> better to wait for what settles out of a discussion of the `BL` /`EL`
> macro pair I have (not yet formally) proposed for a post-1.23.0 groff
> man(7) extension.

I tend to agree with the necessity for a list macro, and I never liked 
lists written as

.TP
item1
.TQ
item2
.TQ
item3

Because that looks like an abuse of tagged paragraph macros, where they 
completely lost their original meaning (there aren't even paragraphs in 
that list!).  And yet we have that code in the Linux man-pages.

I like your idea of BL/EL[1].  Will wait for your release :)

Regards,

Alex


[1]: <https://git.savannah.gnu.org/cgit/groff.git/tree/man/groff.7.man#n225>

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/