From 6253e7d6ecee4130592748a2f59f0c23567b4670 Mon Sep 17 00:00:00 2001
From: Alejandro Colomar <colomar.6.4.3@gmail.com>
Date: Tue, 4 Aug 2020 11:40:41 +0200
Subject: [PATCH] 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 did ``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_*.

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 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 =