* [patch] queue.3: Comment out text for functions not in glibc (related: 6559169cac)
@ 2020-08-04 9:40 Alejandro Colomar
2020-08-04 12:48 ` Michael Kerrisk (man-pages)
0 siblings, 1 reply; 2+ messages in thread
From: Alejandro Colomar @ 2020-08-04 9:40 UTC (permalink / raw)
To: linux-man; +Cc: libc-alpha
===========
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 <colomar.6.4.3@gmail.com>
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(-)
diff --git a/man3/queue.3 b/man3/queue.3
index 00e4b1958..ff1f42f3a 100644
--- a/man3/queue.3
+++ b/man3/queue.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 =
--
2.27.0
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [patch] queue.3: Comment out text for functions not in glibc (related: 6559169cac)
2020-08-04 9:40 [patch] queue.3: Comment out text for functions not in glibc (related: 6559169cac) Alejandro Colomar
@ 2020-08-04 12:48 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 2+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-08-04 12:48 UTC (permalink / raw)
To: Alejandro Colomar, linux-man; +Cc: mtk.manpages, libc-alpha
Hello Alejandro,
On 8/4/20 11:40 AM, Alejandro Colomar wrote:
> ===========
> 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.
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:
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Thanks,
Michael
> =====
> PATCH
> =====
>
> From 2282ba2397e6ac7dca4cc09dfcb92ac524718f27 Mon Sep 17 00:00:00 2001
> From: Alejandro Colomar <colomar.6.4.3@gmail.com>
> 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(-)
>
> diff --git a/man3/queue.3 b/man3/queue.3
> index 00e4b1958..ff1f42f3a 100644
> --- a/man3/queue.3
> +++ b/man3/queue.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 =
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2020-08-04 12:49 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-08-04 9:40 [patch] queue.3: Comment out text for functions not in glibc (related: 6559169cac) Alejandro Colomar
2020-08-04 12:48 ` Michael Kerrisk (man-pages)
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).