queue.3: Comment out text for functions not in glibc (related: 6559169cac)
PATCH 1/1 queue.3: Comment out text for functions not in glibc (related: 6559169cac)
===========
DESCRIPTION
===========
I'm documenting ``CIRCLEQ_*`` macros in queue.3. While writing this, I noticed that the documentation for some types of queues/lists talked about swapping contents of two lists, but only for some of them. I then found that those macros (``*_SWAP``) don't exist in my system (Debian), but exist in BSD, and I also found that a previous commit (6559169cac) commented out a lot of the *_SWAP macros documentation, but not all, and the reason was that they were not present on glibc.
I checked that I didn't have any of the *_SWAP macros on my glibc, so I think this is probably that the commit simply forgot to comment some of them.
=======
TESTING
=======
I tun ``sudo make`` and then visualized the man page with ``man 3 queue``, and the changes looked good.
I also noticed that the subsection ``Tail queue example`` contents were wrong, as they contained calls to CIRCLEQ_* macros. I will address that in a future patch, before I submit the patch documenting CIRCLEQ_*.
________________________________________________________________________P.S.: I'd like to know, as my previous patch was oddly reformatted by my mailer, if you can see it correctly this time. I changed some, configuration, so I hope it is fine.
=====
PATCH
=====
From 2282ba2397e6ac7dca4cc09dfcb92ac524718f27 Mon Sep 17 00:00:00 2001
From: Alejandro Colomar <[email protected]>
Date: Sun, 26 Jul 2020 23:36:42 +0200
Subject: [PATCH] queue.3: Comment out text for functions not in glibc
(related: 6559169cac)
--- man3/queue.3 | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-)
man3/queue.3 +3 -3
@@ -110,8 +110,8 @@ .Nm TAILQ_LAST , .Nm TAILQ_NEXT , .Nm TAILQ_PREV , -.Nm TAILQ_REMOVE , -.Nm TAILQ_SWAP +.Nm TAILQ_REMOVE +.\" .Nm TAILQ_SWAP .Nd implementations of singly-linked lists, singly-linked tail queues, lists and tail queues .Sh SYNOPSIS
@@ -172,7 +172,7 @@ lists and tail queues .Fn LIST_NEXT "TYPE *elm" "LIST_ENTRY NAME" .\" .Fn LIST_PREV "TYPE *elm" "LIST_HEAD *head" "TYPE" "LIST_ENTRY NAME" .Fn LIST_REMOVE "TYPE *elm" "LIST_ENTRY NAME" -.Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" +.\" .Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" .\" .Fn TAILQ_CONCAT "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TAILQ_ENTRY
NAME"
.Fn TAILQ_EMPTY "TAILQ_HEAD *head"
@@ -197,7 +197,7 @@ lists and tail queues
.Fn TAILQ_NEXT "TYPE *elm" "TAILQ_ENTRY NAME"
.Fn TAILQ_PREV "TYPE *elm" "HEADNAME" "TAILQ_ENTRY NAME"
.Fn TAILQ_REMOVE "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME"
-.Fn TAILQ_SWAP "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TYPE" "TAILQ_ENTRY NAME" +.\" .Fn TAILQ_SWAP "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TYPE" "TAILQ_ENTRY NAME"
.\"
.Sh DESCRIPTION
These macros define and operate on four types of data structures:
@@ -213,8 +213,8 @@ Insertion of a new entry after any element in the list.
O(1) removal of an entry from the head of the list.
.It
Forward traversal through the list.
-.It
-Swapping the contents of two lists.
+.\" .It
+.\" Swapping the contents of two lists.
.El
.Pp
Singly-linked lists are the simplest of the four data structures
@@ -1157,13 +1157,13 @@ The macro
removes the element
.Fa elm
from the tail queue.
-.Pp
-The macro
-.Nm TAILQ_SWAP
-swaps the contents of
-.Fa head1
-and
-.Fa head2 .
+.\" .Pp
+.\" The macro
+.\" .Nm TAILQ_SWAP
+.\" swaps the contents of
+.\" .Fa head1
+.\" and
+.\" .Fa head2 .
.Ss Tail queue example
.Bd -literal
TAILQ_HEAD(tailhead, entry) head =
Signature · 1 line
2.27.0
Hello Alejandro,
Quoted 23 lines · Alejandro Colomar
===========
DESCRIPTION
===========I'm documenting ``CIRCLEQ_*`` macros in queue.3. While writing this, I noticed that the documentation for some types of queues/lists talked about swapping contents of two lists, but only for some of them. I then found that those macros (``*_SWAP``) don't exist in my system (Debian), but exist in BSD, and I also found that a previous commit (
6559169cac) commented out a lot of the*_SWAPmacros documentation, but not all, and the reason was that they were not present on glibc.I checked that I didn't have any of the
*_SWAPmacros on my glibc, so I think this is probably that the commit simply forgot to comment some of them.=======
TESTING
=======I tun ``sudo make`` and then visualized the man page with ``man 3 queue``, and the changes looked good.
Quoted 8 lines
I also noticed that the subsection ``Tail queue example`` contents were wrong, as they contained calls to CIRCLEQ_* macros. I will address that in a future patch, before I submit the patch documenting CIRCLEQ_*.
________________________________________________________________________
P.S.: I'd like to know, as my previous patch was oddly reformatted by my mailer, if you can see it correctly this time. I changed some, configuration, so I hope it is fine.
All pretty good this time. I applied your patch. Two things to note:
* There was some superfluous whitespace at the end of some of the changed lines. By chance, that got automatically fixed up. No big problem, but it generates a bit of unnecessary noise when applying the patch [1]
* I added the following on your hehalf:
Thanks,
Michael
Quoted 85 lines
=====
PATCH
=====From
2282ba2397e6ac7dca4cc09dfcb92ac524718f27Mon Sep 17 00:00:00 2001
From: Alejandro Colomar <[email protected]>
Date: Sun, 26 Jul 2020 23:36:42 +0200
Subject: [PATCH] queue.3: Comment out text for functions not in glibc
(related:6559169cac)--- man3/queue.3 | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-)man3/queue.3 +2
-3@@ -110,8 +110,8 @@ .Nm TAILQ_LAST , .Nm TAILQ_NEXT , .Nm TAILQ_PREV , -.Nm TAILQ_REMOVE , -.Nm TAILQ_SWAP +.Nm TAILQ_REMOVE +.\" .Nm TAILQ_SWAP .Nd implementations of singly-linked lists, singly-linked tail queues, lists and tail queues .Sh SYNOPSIS@@ -172,7 +172,7 @@ lists and tail queues .Fn LIST_NEXT "TYPE *elm" "LIST_ENTRY NAME" .\" .Fn LIST_PREV "TYPE *elm" "LIST_HEAD *head" "TYPE" "LIST_ENTRY NAME" .Fn LIST_REMOVE "TYPE *elm" "LIST_ENTRY NAME" -.Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRYNAME"
+.\" .FnLIST_SWAP"LIST_HEAD*head1" "LIST_HEAD*head2" "TYPE" "LIST_ENTRYNAME"
.\"
.FnTAILQ_CONCAT"TAILQ_HEAD*head1" "TAILQ_HEAD*head2" "TAILQ_ENTRY
NAME"
.FnTAILQ_EMPTY"TAILQ_HEAD*head"man3/queue.3 +0
-1@@ -197,7 +197,7 @@ lists and tail queues .Fn TAILQ_NEXT "TYPE *elm" "TAILQ_ENTRY NAME" .Fn TAILQ_PREV "TYPE *elm" "HEADNAME" "TAILQ_ENTRY NAME" .Fn TAILQ_REMOVE "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" -.Fn TAILQ_SWAP "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TYPE""
TAILQ_ENTRYNAME"
+.\" .FnTAILQ_SWAP"TAILQ_HEAD*head1" "TAILQ_HEAD*head2" "TYPE" "TAILQ_ENTRYNAME"
.\"
.Sh DESCRIPTION
These macros define and operate on four types of data structures:man3/queue.3 +9
-9@@ -213,8 +213,8 @@ Insertion of a new entry after any element in the list. O(1) removal of an entry from the head of the list. .It Forward traversal through the list. -.It -Swapping the contents of two lists. +.\" .It +.\" Swapping the contents of two lists. .El .Pp Singly-linked lists are the simplest of the four data structures@@ -1157,13 +1157,13 @@ The macro removes the element .Fa elm from the tail queue. -.Pp -The macro -.Nm TAILQ_SWAP -swaps the contents of -.Fa head1 -and -.Fa head2 . +.\" .Pp +.\" The macro +.\" .Nm TAILQ_SWAP +.\" swaps the contents of +.\" .Fa head1 +.\" and +.\" .Fa head2 . .Ss Tail queue example .Bd -literal TAILQ_HEAD(tailhead, entry) head =
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/