Skip to contentSkip to conversation

circleq.3, list.3, slist.3, stailq.3, tailq.3: Improve readability, especially in SYNOPSIS

PATCH Superseded Alejandro Colomar 3 participants 11 messages Jan 4, 2021 – Nov 3, 2024 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 circleq.3, list.3, slist.3, stailq.3, tailq.3: Improve readability, especially in SYNOPSIS

- Group macros by kinds.
- Align so that it's easiest to distinguish differences between related macros.
- Fix minor typos.
- Remove redundant text ('The macro xxx() ...'):
The first paragraph already says that these are macros.
- Fit lines into 78 columns.

I noticed a bug which should be fixed next:
CIRCLEQ_LOOP_*() return a 'struct TYPE *'.

---

Hi Michael,

Here's my attempt of making queue.3 pages more readable. I think it's quite nicer now.
But please, review it, because I may have introduced a few bugs while moving the text around.
Also, if you feel something could be nicer, please tell me.

BTW, it's been the first time I use Vim for something not trivial, and I quite liked it.
I think I'll stop using Gedit for a while :-)

Cheers,

Alex

 man3/circleq.3 |  77 +++++++++++++----------------------
 man3/list.3    |  59 ++++++++++++---------------
 man3/slist.3   |  58 ++++++++++++---------------
 man3/stailq.3  |  76 +++++++++++++++--------------------
 man3/tailq.3   | 106 +++++++++++++++++++++----------------------------
 5 files changed, 154 insertions(+), 222 deletions(-)
man3/circleq.3 +27 -50
index 49c7bad66..97f290cbd 100644
@@ -54,43 +54,39 @@ CIRCLEQ_REMOVE
 .nf
 .B #include <sys/queue.h>
 .PP
-.BI "int CIRCLEQ_EMPTY(CIRCLEQ_HEAD *" head ");"
-.PP
 .B CIRCLEQ_ENTRY(TYPE);
 .PP
-.BI "struct TYPE *CIRCLEQ_FIRST(CIRCLEQ_HEAD *" head ");"
-.PP
-.BI "CIRCLEQ_FOREACH(struct TYPE *" var ", CIRCLEQ_HEAD *" head ,
-.BI "                CIRCLEQ_ENTRY " NAME ");"
-.BI "CIRCLEQ_FOREACH_REVERSE(struct TYPE *" var ", CIRCLEQ_HEAD *" head ","
-.BI "                CIRCLEQ_ENTRY " NAME ");"
-.PP
 .B CIRCLEQ_HEAD(HEADNAME, TYPE);
-.BI "CIRCLEQ_HEAD CIRCLEQ_HEAD_INITIALIZER(CIRCLEQ_HEAD " head ");"
-.BI "void CIRCLEQ_INIT(CIRCLEQ_HEAD *" head ");"
-.PP
-.BI "void CIRCLEQ_INSERT_AFTER(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm ,
-.BI "                struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
-.BI "void CIRCLEQ_INSERT_BEFORE(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm ,
-.BI "                struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
+.BI "CIRCLEQ_HEAD CIRCLEQ_HEAD_INITIALIZER(CIRCLEQ_HEAD " head );
+.BI "void CIRCLEQ_INIT(CIRCLEQ_HEAD *" head );
 .PP
-.BI "void CIRCLEQ_INSERT_HEAD(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ","
-.BI "                CIRCLEQ_ENTRY " NAME ");"
-.BI "void CIRCLEQ_INSERT_TAIL(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ","
-.BI "                CIRCLEQ_ENTRY " NAME ");"
+.BI "int CIRCLEQ_EMPTY(CIRCLEQ_HEAD *" head );
 .PP
-.BI "struct TYPE *CIRCLEQ_LAST(CIRCLEQ_HEAD *" head ");"
+.BI "void CIRCLEQ_INSERT_HEAD(CIRCLEQ_HEAD *" head ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "void CIRCLEQ_INSERT_TAIL(CIRCLEQ_HEAD *" head ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "void CIRCLEQ_INSERT_BEFORE(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "void CIRCLEQ_INSERT_AFTER(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
 .PP
-.BI "void CIRCLEQ_LOOP_NEXT(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ","
-.BI "                CIRCLEQ_ENTRY " NAME ");"
-.BI "void CIRCLEQ_LOOP_PREV(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ","
-.BI "                CIRCLEQ_ENTRY " NAME ");"
+.BI "struct TYPE *CIRCLEQ_FIRST(CIRCLEQ_HEAD *" head );
+.BI "struct TYPE *CIRCLEQ_LAST(CIRCLEQ_HEAD *" head );
+.BI "struct TYPE *CIRCLEQ_PREV(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "struct TYPE *CIRCLEQ_NEXT(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "void CIRCLEQ_LOOP_PREV(CIRCLEQ_HEAD *" head ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "void CIRCLEQ_LOOP_NEXT(CIRCLEQ_HEAD *" head ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
 .PP
-.BI "struct TYPE *CIRCLEQ_NEXT(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
-.BI "struct TYPE *CIRCLEQ_PREV(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
+.BI "CIRCLEQ_FOREACH(struct TYPE *" var ", CIRCLEQ_HEAD *" head ,
+.BI "                        CIRCLEQ_ENTRY " NAME );
+.BI "CIRCLEQ_FOREACH_REVERSE(struct TYPE *" var ", CIRCLEQ_HEAD *" head ,
+.BI "                        CIRCLEQ_ENTRY " NAME );
 .PP
 .BI "void CIRCLEQ_REMOVE(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ,
-.BI "                CIRCLEQ_ENTRY " NAME ");"
+.BI "                    CIRCLEQ_ENTRY " NAME );
 .fi
 .SH DESCRIPTION
 These macros define and operate on doubly linked circular queues.
@@ -148,25 +144,20 @@ and
 .I headp
 are user selectable.)
 .PP
-The macro
 .BR CIRCLEQ_HEAD_INITIALIZER ()
 evaluates to an initializer for the circular queue
 .IR head .
 .PP
-The macro
 .BR CIRCLEQ_EMPTY ()
 evaluates to true if there are no items on the circular queue.
 .PP
-The macro
 .BR CIRCLEQ_ENTRY ()
 declares a structure that connects the elements in
 the circular queue.
 .PP
-The macro
 .BR CIRCLEQ_FIRST ()
 returns the first item on the circular queue.
 .PP
-The macro
 .BR CIRCLEQ_FOREACH ()
 traverses the circular queue referenced by
 .I head
@@ -177,75 +168,63 @@ is set to
 .I &head
 if the loop completes normally, or if there were no elements.
 .PP
-The macro
 .BR CIRCLEQ_FOREACH_REVERSE ()
 traverses the circular queue referenced by
 .I head
 in the reverse direction, assigning each element in turn to
 .IR var .
 .PP
-The macro
 .BR CIRCLEQ_INIT ()
 initializes the circular queue referenced by
 .IR head .
 .PP
-The macro
 .BR CIRCLEQ_INSERT_HEAD ()
 inserts the new element
 .I elm
 at the head of the circular queue.
 .PP
-The macro
 .BR CIRCLEQ_INSERT_TAIL ()
 inserts the new element
 .I elm
 at the end of the circular queue.
 .PP
-The macro
 .BR CIRCLEQ_INSERT_AFTER ()
 inserts the new element
 .I elm
 after the element
 .IR listelm .
 .PP
-The macro
 .BR CIRCLEQ_INSERT_BEFORE ()
 inserts the new element
 .I elm
 before the element
 .IR listelm .
 .PP
-The macro
 .BR CIRCLEQ_LAST ()
 returns the last item on the circular queue.
 .PP
-The macro
 .BR CIRCLEQ_NEXT ()
 returns the next item on the circular queue, or
 .I &head
 if this item is the last one.
 .PP
-The macro
 .BR CIRCLEQ_PREV ()
 returns the previous item on the circular queue, or
 .I &head
 if this item is the first one.
 .PP
-The macro
 .BR CIRCLEQ_LOOP_NEXT ()
 returns the next item on the circular queue.
 If
 .I elm
 is the last element on the circular queue, the first element is returned.
 .PP
-The macro
 .BR CIRCLEQ_LOOP_PREV ()
 returns the previous item on the circular queue.
 If
 .I elm
 is the first element on the circular queue, the last element is returned.
 .PP
-The macro
 .BR CIRCLEQ_REMOVE ()
 removes the element
 .I elm
@@ -257,10 +236,10 @@ and zero if the queue contains at least one entry.
 .PP
 .BR CIRCLEQ_FIRST (),
 .BR CIRCLEQ_LAST (),
-.BR CIRCLEQ_NEXT (),
+.BR CIRCLEQ_PREV (),
 and
-.BR CIRCLEQ_PREV ()
-return a pointer to the first, last, next or previous
+.BR CIRCLEQ_NEXT ()
+return a pointer to the first, last, previous or next
 .I TYPE
 structure, respectively.
 .PP
@@ -272,7 +251,6 @@ Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008.
 Present on the BSDs
 (CIRCLEQ macros first appeared in 4.4BSD).
 .SH BUGS
-The macros
 .BR CIRCLEQ_FOREACH ()
 and
 .BR CIRCLEQ_FOREACH_REVERSE ()
@@ -280,7 +258,6 @@ don't allow
 .I var
 to be removed or freed within the loop,
 as it would interfere with the traversal.
-The macros
 .BR CIRCLEQ_FOREACH_SAFE ()
 and
 .BR CIRCLEQ_FOREACH_REVERSE_SAFE (),
man3/list.3 +25 -34

143 lines not on this page · raw message

man3/slist.3 +25 -33

135 lines not on this page · raw message

man3/stailq.3 +31 -45

184 lines not on this page · raw message

man3/tailq.3 +46 -60

250 lines not on this page · raw message

Signature · 1 line
2.29.2
#1 lore raw

BTW, I didn't reorder the descriptions to match the groups. I wasn't sure about what to do,
so I prefered to leave them for now.

Quoted 1,004 lines · Alejandro Colomar

- Group macros by kinds.
- Align so that it's easiest to distinguish differences between related macros.
- Fix minor typos.
- Remove redundant text ('The macro xxx() ...'):
The first paragraph already says that these are macros.
- Fit lines into 78 columns.

I noticed a bug which should be fixed next:
CIRCLEQ_LOOP_*() return a 'struct TYPE *'.

---

Hi Michael,

Here's my attempt of making queue.3 pages more readable. I think it's quite nicer now.
But please, review it, because I may have introduced a few bugs while moving the text around.
Also, if you feel something could be nicer, please tell me.

BTW, it's been the first time I use Vim for something not trivial, and I quite liked it.
I think I'll stop using Gedit for a while :-)

Cheers,

Alex

 man3/circleq.3 |  77 +++++++++++++----------------------
 man3/list.3    |  59 ++++++++++++---------------
 man3/slist.3   |  58 ++++++++++++---------------
 man3/stailq.3  |  76 +++++++++++++++--------------------
 man3/tailq.3   | 106 +++++++++++++++++++++----------------------------
 5 files changed, 154 insertions(+), 222 deletions(-)
man3/circleq.3 +27 -50
index 49c7bad66..97f290cbd 100644
@@ -54,43 +54,39 @@ CIRCLEQ_REMOVE
 .nf
 .B #include <sys/queue.h>
 .PP
-.BI "int CIRCLEQ_EMPTY(CIRCLEQ_HEAD *" head ");"
-.PP
 .B CIRCLEQ_ENTRY(TYPE);
 .PP
-.BI "struct TYPE *CIRCLEQ_FIRST(CIRCLEQ_HEAD *" head ");"
-.PP
-.BI "CIRCLEQ_FOREACH(struct TYPE *" var ", CIRCLEQ_HEAD *" head ,
-.BI "                CIRCLEQ_ENTRY " NAME ");"
-.BI "CIRCLEQ_FOREACH_REVERSE(struct TYPE *" var ", CIRCLEQ_HEAD *" head ","
-.BI "                CIRCLEQ_ENTRY " NAME ");"
-.PP
 .B CIRCLEQ_HEAD(HEADNAME, TYPE);
-.BI "CIRCLEQ_HEAD CIRCLEQ_HEAD_INITIALIZER(CIRCLEQ_HEAD " head ");"
-.BI "void CIRCLEQ_INIT(CIRCLEQ_HEAD *" head ");"
-.PP
-.BI "void CIRCLEQ_INSERT_AFTER(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm ,
-.BI "                struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
-.BI "void CIRCLEQ_INSERT_BEFORE(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm ,
-.BI "                struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
+.BI "CIRCLEQ_HEAD CIRCLEQ_HEAD_INITIALIZER(CIRCLEQ_HEAD " head );
+.BI "void CIRCLEQ_INIT(CIRCLEQ_HEAD *" head );
 .PP
-.BI "void CIRCLEQ_INSERT_HEAD(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ","
-.BI "                CIRCLEQ_ENTRY " NAME ");"
-.BI "void CIRCLEQ_INSERT_TAIL(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ","
-.BI "                CIRCLEQ_ENTRY " NAME ");"
+.BI "int CIRCLEQ_EMPTY(CIRCLEQ_HEAD *" head );
 .PP
-.BI "struct TYPE *CIRCLEQ_LAST(CIRCLEQ_HEAD *" head ");"
+.BI "void CIRCLEQ_INSERT_HEAD(CIRCLEQ_HEAD *" head ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "void CIRCLEQ_INSERT_TAIL(CIRCLEQ_HEAD *" head ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "void CIRCLEQ_INSERT_BEFORE(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "void CIRCLEQ_INSERT_AFTER(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
 .PP
-.BI "void CIRCLEQ_LOOP_NEXT(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ","
-.BI "                CIRCLEQ_ENTRY " NAME ");"
-.BI "void CIRCLEQ_LOOP_PREV(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ","
-.BI "                CIRCLEQ_ENTRY " NAME ");"
+.BI "struct TYPE *CIRCLEQ_FIRST(CIRCLEQ_HEAD *" head );
+.BI "struct TYPE *CIRCLEQ_LAST(CIRCLEQ_HEAD *" head );
+.BI "struct TYPE *CIRCLEQ_PREV(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "struct TYPE *CIRCLEQ_NEXT(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "void CIRCLEQ_LOOP_PREV(CIRCLEQ_HEAD *" head ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "void CIRCLEQ_LOOP_NEXT(CIRCLEQ_HEAD *" head ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
 .PP
-.BI "struct TYPE *CIRCLEQ_NEXT(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
-.BI "struct TYPE *CIRCLEQ_PREV(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
+.BI "CIRCLEQ_FOREACH(struct TYPE *" var ", CIRCLEQ_HEAD *" head ,
+.BI "                        CIRCLEQ_ENTRY " NAME );
+.BI "CIRCLEQ_FOREACH_REVERSE(struct TYPE *" var ", CIRCLEQ_HEAD *" head ,
+.BI "                        CIRCLEQ_ENTRY " NAME );
 .PP
 .BI "void CIRCLEQ_REMOVE(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ,
-.BI "                CIRCLEQ_ENTRY " NAME ");"
+.BI "                    CIRCLEQ_ENTRY " NAME );
 .fi
 .SH DESCRIPTION
 These macros define and operate on doubly linked circular queues.
@@ -148,25 +144,20 @@ and
 .I headp
 are user selectable.)
 .PP
-The macro
 .BR CIRCLEQ_HEAD_INITIALIZER ()
 evaluates to an initializer for the circular queue
 .IR head .
 .PP
-The macro
 .BR CIRCLEQ_EMPTY ()
 evaluates to true if there are no items on the circular queue.
 .PP
-The macro
 .BR CIRCLEQ_ENTRY ()
 declares a structure that connects the elements in
 the circular queue.
 .PP
-The macro
 .BR CIRCLEQ_FIRST ()
 returns the first item on the circular queue.
 .PP
-The macro
 .BR CIRCLEQ_FOREACH ()
 traverses the circular queue referenced by
 .I head
@@ -177,75 +168,63 @@ is set to
 .I &head
 if the loop completes normally, or if there were no elements.
 .PP
-The macro
 .BR CIRCLEQ_FOREACH_REVERSE ()
 traverses the circular queue referenced by
 .I head
 in the reverse direction, assigning each element in turn to
 .IR var .
 .PP
-The macro
 .BR CIRCLEQ_INIT ()
 initializes the circular queue referenced by
 .IR head .
 .PP
-The macro
 .BR CIRCLEQ_INSERT_HEAD ()
 inserts the new element
 .I elm
 at the head of the circular queue.
 .PP
-The macro
 .BR CIRCLEQ_INSERT_TAIL ()
 inserts the new element
 .I elm
 at the end of the circular queue.
 .PP
-The macro
 .BR CIRCLEQ_INSERT_AFTER ()
 inserts the new element
 .I elm
 after the element
 .IR listelm .
 .PP
-The macro
 .BR CIRCLEQ_INSERT_BEFORE ()
 inserts the new element
 .I elm
 before the element
 .IR listelm .
 .PP
-The macro
 .BR CIRCLEQ_LAST ()
 returns the last item on the circular queue.
 .PP
-The macro
 .BR CIRCLEQ_NEXT ()
 returns the next item on the circular queue, or
 .I &head
 if this item is the last one.
 .PP
-The macro
 .BR CIRCLEQ_PREV ()
 returns the previous item on the circular queue, or
 .I &head
 if this item is the first one.
 .PP
-The macro
 .BR CIRCLEQ_LOOP_NEXT ()
 returns the next item on the circular queue.
 If
 .I elm
 is the last element on the circular queue, the first element is returned.
 .PP
-The macro
 .BR CIRCLEQ_LOOP_PREV ()
 returns the previous item on the circular queue.
 If
 .I elm
 is the first element on the circular queue, the last element is returned.
 .PP
-The macro
 .BR CIRCLEQ_REMOVE ()
 removes the element
 .I elm
@@ -257,10 +236,10 @@ and zero if the queue contains at least one entry.
 .PP
 .BR CIRCLEQ_FIRST (),
 .BR CIRCLEQ_LAST (),
-.BR CIRCLEQ_NEXT (),
+.BR CIRCLEQ_PREV (),
 and
-.BR CIRCLEQ_PREV ()
-return a pointer to the first, last, next or previous
+.BR CIRCLEQ_NEXT ()
+return a pointer to the first, last, previous or next
 .I TYPE
 structure, respectively.
 .PP
@@ -272,7 +251,6 @@ Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008.
 Present on the BSDs
 (CIRCLEQ macros first appeared in 4.4BSD).
 .SH BUGS
-The macros
 .BR CIRCLEQ_FOREACH ()
 and
 .BR CIRCLEQ_FOREACH_REVERSE ()
@@ -280,7 +258,6 @@ don't allow
 .I var
 to be removed or freed within the loop,
 as it would interfere with the traversal.
-The macros
 .BR CIRCLEQ_FOREACH_SAFE ()
 and
 .BR CIRCLEQ_FOREACH_REVERSE_SAFE (),
man3/list.3 +25 -34
index dde0960db..2efa1403d 100644
@@ -53,33 +53,38 @@ LIST_REMOVE
 .nf
 .B #include <sys/queue.h>
 .PP
-.BI "int LIST_EMPTY(LIST_HEAD *" head ");"
-.PP
 .B LIST_ENTRY(TYPE);
 .PP
-.BI "struct TYPE *LIST_FIRST(LIST_HEAD *" head ");"
+.B LIST_HEAD(HEADNAME, TYPE);
+.BI "LIST_HEAD LIST_HEAD_INITIALIZER(LIST_HEAD " head );
+.BI "void LIST_INIT(LIST_HEAD *" head );
 .PP
-.BI "LIST_FOREACH(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ");"
-.\".BI "LIST_FOREACH_FROM(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ");"
-.\".BI "LIST_FOREACH_FROM_SAFE(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ", struct TYPE *" temp_var ");"
-.\".BI "LIST_FOREACH_SAFE(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ", struct TYPE *" temp_var ");"
+.BI "int LIST_EMPTY(LIST_HEAD *" head );
 .PP
-.B LIST_HEAD(HEADNAME, TYPE);
-.BI "LIST_HEAD LIST_HEAD_INITIALIZER(LIST_HEAD " head ");"
-.BI "void LIST_INIT(LIST_HEAD *" head ");"
+.BI "void LIST_INSERT_HEAD(LIST_HEAD *" head ,
+.BI "                        struct TYPE *" elm ", LIST_ENTRY " NAME );
+.BI "void LIST_INSERT_AFTER(struct TYPE *" listelm ,
+.BI "                        struct TYPE *" elm ", LIST_ENTRY " NAME );
+.BI "void LIST_INSERT_BEFORE(struct TYPE *" listelm ,
+.BI "                        struct TYPE *" elm ", LIST_ENTRY " NAME );
 .PP
-.BI "void LIST_INSERT_AFTER(struct TYPE *" listelm ", struct TYPE *" elm ","
-.BI "                LIST_ENTRY " NAME ");"
-.BI "void LIST_INSERT_BEFORE(struct TYPE *" listelm ", struct TYPE *" elm ","
-.BI "                LIST_ENTRY " NAME ");"
-.BI "void LIST_INSERT_HEAD(LIST_HEAD *" head ", struct TYPE *" elm ","
-.BI "                LIST_ENTRY " NAME ");"
+.BI "struct TYPE *LIST_FIRST(LIST_HEAD *" head );
+.\" .BI "struct TYPE *LIST_PREV(struct TYPE *" elm ", LIST_HEAD *" head ,
+.\" .BI "                        struct TYPE, LIST_ENTRY " NAME );
+.BI "struct TYPE *LIST_NEXT(struct TYPE *" elm ", LIST_ENTRY " NAME );
 .PP
-.BI "struct TYPE *LIST_NEXT(struct TYPE *" elm ", LIST_ENTRY " NAME ");"
-.\".BI "struct TYPE *LIST_PREV(struct TYPE *" elm ", LIST_HEAD *" head ", struct TYPE, LIST_ENTRY " NAME ");"
+.BI "LIST_FOREACH(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME );
+.\" .BI "LIST_FOREACH_FROM(struct TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME );
+.\" .PP
+.\" .BI "LIST_FOREACH_SAFE(struct TYPE *" var ", LIST_HEAD *" head ,
+.\" .BI "                       LIST_ENTRY " NAME ", struct TYPE *" temp_var );
+.\" .BI "LIST_FOREACH_FROM_SAFE(struct TYPE *" var ", LIST_HEAD *" head ,
+.\" .BI "                       LIST_ENTRY " NAME ", struct TYPE *" temp_var );
 .PP
-.BI "void LIST_REMOVE(struct TYPE *" elm ", LIST_ENTRY " NAME ");"
-.\".BI "void LIST_SWAP(LIST_HEAD *" head1 ", LIST_HEAD *" head2 ", struct TYPE, LIST_ENTRY " NAME ");"
+.BI "void LIST_REMOVE(struct TYPE *" elm ", LIST_ENTRY " NAME );
+.\" .PP
+.\" .BI "void LIST_SWAP(LIST_HEAD *" head1 ", LIST_HEAD *" head2 ,
+.\" .BI "               struct TYPE, LIST_ENTRY " NAME );
 .fi
 .SH DESCRIPTION
 These macros define and operate on doubly linked lists.
@@ -135,33 +140,27 @@ and
 .I headp
 are user selectable.)
 .PP
-The macro
 .BR LIST_HEAD_INITIALIZER ()
 evaluates to an initializer for the list
 .IR head .
 .PP
-The macro
 .BR LIST_EMPTY ()
 evaluates to true if there are no elements in the list.
 .PP
-The macro
 .BR LIST_ENTRY ()
 declares a structure that connects the elements in
 the list.
 .PP
-The macro
 .BR LIST_FIRST ()
 returns the first element in the list or NULL if the list
 is empty.
 .PP
-The macro
 .BR LIST_FOREACH ()
 traverses the list referenced by
 .I head
 in the forward direction, assigning each element in turn to
 .IR var .
 .\" .PP
-.\" The macro
 .\" .BR LIST_FOREACH_FROM ()
 .\" behaves identically to
 .\" .BR LIST_FOREACH ()
@@ -200,32 +199,27 @@ in the forward direction, assigning each element in turn to
 .\" instead of the first element in the LIST referenced by
 .\" .IR head .
 .PP
-The macro
 .BR LIST_INIT ()
 initializes the list referenced by
 .IR head .
 .PP
-The macro
 .BR LIST_INSERT_HEAD ()
 inserts the new element
 .I elm
 at the head of the list.
 .PP
-The macro
 .BR LIST_INSERT_AFTER ()
 inserts the new element
 .I elm
 after the element
 .IR listelm .
 .PP
-The macro
 .BR LIST_INSERT_BEFORE ()
 inserts the new element
 .I elm
 before the element
 .IR listelm .
 .PP
-The macro
 .BR LIST_NEXT ()
 returns the next element in the list, or NULL if this is the last.
 .\" .PP
@@ -237,7 +231,6 @@ returns the next element in the list, or NULL if this is the last.
 .\" must contain element
 .\" .IR elm .
 .PP
-The macro
 .BR LIST_REMOVE ()
 removes the element
 .I elm
@@ -269,13 +262,11 @@ Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008.
 Present on the BSDs
 (LIST macros first appeared in 4.4BSD).
 .SH BUGS
-The macro
 .BR LIST_FOREACH ()
 doesn't allow
 .I var
 to be removed or freed within the loop,
 as it would interfere with the traversal.
-The macro
 .BR LIST_FOREACH_SAFE (),
 which is present on the BSDs but is not present in glibc,
 fixes this limitation by allowing
man3/slist.3 +25 -33
index 6868a63c2..714289a57 100644
@@ -53,33 +53,38 @@ SLIST_REMOVE_HEAD
 .nf
 .B #include <sys/queue.h>
 .PP
-.BI "int SLIST_EMPTY(SLIST_HEAD *" head ");"
-.PP
 .B SLIST_ENTRY(TYPE);
 .PP
-.BI "struct TYPE *SLIST_FIRST(SLIST_HEAD *" head ");"
+.B SLIST_HEAD(HEADNAME, TYPE);
+.BI "SLIST_HEAD SLIST_HEAD_INITIALIZER(SLIST_HEAD " head );
+.BI "void SLIST_INIT(SLIST_HEAD *" head );
 .PP
-.BI "SLIST_FOREACH(struct TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ");"
-.\".BI "SLIST_FOREACH_FROM(struct TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ");"
-.\".BI "SLIST_FOREACH_FROM_SAFE(struct TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ", struct TYPE *" temp_var ");"
-.\".BI "SLIST_FOREACH_SAFE(struct TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME ", struct TYPE *" temp_var ");"
+.BI "int SLIST_EMPTY(SLIST_HEAD *" head );
 .PP
-.B SLIST_HEAD(HEADNAME, TYPE);
-.BI "SLIST_HEAD SLIST_HEAD_INITIALIZER(SLIST_HEAD " head ");"
-.BI "void SLIST_INIT(SLIST_HEAD *" head ");"
+.BI "void SLIST_INSERT_HEAD(SLIST_HEAD *" head ,
+.BI "                        struct TYPE *" elm ", SLIST_ENTRY " NAME );
+.BI "void SLIST_INSERT_AFTER(struct TYPE *" listelm ,
+.BI "                        struct TYPE *" elm ", SLIST_ENTRY " NAME );
 .PP
-.BI "void SLIST_INSERT_AFTER(struct TYPE *" listelm ", struct TYPE *" elm ","
-.BI "                SLIST_ENTRY " NAME ");"
-.BI "void SLIST_INSERT_HEAD(SLIST_HEAD *" head ", struct TYPE *" elm ","
-.BI "                SLIST_ENTRY " NAME ");"
+.BI "struct TYPE *SLIST_FIRST(SLIST_HEAD *" head );
+.BI "struct TYPE *SLIST_NEXT(struct TYPE *" elm ", SLIST_ENTRY " NAME );
 .PP
-.BI "struct TYPE *SLIST_NEXT(struct TYPE *" elm ", SLIST_ENTRY " NAME ");"
+.BI "SLIST_FOREACH(struct TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME );
+.\" .BI "SLIST_FOREACH_FROM(struct TYPE *" var ", SLIST_HEAD *" head ", SLIST_ENTRY " NAME );
+.\" .PP
+.\" .BI "SLIST_FOREACH_SAFE(struct TYPE *" var ", SLIST_HEAD *" head ,
+.\" .BI "                        SLIST_ENTRY " NAME ", struct TYPE *" temp_var );
+.\" .BI "SLIST_FOREACH_FROM_SAFE(struct TYPE *" var ", SLIST_HEAD *" head ,
+.\" .BI "                        SLIST_ENTRY " NAME ", struct TYPE *" temp_var );
 .PP
-.BI "void SLIST_REMOVE(SLIST_HEAD *" head ", struct TYPE *" elm ", SLIST_ENTRY " NAME ");"
-.\".BI "void SLIST_REMOVE_AFTER(struct TYPE *" elm ", SLIST_ENTRY " NAME ");"
-.BI "void SLIST_REMOVE_HEAD(SLIST_HEAD *" head ", SLIST_ENTRY " NAME ");"
-.\".PP
-.\".BI "void SLIST_SWAP(SLIST_HEAD *" head1 ", SLIST_HEAD *" head2 ", SLIST_ENTRY " NAME ");"
+.BI "void SLIST_REMOVE(SLIST_HEAD *" head ", struct TYPE *" elm ,
+.BI "                       SLIST_ENTRY " NAME );
+.BI "void SLIST_REMOVE_HEAD(SLIST_HEAD *" head ,
+.BI "                       SLIST_ENTRY " NAME );
+.\" .BI "void SLIST_REMOVE_AFTER(struct TYPE *" elm ,
+.\" .BI "                        SLIST_ENTRY " NAME );
+.\" .PP
+.\" .BI "void SLIST_SWAP(SLIST_HEAD *" head1 ", SLIST_HEAD *" head2 ", SLIST_ENTRY " NAME );
 .fi
 .SH DESCRIPTION
 These macros define and operate on doubly linked lists.
@@ -135,25 +140,20 @@ and
 .I headp
 are user selectable.)
 .PP
-The macro
 .BR SLIST_HEAD_INITIALIZER ()
 evaluates to an initializer for the list
 .IR head .
 .PP
-The macro
 .BR SLIST_EMPTY ()
 evaluates to true if there are no elements in the list.
 .PP
-The macro
 .BR SLIST_ENTRY ()
 declares a structure that connects the elements in
 the list.
 .PP
-The macro
 .BR SLIST_FIRST ()
 returns the first element in the list or NULL if the list is empty.
 .PP
-The macro
 .BR SLIST_FOREACH ()
 traverses the list referenced by
 .I head
@@ -201,25 +201,21 @@ turn to
 .\" instead of the first element in the SLIST referenced by
 .\" .IR head .
 .PP
-The macro
 .BR SLIST_INIT ()
 initializes the list referenced by
 .IR head .
 .PP
-The macro
 .BR SLIST_INSERT_HEAD ()
 inserts the new element
 .I elm
 at the head of the list.
 .PP
-The macro
 .BR SLIST_INSERT_AFTER ()
 inserts the new element
 .I elm
 after the element
 .IR listelm .
 .PP
-The macro
 .BR SLIST_NEXT ()
 returns the next element in the list.
 .\" .PP
@@ -232,7 +228,6 @@ returns the next element in the list.
 .\" .IR SLIST_REMOVE ,
 .\" this macro does not traverse the entire list.
 .PP
-The macro
 .BR SLIST_REMOVE_HEAD ()
 removes the element
 .I elm
@@ -243,7 +238,6 @@ this macro instead of the generic
 .I SLIST_REMOVE
 macro.
 .PP
-The macro
 .BR SLIST_REMOVE ()
 removes the element
 .I elm
@@ -275,13 +269,11 @@ Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008.
 Present on the BSDs
 (SLIST macros first appeared in 4.4BSD).
 .SH BUGS
-The macro
 .BR SLIST_FOREACH ()
 doesn't allow
 .I var
 to be removed or freed within the loop,
 as it would interfere with the traversal.
-The macro
 .BR SLIST_FOREACH_SAFE (),
 which is present on the BSDs but is not present in glibc,
 fixes this limitation by allowing
man3/stailq.3 +31 -45
index 4a0e0bc5f..b825632c0 100644
@@ -56,41 +56,45 @@ STAILQ_REMOVE_HEAD,
 .nf
 .B #include <sys/queue.h>
 .PP
-.BI "void STAILQ_CONCAT(STAILQ_HEAD *" head1 ", STAILQ_HEAD *" head2 ");"
-.PP
-.BI "int STAILQ_EMPTY(STAILQ_HEAD *" head ");"
-.PP
 .B STAILQ_ENTRY(TYPE);
 .PP
-.BI "struct TYPE *STAILQ_FIRST(STAILQ_HEAD *" head ");"
+.B STAILQ_HEAD(HEADNAME, TYPE);
+.BI "STAILQ_HEAD STAILQ_HEAD_INITIALIZER(STAILQ_HEAD " head );
+.BI "void STAILQ_INIT(STAILQ_HEAD *" head );
 .PP
-.BI "STAILQ_FOREACH(struct TYPE *" var ", STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME ");"
-.\" .BI "STAILQ_FOREACH_FROM(struct TYPE *" var ", STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME ");"
-.\" .BI "STAILQ_FOREACH_FROM_SAFE(struct TYPE *" var ", STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME ", struct TYPE *" temp_var ");"
-.\" .BI "STAILQ_FOREACH_SAFE(struct TYPE *" var ", STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME ", struct TYPE *" temp_var ");"
+.BI "int STAILQ_EMPTY(STAILQ_HEAD *" head );
 .PP
-.B STAILQ_HEAD(HEADNAME, TYPE);
-.BI "STAILQ_HEAD STAILQ_HEAD_INITIALIZER(STAILQ_HEAD " head ");"
-.BI "void STAILQ_INIT(STAILQ_HEAD *" head ");"
+.BI "void STAILQ_INSERT_HEAD(STAILQ_HEAD *" head ,
+.BI "                         struct TYPE *" elm ", STAILQ_ENTRY " NAME );
+.BI "void STAILQ_INSERT_TAIL(STAILQ_HEAD *" head ,
+.BI "                         struct TYPE *" elm ", STAILQ_ENTRY " NAME );
+.BI "void STAILQ_INSERT_AFTER(STAILQ_HEAD *" head ", struct TYPE *" listelm ,
+.BI "                         struct TYPE *" elm ", STAILQ_ENTRY " NAME );
 .PP
-.BI "void STAILQ_INSERT_AFTER(STAILQ_HEAD *" head ", struct TYPE *" listelm ","
-.BI "                struct TYPE *" elm ", STAILQ_ENTRY " NAME ");"
-.BI "void STAILQ_INSERT_HEAD(STAILQ_HEAD *" head ", struct TYPE *" elm ","
-.BI "                STAILQ_ENTRY " NAME ");"
-.BI "void STAILQ_INSERT_TAIL(STAILQ_HEAD *" head ", struct TYPE *" elm ","
-.BI "                STAILQ_ENTRY " NAME ");"
-.\" .PP
-.\" .BI "struct TYPE *STAILQ_LAST(STAILQ_HEAD *" head ", struct TYPE *" elm ", STAILQ_ENTRY " NAME ");"
+.BI "struct TYPE *STAILQ_FIRST(STAILQ_HEAD *" head );
+.\" .BI "struct TYPE *STAILQ_LAST(STAILQ_HEAD *" head ", struct TYPE *" elm ,
+.\" .BI "                          STAILQ_ENTRY " NAME );
+.BI "struct TYPE *STAILQ_NEXT(struct TYPE *" elm ", STAILQ_ENTRY " NAME );
 .PP
-.BI "struct TYPE *STAILQ_NEXT(struct TYPE *" elm ", STAILQ_ENTRY " NAME ");"
+.BI "STAILQ_FOREACH(struct TYPE *" var ", STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME );
+.\" .BI "STAILQ_FOREACH_FROM(struct TYPE *" var ", STAILQ_HEAD *" head ,
+.\" .BI "                    STAILQ_ENTRY " NAME );
+.\" .PP
+.\" .BI "STAILQ_FOREACH_SAFE(struct TYPE *" var ", STAILQ_HEAD *" head ,
+.\" .BI "                         STAILQ_ENTRY " NAME ", struct TYPE *" temp_var );
+.\" .BI "STAILQ_FOREACH_FROM_SAFE(struct TYPE *" var ", STAILQ_HEAD *" head ,
+.\" .BI "                         STAILQ_ENTRY " NAME ", struct TYPE *" temp_var );
 .PP
 .BI "void STAILQ_REMOVE(STAILQ_HEAD *" head ", struct TYPE *" elm ", TYPE,"
-.BI "                STAILQ_ENTRY " NAME ");"
-.\" .BI "void STAILQ_REMOVE_AFTER(STAILQ_HEAD *" head ", struct TYPE *" elm ","
-.\" .BI "                STAILQ_ENTRY " NAME ");"
-.BI "void STAILQ_REMOVE_HEAD(STAILQ_HEAD *" head ", STAILQ_ENTRY " NAME ");"
-.\" .BI "void STAILQ_SWAP(STAILQ_HEAD *" head1 ", STAILQ_HEAD *" head2 ","
-.\" .BI "                STAILQ_ENTRY " NAME ");"
+.BI "                        STAILQ_ENTRY " NAME );
+.BI "void STAILQ_REMOVE_HEAD(STAILQ_HEAD *" head ,
+.BI "                        STAILQ_ENTRY " NAME );
+.\" .BI "void STAILQ_REMOVE_AFTER(STAILQ_HEAD *" head ", struct TYPE *" elm ,
+.\" .BI "                         STAILQ_ENTRY " NAME );
+.PP
+.BI "void STAILQ_CONCAT(STAILQ_HEAD *" head1 ", STAILQ_HEAD *" head2 );
+.\" .BI "void STAILQ_SWAP(STAILQ_HEAD *" head1 ", STAILQ_HEAD *" head2 ,
+.\" .BI "                   STAILQ_ENTRY " NAME );
 .fi
 .SH DESCRIPTION
 These macros define and operate on singly linked tail queues.
@@ -148,12 +152,10 @@ and
 .I headp
 are user selectable.)
 .PP
-The macro
 .BR STAILQ_HEAD_INITIALIZER ()
 evaluates to an initializer for the tail queue
 .IR head .
 .PP
-The macro
 .BR STAILQ_CONCAT ()
 concatenates the tail queue headed by
 .I head2
@@ -161,21 +163,17 @@ onto the end of the one headed by
 .I head1
 removing all entries from the former.
 .PP
-The macro
 .BR STAILQ_EMPTY ()
 evaluates to true if there are no items on the tail queue.
 .PP
-The macro
 .BR STAILQ_ENTRY ()
 declares a structure that connects the elements in
 the tail queue.
 .PP
-The macro
 .BR STAILQ_FIRST ()
 returns the first item on the tail queue or NULL if the tail queue
 is empty.
 .PP
-The macro
 .BR STAILQ_FOREACH ()
 traverses the tail queue referenced by
 .I head
@@ -183,7 +181,6 @@ in the forward direction, assigning each element
 in turn to
 .IR var .
 .\" .PP
-.\" The macro
 .\" .BR STAILQ_FOREACH_FROM ()
 .\" behaves identically to
 .\" .BR STAILQ_FOREACH ()
@@ -196,7 +193,6 @@ in turn to
 .\" instead of the first element in the STAILQ referenced by
 .\" .IR head .
 .\" .PP
-.\" The macro
 .\" .BR STAILQ_FOREACH_SAFE ()
 .\" traverses the tail queue referenced by
 .\" .I head
@@ -210,7 +206,6 @@ in turn to
 .\" as well as free it from within the loop safely without interfering with the
 .\" traversal.
 .\" .PP
-.\" The macro
 .\" .BR STAILQ_FOREACH_FROM_SAFE ()
 .\" behaves identically to
 .\" .BR STAILQ_FOREACH_SAFE ()
@@ -223,24 +218,20 @@ in turn to
 .\" instead of the first element in the STAILQ referenced by
 .\" .IR head .
 .PP
-The macro
 .BR STAILQ_INIT ()
 initializes the tail queue referenced by
 .IR head .
 .PP
-The macro
 .BR STAILQ_INSERT_HEAD ()
 inserts the new element
 .I elm
 at the head of the tail queue.
 .PP
-The macro
 .BR STAILQ_INSERT_TAIL ()
 inserts the new element
 .I elm
 at the end of the tail queue.
 .PP
-The macro
 .BR STAILQ_INSERT_AFTER ()
 inserts the new element
 .I elm
@@ -252,7 +243,6 @@ after the element
 .\" returns the last item on the tail queue.
 .\" If the tail queue is empty the return value is NULL .
 .PP
-The macro
 .BR STAILQ_NEXT ()
 returns the next item on the tail queue, or NULL this item is the last.
 .\" .PP
@@ -265,7 +255,6 @@ returns the next item on the tail queue, or NULL this item is the last.
 .\" .BR STAILQ_REMOVE (),
 .\" this macro does not traverse the entire tail queue.
 .PP
-The macro
 .BR STAILQ_REMOVE_HEAD ()
 removes the element at the head of the tail queue.
 For optimum efficiency,
@@ -274,7 +263,6 @@ use this macro explicitly rather than the generic
 .BR STAILQ_REMOVE ()
 macro.
 .PP
-The macro
 .BR STAILQ_REMOVE ()
 removes the element
 .I elm
@@ -306,13 +294,11 @@ Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008.
 Present on the BSDs
 (STAILQ macros first appeared in 4.4BSD).
 .SH BUGS
-The macro
 .BR STAILQ_FOREACH ()
 doesn't allow
 .I var
 to be removed or freed within the loop,
 as it would interfere with the traversal.
-The macro
 .BR STAILQ_FOREACH_SAFE (),
 which is present on the BSDs but is not present in glibc,
 fixes this limitation by allowing
man3/tailq.3 +46 -60
index 14af54878..163b9556e 100644
@@ -60,47 +60,57 @@ TAILQ_REMOVE
 .nf
 .B #include <sys/queue.h>
 .PP
-.BI "void TAILQ_CONCAT(TAILQ_HEAD *" head1 ", TAILQ_HEAD *" head2 ","
-.BI "                TAILQ_ENTRY " NAME ");"
-.PP
-.BI "int TAILQ_EMPTY(TAILQ_HEAD *" head ");"
-.PP
 .B TAILQ_ENTRY(TYPE);
 .PP
-.BI "struct TYPE *TAILQ_FIRST(TAILQ_HEAD *" head ");"
-.PP
-.BI "TAILQ_FOREACH(struct TYPE *" var ", TAILQ_HEAD *" head ", TAILQ_ENTRY " NAME ");"
-.\" .BI "TAILQ_FOREACH_FROM(struct TYPE *" var ", TAILQ_HEAD *" head ", TAILQ_ENTRY " NAME ");"
-.\" .BI "TAILQ_FOREACH_FROM_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head ", TAILQ_ENTRY " NAME ", struct TYPE *" temp_var ");"
-.BI "TAILQ_FOREACH_REVERSE(struct TYPE *" var ", TAILQ_HEAD *" head ", HEADNAME,"
-.BI "                TAILQ_ENTRY " NAME ");"
-.\" .PP
-.\" .BI "TAILQ_FOREACH_REVERSE_FROM(struct TYPE *" var ", TAILQ_HEAD *" head ", HEADNAME, TAILQ_ENTRY " NAME ");"
-.\" .BI "TAILQ_FOREACH_REVERSE_FROM_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head ", HEADNAME, TAILQ_ENTRY " NAME ", struct TYPE *" temp_var ");"
-.\" .BI "TAILQ_FOREACH_REVERSE_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head ", HEADNAME, TAILQ_ENTRY " NAME ", TYPE *" temp_var ");"
-.\" .BI "TAILQ_FOREACH_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head ", TAILQ_ENTRY " NAME ", struct TYPE *" temp_var ");"
-.PP
 .B TAILQ_HEAD(HEADNAME, TYPE);
-.BI "TAILQ_HEAD TAILQ_HEAD_INITIALIZER(TAILQ_HEAD " head ");"
-.BI "void TAILQ_INIT(TAILQ_HEAD *" head ");"
+.BI "TAILQ_HEAD TAILQ_HEAD_INITIALIZER(TAILQ_HEAD " head );
+.BI "void TAILQ_INIT(TAILQ_HEAD *" head );
 .PP
-.BI "void TAILQ_INSERT_AFTER(TAILQ_HEAD *" head ", struct TYPE *" listelm ","
-.BI "                struct TYPE *" elm ", TAILQ_ENTRY " NAME ");"
-.BI "void TAILQ_INSERT_BEFORE(struct TYPE *" listelm ", struct TYPE *" elm ","
-.BI "                TAILQ_ENTRY " NAME ");"
+.BI "int TAILQ_EMPTY(TAILQ_HEAD *" head );
 .PP
-.BI "void TAILQ_INSERT_HEAD(TAILQ_HEAD *" head ", struct TYPE *" elm ","
-.BI "                TAILQ_ENTRY " NAME ");"
-.BI "void TAILQ_INSERT_TAIL(TAILQ_HEAD *" head ", struct TYPE *" elm ","
-.BI "                TAILQ_ENTRY " NAME ");"
+.BI "void TAILQ_INSERT_HEAD(TAILQ_HEAD *" head ,
+.BI "                         struct TYPE *" elm ", TAILQ_ENTRY " NAME );
+.BI "void TAILQ_INSERT_TAIL(TAILQ_HEAD *" head ,
+.BI "                         struct TYPE *" elm ", TAILQ_ENTRY " NAME );
+.BI "void TAILQ_INSERT_BEFORE(struct TYPE *" listelm ,
+.BI "                         struct TYPE *" elm ", TAILQ_ENTRY " NAME );
+.BI "void TAILQ_INSERT_AFTER(TAILQ_HEAD *" head ", struct TYPE *" listelm ,
+.BI "                         struct TYPE *" elm ", TAILQ_ENTRY " NAME );
 .PP
+.BI "struct TYPE *TAILQ_FIRST(TAILQ_HEAD *" head );
 .BI "struct TYPE *TAILQ_LAST(TAILQ_HEAD *" head ", HEADNAME);"
-.BI "struct TYPE *TAILQ_NEXT(struct TYPE *" elm ", TAILQ_ENTRY " NAME ");"
-.BI "struct TYPE *TAILQ_PREV(struct TYPE *" elm ", HEADNAME, TAILQ_ENTRY " NAME ");"
-.BI "void TAILQ_REMOVE(TAILQ_HEAD *" head ", struct TYPE *" elm ,
-.BI "                TAILQ_ENTRY " NAME ");"
+.BI "struct TYPE *TAILQ_PREV(struct TYPE *" elm ", HEADNAME, TAILQ_ENTRY " NAME );
+.BI "struct TYPE *TAILQ_NEXT(struct TYPE *" elm ", TAILQ_ENTRY " NAME );
+.PP
+.BI "TAILQ_FOREACH(struct TYPE *" var ", TAILQ_HEAD *" head ,
+.BI "                      TAILQ_ENTRY " NAME );
+.\" .BI "TAILQ_FOREACH_FROM(struct TYPE *" var ", TAILQ_HEAD *" head ,
+.\" .BI "                           TAILQ_ENTRY " NAME );
+.BI "TAILQ_FOREACH_REVERSE(struct TYPE *" var ", TAILQ_HEAD *" head ", HEADNAME,"
+.BI "                      TAILQ_ENTRY " NAME );
+.\" .BI "TAILQ_FOREACH_REVERSE_FROM(struct TYPE *" var ", TAILQ_HEAD *" head ", HEADNAME,"
+.\" .BI "                           TAILQ_ENTRY " NAME );
 .\" .PP
-.\" .BI "void TAILQ_SWAP(TAILQ_HEAD *" head1 ", TAILQ_HEAD *" head2 ", TYPE, TAILQ_ENTRY " NAME ");"
+.\" .BI "TAILQ_FOREACH_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head ,
+.\" .BI "                                TAILQ_ENTRY " NAME ,
+.\" .BI "                                struct TYPE *" temp_var );
+.\" .BI "TAILQ_FOREACH_FROM_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head ,
+.\" .BI "                                TAILQ_ENTRY " NAME ,
+.\" .BI "                                struct TYPE *" temp_var );
+.\" .BI "TAILQ_FOREACH_REVERSE_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head ,
+.\" .BI "                                HEADNAME, TAILQ_ENTRY " NAME ,
+.\" .BI "                                struct TYPE *" temp_var );
+.\" .BI "TAILQ_FOREACH_REVERSE_FROM_SAFE(struct TYPE *" var ", TAILQ_HEAD *" head ,
+.\" .BI "                                HEADNAME, TAILQ_ENTRY " NAME ,
+.\" .BI "                                struct TYPE *" temp_var );
+.PP
+.BI "void TAILQ_REMOVE(TAILQ_HEAD *" head ", struct TYPE *" elm ,
+.BI "                  TAILQ_ENTRY " NAME );
+.PP
+.BI "void TAILQ_CONCAT(TAILQ_HEAD *" head1 ", TAILQ_HEAD *" head2 ,
+.BI "                  TAILQ_ENTRY " NAME );
+.\" .BI "void TAILQ_SWAP(TAILQ_HEAD *" head1 ", TAILQ_HEAD *" head2 ", TYPE,"
+.\" .BI "                  TAILQ_ENTRY " NAME );
 .fi
 .SH DESCRIPTION
 These macros define and operate on doubly linked tail queues.
@@ -158,12 +168,10 @@ and
 .I headp
 are user selectable.)
 .PP
-The macro
 .BR TAILQ_HEAD_INITIALIZER ()
 evaluates to an initializer for the tail queue
 .IR head .
 .PP
-The macro
 .BR TAILQ_CONCAT ()
 concatenates the tail queue headed by
 .I head2
@@ -171,21 +179,17 @@ onto the end of the one headed by
 .I head1
 removing all entries from the former.
 .PP
-The macro
 .BR TAILQ_EMPTY ()
 evaluates to true if there are no items on the tail queue.
 .PP
-The macro
 .BR TAILQ_ENTRY ()
 declares a structure that connects the elements in
 the tail queue.
 .PP
-The macro
 .BR TAILQ_FIRST ()
 returns the first item on the tail queue or NULL if the tail queue
 is empty.
 .PP
-The macro
 .BR TAILQ_FOREACH ()
 traverses the tail queue referenced by
 .I head
@@ -195,7 +199,6 @@ in the forward direction, assigning each element in turn to
 is set to NULL if the loop completes normally,
 or if there were no elements.
 .\" .PP
-.\" The macro
 .\" .BR TAILQ_FOREACH_FROM ()
 .\" behaves identically to
 .\" .BR TAILQ_FOREACH ()
@@ -208,14 +211,12 @@ or if there were no elements.
 .\" instead of the first element in the TAILQ referenced by
 .\" .IR head .
 .PP
-The macro
 .BR TAILQ_FOREACH_REVERSE ()
 traverses the tail queue referenced by
 .I head
 in the reverse direction, assigning each element in turn to
 .IR var .
 .\" .PP
-.\" The macro
 .\" .BR TAILQ_FOREACH_REVERSE_FROM ()
 .\" behaves identically to
 .\" .BR TAILQ_FOREACH_REVERSE ()
@@ -228,7 +229,6 @@ in the reverse direction, assigning each element in turn to
 .\" instead of the last element in the TAILQ referenced by
 .\" .IR head .
 .\" .PP
-.\" The macros
 .\" .BR TAILQ_FOREACH_SAFE ()
 .\" and
 .\" .BR TAILQ_FOREACH_REVERSE_SAFE ()
@@ -246,7 +246,6 @@ in the reverse direction, assigning each element in turn to
 .\" as well as free it from within the loop safely without interfering with the
 .\" traversal.
 .\" .PP
-.\" The macro
 .\" .BR TAILQ_FOREACH_FROM_SAFE ()
 .\" behaves identically to
 .\" .BR TAILQ_FOREACH_SAFE ()
@@ -259,7 +258,6 @@ in the reverse direction, assigning each element in turn to
 .\" instead of the first element in the TAILQ referenced by
 .\" .IR head .
 .\" .PP
-.\" The macro
 .\" .BR TAILQ_FOREACH_REVERSE_FROM_SAFE ()
 .\" behaves identically to
 .\" .BR TAILQ_FOREACH_REVERSE_SAFE ()
@@ -272,58 +270,48 @@ in the reverse direction, assigning each element in turn to
 .\" instead of the last element in the TAILQ referenced by
 .\" .IR head .
 .PP
-The macro
 .BR TAILQ_INIT ()
 initializes the tail queue referenced by
 .IR head .
 .PP
-The macro
 .BR TAILQ_INSERT_HEAD ()
 inserts the new element
 .I elm
 at the head of the tail queue.
 .PP
-The macro
 .BR TAILQ_INSERT_TAIL ()
 inserts the new element
 .I elm
 at the end of the tail queue.
 .PP
-The macro
 .BR TAILQ_INSERT_AFTER ()
 inserts the new element
 .I elm
 after the element
 .IR listelm .
 .PP
-The macro
 .BR TAILQ_INSERT_BEFORE ()
 inserts the new element
 .I elm
 before the element
 .IR listelm .
 .PP
-The macro
 .BR TAILQ_LAST ()
 returns the last item on the tail queue.
 If the tail queue is empty the return value is NULL.
 .PP
-The macro
 .BR TAILQ_NEXT ()
 returns the next item on the tail queue, or NULL if this item is the last.
 .PP
-The macro
 .BR TAILQ_PREV ()
 returns the previous item on the tail queue, or NULL if this item
 is the first.
 .PP
-The macro
 .BR TAILQ_REMOVE ()
 removes the element
 .I elm
 from the tail queue.
 .\" .PP
-.\" The macro
 .\" .BR TAILQ_SWAP ()
 .\" swaps the contents of
 .\" .I head1
@@ -336,10 +324,10 @@ and zero if the queue contains at least one entry.
 .PP
 .BR TAILQ_FIRST (),
 .BR TAILQ_LAST (),
-.BR TAILQ_NEXT (),
+.BR TAILQ_PREV (),
 and
-.BR TAILQ_PREV ()
-return a pointer to the first, last, next or previous
+.BR TAILQ_NEXT ()
+return a pointer to the first, last, previous or next
 .I TYPE
 structure, respectively.
 .PP
@@ -351,7 +339,6 @@ Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008.
 Present on the BSDs.
 (TAILQ functions first appeared in 4.4BSD).
 .SH BUGS
-The macros
 .BR TAILQ_FOREACH ()
 and
 .BR TAILQ_FOREACH_REVERSE ()
@@ -359,7 +346,6 @@ don't allow
 .I var
 to be removed or freed within the loop,
 as it would interfere with the traversal.
-The macros
 .BR TAILQ_FOREACH_SAFE ()
 and
 .BR TAILQ_FOREACH_REVERSE_SAFE (),
Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#2 lore raw
Quoted 3 lines · Alejandro Colomar (man-pages)

BTW, I didn't reorder the descriptions to match the groups. I wasn't sure about what to do,
so I prefered to leave them for now.

I think it would be kind to the reader if the descriptions roughly matched (does not need to be exact) the ordering in the SYNOPSIS.

Thanks,

Michael

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/
#3 lore raw

PATCH v2 1/1 circleq.3, list.3, slist.3, stailq.3, tailq.3: Improve readability, especially in SYNOPSIS

- Group macros by kinds.
- Align so that it's easiest to distinguish differences between related macros.
(Align all continuations for consistency on PDF.)
- Fix minor typos.
- Remove redundant text:
'The macro xxx() ...':
The first paragraph already says that these are macros.
'circular|tail|... queue':
Don't need to repeat every time.
Generic text makes it easier to spot the differences.
- Fit lines into 78 columns.
- Reorder descriptions to match SYNOPSIS,
and add subsections to DESCRIPTION.
- srcfix: fix a few smantic newlines.

I noticed a bug which should be fixed next:
CIRCLEQ_LOOP_*() return a 'struct TYPE *'.

---
 man3/circleq.3 | 199 ++++++++++++++++++----------------------
 man3/list.3    | 159 +++++++++++++++-----------------
 man3/slist.3   | 159 +++++++++++++++-----------------
 man3/stailq.3  | 184 +++++++++++++++++--------------------
 man3/tailq.3   | 241 +++++++++++++++++++++++--------------------------
 5 files changed, 433 insertions(+), 509 deletions(-)
man3/circleq.3 +89 -110
index 49c7bad66..a2b49210f 100644
@@ -54,43 +54,39 @@ CIRCLEQ_REMOVE
 .nf
 .B #include <sys/queue.h>
 .PP
-.BI "int CIRCLEQ_EMPTY(CIRCLEQ_HEAD *" head ");"
-.PP
 .B CIRCLEQ_ENTRY(TYPE);
 .PP
-.BI "struct TYPE *CIRCLEQ_FIRST(CIRCLEQ_HEAD *" head ");"
-.PP
-.BI "CIRCLEQ_FOREACH(struct TYPE *" var ", CIRCLEQ_HEAD *" head ,
-.BI "                CIRCLEQ_ENTRY " NAME ");"
-.BI "CIRCLEQ_FOREACH_REVERSE(struct TYPE *" var ", CIRCLEQ_HEAD *" head ","
-.BI "                CIRCLEQ_ENTRY " NAME ");"
-.PP
 .B CIRCLEQ_HEAD(HEADNAME, TYPE);
-.BI "CIRCLEQ_HEAD CIRCLEQ_HEAD_INITIALIZER(CIRCLEQ_HEAD " head ");"
-.BI "void CIRCLEQ_INIT(CIRCLEQ_HEAD *" head ");"
+.BI "CIRCLEQ_HEAD CIRCLEQ_HEAD_INITIALIZER(CIRCLEQ_HEAD " head );
+.BI "void CIRCLEQ_INIT(CIRCLEQ_HEAD *" head );
 .PP
-.BI "void CIRCLEQ_INSERT_AFTER(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm ,
-.BI "                struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
-.BI "void CIRCLEQ_INSERT_BEFORE(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm ,
-.BI "                struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
-.PP
-.BI "void CIRCLEQ_INSERT_HEAD(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ","
-.BI "                CIRCLEQ_ENTRY " NAME ");"
-.BI "void CIRCLEQ_INSERT_TAIL(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ","
-.BI "                CIRCLEQ_ENTRY " NAME ");"
+.BI "int CIRCLEQ_EMPTY(CIRCLEQ_HEAD *" head );
 .PP
-.BI "struct TYPE *CIRCLEQ_LAST(CIRCLEQ_HEAD *" head ");"
+.BI "void CIRCLEQ_INSERT_HEAD(CIRCLEQ_HEAD *" head ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "void CIRCLEQ_INSERT_TAIL(CIRCLEQ_HEAD *" head ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "void CIRCLEQ_INSERT_BEFORE(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "void CIRCLEQ_INSERT_AFTER(CIRCLEQ_HEAD *" head ", struct TYPE *" listelm ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
 .PP
-.BI "void CIRCLEQ_LOOP_NEXT(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ","
-.BI "                CIRCLEQ_ENTRY " NAME ");"
-.BI "void CIRCLEQ_LOOP_PREV(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ","
-.BI "                CIRCLEQ_ENTRY " NAME ");"
+.BI "struct TYPE *CIRCLEQ_FIRST(CIRCLEQ_HEAD *" head );
+.BI "struct TYPE *CIRCLEQ_LAST(CIRCLEQ_HEAD *" head );
+.BI "struct TYPE *CIRCLEQ_PREV(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "struct TYPE *CIRCLEQ_NEXT(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "void CIRCLEQ_LOOP_PREV(CIRCLEQ_HEAD *" head ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
+.BI "void CIRCLEQ_LOOP_NEXT(CIRCLEQ_HEAD *" head ,
+.BI "                           struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME );
 .PP
-.BI "struct TYPE *CIRCLEQ_NEXT(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
-.BI "struct TYPE *CIRCLEQ_PREV(struct TYPE *" elm ", CIRCLEQ_ENTRY " NAME ");"
+.BI "CIRCLEQ_FOREACH(struct TYPE *" var ", CIRCLEQ_HEAD *" head ,
+.BI "                           CIRCLEQ_ENTRY " NAME );
+.BI "CIRCLEQ_FOREACH_REVERSE(struct TYPE *" var ", CIRCLEQ_HEAD *" head ,
+.BI "                           CIRCLEQ_ENTRY " NAME );
 .PP
 .BI "void CIRCLEQ_REMOVE(CIRCLEQ_HEAD *" head ", struct TYPE *" elm ,
-.BI "                CIRCLEQ_ENTRY " NAME ");"
+.BI "                           CIRCLEQ_ENTRY " NAME );
 .fi
 .SH DESCRIPTION
 These macros define and operate on doubly linked circular queues.
@@ -104,21 +100,23 @@ named
 .IR NAME .
 The argument
 .I HEADNAME
-is the name of a user-defined structure that must be declared
-using the macro
+is the name of a user-defined structure
+that must be declared using the macro
 .BR CIRCLEQ_HEAD ().
-.PP
+.SS Creation
 A circular queue is headed by a structure defined by the
 .BR CIRCLEQ_HEAD ()
 macro.
 This structure contains a pair of pointers,
-one to the first element in the circular queue and the other to
-the last element in the circular queue.
-The elements are doubly linked so that an arbitrary element can be
-removed without traversing the circular queue.
-New elements can be added to the circular queue after an existing element,
-before an existing element, at the head of the circular queue,
-or at the end of the circular queue.
+one to the first element in the queue
+and the other to the last element in the queue.
+The elements are doubly linked
+so that an arbitrary element can be removed without traversing the queue.
+New elements can be added to the queue
+after an existing element,
+before an existing element,
+at the head of the queue,
+or at the end of the queue.
 A
 .I CIRCLEQ_HEAD
 structure is declared as follows:
@@ -133,8 +131,8 @@ where
 .I struct HEADNAME
 is the structure to be defined, and
 .I struct TYPE
-is the type of the elements to be linked into the circular queue.
-A pointer to the head of the circular queue can later be declared as:
+is the type of the elements to be linked into the queue.
+A pointer to the head of the queue can later be declared as:
 .PP
 .in +4
 .EX
@@ -148,108 +146,91 @@ and
 .I headp
 are user selectable.)
 .PP
-The macro
-.BR CIRCLEQ_HEAD_INITIALIZER ()
-evaluates to an initializer for the circular queue
-.IR head .
-.PP
-The macro
-.BR CIRCLEQ_EMPTY ()
-evaluates to true if there are no items on the circular queue.
-.PP
-The macro
 .BR CIRCLEQ_ENTRY ()
-declares a structure that connects the elements in
-the circular queue.
-.PP
-The macro
-.BR CIRCLEQ_FIRST ()
-returns the first item on the circular queue.
+declares a structure that connects the elements in the queue.
 .PP
-The macro
-.BR CIRCLEQ_FOREACH ()
-traverses the circular queue referenced by
-.I head
-in the forward direction, assigning each element in turn to
-.IR var .
-.I var
-is set to
-.I &head
-if the loop completes normally, or if there were no elements.
-.PP
-The macro
-.BR CIRCLEQ_FOREACH_REVERSE ()
-traverses the circular queue referenced by
-.I head
-in the reverse direction, assigning each element in turn to
-.IR var .
+.BR CIRCLEQ_HEAD_INITIALIZER ()
+evaluates to an initializer for the queue
+.IR head .
 .PP
-The macro
 .BR CIRCLEQ_INIT ()
-initializes the circular queue referenced by
+initializes the queue referenced by
 .IR head .
 .PP
-The macro
+.BR CIRCLEQ_EMPTY ()
+evaluates to true if there are no items on the queue.
+.SS Insertion
 .BR CIRCLEQ_INSERT_HEAD ()
 inserts the new element
 .I elm
-at the head of the circular queue.
+at the head of the queue.
 .PP
-The macro
 .BR CIRCLEQ_INSERT_TAIL ()
 inserts the new element
 .I elm
-at the end of the circular queue.
+at the end of the queue.
 .PP
-The macro
-.BR CIRCLEQ_INSERT_AFTER ()
+.BR CIRCLEQ_INSERT_BEFORE ()
 inserts the new element
 .I elm
-after the element
+before the element
 .IR listelm .
 .PP
-The macro
-.BR CIRCLEQ_INSERT_BEFORE ()
+.BR CIRCLEQ_INSERT_AFTER ()
 inserts the new element
 .I elm
-before the element
+after the element
 .IR listelm .
+.SS Traversal
+.BR CIRCLEQ_FIRST ()
+returns the first item on the queue.
 .PP
-The macro
 .BR CIRCLEQ_LAST ()
-returns the last item on the circular queue.
+returns the last item on the queue.
 .PP
-The macro
-.BR CIRCLEQ_NEXT ()
-returns the next item on the circular queue, or
-.I &head
-if this item is the last one.
-.PP
-The macro
 .BR CIRCLEQ_PREV ()
-returns the previous item on the circular queue, or
+returns the previous item on the queue, or
 .I &head
 if this item is the first one.
 .PP
-The macro
-.BR CIRCLEQ_LOOP_NEXT ()
-returns the next item on the circular queue.
+.BR CIRCLEQ_NEXT ()
+returns the next item on the queue, or
+.I &head
+if this item is the last one.
+.PP
+.BR CIRCLEQ_LOOP_PREV ()
+returns the previous item on the queue.
 If
 .I elm
-is the last element on the circular queue, the first element is returned.
+is the first element on the queue, the last element is returned.
 .PP
-The macro
-.BR CIRCLEQ_LOOP_PREV ()
-returns the previous item on the circular queue.
+.BR CIRCLEQ_LOOP_NEXT ()
+returns the next item on the queue.
 If
 .I elm
-is the first element on the circular queue, the last element is returned.
+is the last element on the queue, the first element is returned.
 .PP
-The macro
+.BR CIRCLEQ_FOREACH ()
+traverses the queue referenced by
+.I head
+in the forward direction, assigning each element in turn to
+.IR var .
+.I var
+is set to
+.I &head
+if the loop completes normally, or if there were no elements.
+.PP
+.BR CIRCLEQ_FOREACH_REVERSE ()
+traverses the queue referenced by
+.I head
+in the reverse direction,
+assigning each element in turn to
+.IR var .
+.SS Removal
 .BR CIRCLEQ_REMOVE ()
 removes the element
 .I elm
-from the circular queue.
+from the queue.
 .SH RETURN VALUE
 .BR CIRCLEQ_EMPTY ()
 returns nonzero if the queue is empty,
@@ -257,10 +238,10 @@ and zero if the queue contains at least one entry.
 .PP
 .BR CIRCLEQ_FIRST (),
 .BR CIRCLEQ_LAST (),
-.BR CIRCLEQ_NEXT (),
+.BR CIRCLEQ_PREV (),
 and
-.BR CIRCLEQ_PREV ()
-return a pointer to the first, last, next or previous
+.BR CIRCLEQ_NEXT ()
+return a pointer to the first, last, previous or next
 .I TYPE
 structure, respectively.
 .PP
@@ -272,7 +253,6 @@ Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008.
 Present on the BSDs
 (CIRCLEQ macros first appeared in 4.4BSD).
 .SH BUGS
-The macros
 .BR CIRCLEQ_FOREACH ()
 and
 .BR CIRCLEQ_FOREACH_REVERSE ()
@@ -280,7 +260,6 @@ don't allow
 .I var
 to be removed or freed within the loop,
 as it would interfere with the traversal.
-The macros
 .BR CIRCLEQ_FOREACH_SAFE ()
 and
 .BR CIRCLEQ_FOREACH_REVERSE_SAFE (),
man3/list.3 +73 -86

236 lines not on this page · raw message

man3/slist.3 +74 -85

241 lines not on this page · raw message

man3/stailq.3 +82 -102

271 lines not on this page · raw message

man3/tailq.3 +115 -126

355 lines not on this page · raw message

Signature · 1 line
2.29.2
#4 lore raw

A minor correction below:

Quoted 28 lines · Alejandro Colomar

- Group macros by kinds.
- Align so that it's easiest to distinguish differences between related macros.
(Align all continuations for consistency on PDF.)
- Fix minor typos.
- Remove redundant text:
'The macro xxx() ...':
The first paragraph already says that these are macros.
'circular|tail|... queue':
Don't need to repeat every time.
Generic text makes it easier to spot the differences.
- Fit lines into 78 columns.
- Reorder descriptions to match SYNOPSIS,
and add subsections to DESCRIPTION.
- srcfix: fix a few smantic newlines.

I noticed a bug which should be fixed next:
CIRCLEQ_LOOP_*() return a 'struct TYPE *'.

---
 man3/circleq.3 | 199 ++++++++++++++++++----------------------
 man3/list.3    | 159 +++++++++++++++-----------------
 man3/slist.3   | 159 +++++++++++++++-----------------
 man3/stailq.3  | 184 +++++++++++++++++--------------------
 man3/tailq.3   | 241 +++++++++++++++++++++++--------------------------
 5 files changed, 433 insertions(+), 509 deletions(-)

[...]

Quoted 4 lines
man3/slist.3 +0 -0
index 6868a63c2..1b041773e 100644

[...]

Quoted 1 line
man3/slist.3 +0 -0
@@ -200,30 +218,21 @@ turn to

[...]

man3/slist.3 turn to · line 234

Quoted 9 lines

-.PP

man3/slist.3 +5 -3
-The macro
-.BR SLIST_NEXT ()
-returns the next element in the list.
+from the head of the list.
+For optimum efficiency,
+elements being removed from the head of the list
+should explicitly use this macro instead of the generic
+.IR SLIST_REMOVE ().

s/.IR/.BR/

[...]

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#5 lore raw
Quoted 5 lines
Quoted 1 line

+.IR SLIST_REMOVE ().

s/.IR/.BR/

[...]

Fixed.

Thanks,

Mcihael

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/
#6 lore raw
In reply to Alejandro Colomar

Hi Alex,

Quoted 4 lines · Alejandro Colomar

- Group macros by kinds.
- Align so that it's easiest to distinguish differences between related macros.
(Align all continuations for consistency on PDF.)

(Thanks.)

Quoted 9 lines

- Fix minor typos.
- Remove redundant text:
'The macro xxx() ...':
The first paragraph already says that these are macros.
'circular|tail|... queue':
Don't need to repeat every time.
Generic text makes it easier to spot the differences.
- Fit lines into 78 columns.
- Reorder descriptions to match SYNOPSIS,

Thanks!

Quoted 1 line

and add subsections to DESCRIPTION.

That really helps!

Quoted 6 lines

- srcfix: fix a few smantic newlines.

I noticed a bug which should be fixed next:
CIRCLEQ_LOOP_*() return a 'struct TYPE *'.

Nice work! Patch applied.

Thanks,

Michael

[...]

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/
#7 lore raw
In reply to Alejandro Colomar

Hello Alex,

Quoted 1 line · Alejandro Colomar

- Group macros by kinds.

Looks good.

Quoted 1 line

- Align so that it's easiest to distinguish differences> between related macros.

The problem with this is that it doesn't render well in PDF [1], I think. The spaces render small in PDF, and the alignment looks random. Better to use the same indent for all continuations. Could you amend and resend please.

Quoted 1 line

- Fix minor typos.

Okay.

Quoted 1 line

- Remove redundant text ('The macro xxx() ...')> The first paragraph already says that these are macros.

Okay.

Quoted 1 line

- Fit lines into 78 columns.

Okay.

Quoted 2 lines

I noticed a bug which should be fixed next:
CIRCLEQ_LOOP_*() return a 'struct TYPE *'.

Okay.

Quoted 7 lines

---

Hi Michael,

Here's my attempt of making queue.3 pages more readable. I think it's quite nicer now.

Agreed.

Quoted 2 lines

But please, review it, because I may have introduced a few bugs while moving the text around.

At aa quick glance, it looks okay to me.

Quoted 5 lines

Also, if you feel something could be nicer, please tell me.

BTW, it's been the first time I use Vim for something not trivial, and I quite liked it.
I think I'll stop using Gedit for a while :-)

Good choice :-).

[...]

Cheers,

Michael

[1]
Usage: pdfman <man-page.n>

function pdfman {
    man -Tps -l $1 > /tmp/$(basename $1).$$.ps
    ps2pdf /tmp/$(basename $1).$$.ps $1.pdf
    evince $1.pdf
}
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/
#8 lore raw

Re: pdfman

Hey Michael,

Quoted 5 lines · Michael Kerrisk (man-pages)
function pdfman {
    man -Tps -l $1 > /tmp/$(basename $1).$$.ps
    ps2pdf /tmp/$(basename $1).$$.ps $1.pdf
    evince $1.pdf
}

Would you mind adding that to a script in scripts/?

Thanks!

Alex

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#9 lore raw

Re: pdfman

Hi Alex,

Quoted 10 lines · Alejandro Colomar (man-pages)

Hey Michael,

Quoted 5 lines · Michael Kerrisk (man-pages)
function pdfman {
    man -Tps -l $1 > /tmp/$(basename $1).$$.ps
    ps2pdf /tmp/$(basename $1).$$.ps $1.pdf
    evince $1.pdf
}

Would you mind adding that to a script in scripts/?

I'm not convinced it really belongs in there.

Thanks,

Michael

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/
#10 lore raw

Re: pdfman

[CC += Branden]

Hi Michael,

[Speleology session below]
<https://lore.kernel.org/linux-man/[email protected]/>

Quoted 11 lines · Michael

Hi Alex,

Quoted 8 lines · Alejandro Colomar (man-pages)

Hey Michael,

Quoted 5 lines · Michael Kerrisk (man-pages)
function pdfman {
    man -Tps -l $1 > /tmp/$(basename $1).$$.ps
    ps2pdf /tmp/$(basename $1).$$.ps $1.pdf
    evince $1.pdf
}

I was wondering why -Tps and then ps2pdf(1) instead of directly -Tpdf. Do you remember a reason? We still have the function around (with my rewrite, but we kept that ps thing), and was wondering if I could simplify.

Cheers,
Alex

Quoted 8 lines
Quoted 2 lines

Would you mind adding that to a script in scripts/?

I'm not convinced it really belongs in there.

Thanks,

Michael

Signature · 1 line
<https://www.alejandro-colomar.es/>