>Number:         36857
>Category:       misc
>Synopsis:       Add a summary section in queue(3) man page
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    misc-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Wed Aug 29 13:10:00 +0000 2007
>Originator:     Stathis Kamperis
>Release:        NetBSD 4.0BETA2
>Organization:
Aristotle University of Thessaloniki
>Environment:
NetBSD netbsd 4.0_BETA2 NetBSD 4.0_BETA2 (MYGENERIC) #3: Tue Aug 28 14:23:03 EEST 2007  root@netbsd:/usr/obj/sys/arch/i386/compile/MYGENERIC i386

>Description:
Due to the large number of data structure types and the associated macros, it would be useful to have a table summarizing all of them.

I attach a patch that adds a `SUMMARY' section in man 3 queue. Since my code uses the tbl preprocessor to format the table, I had also to add USETBL= in the Makefile.

In order to see how the man page looks after the patch has been applied, you may run:

$ cd /usr/share/man/man3
$ groff -tbl -mdoc -Tascii queue.3 | col -bx

>How-To-Repeat:

>Fix:
Index: Makefile
===================================================================
RCS file: /cvsroot/src/share/man/man3/Makefile,v
retrieving revision 1.30
diff -u -r1.30 Makefile
--- Makefile	15 Aug 2007 03:53:09 -0000	1.30
+++ Makefile	29 Aug 2007 12:50:10 -0000
@@ -3,6 +3,9 @@
 
 MAN=	_DIAGASSERT.3 assert.3 bits.3 bitstring.3 dlfcn.3 end.3 gcq.3 \
 	intro.3 queue.3 stdarg.3 sysexits.3 tree.3 varargs.3
+
+USETBL=
+
 MLINKS+=end.3 edata.3 end.3 etext.3
 MLINKS+=bits.3 __BIT.3 \
 	bits.3 __BITS.3 \
Index: queue.3
===================================================================
RCS file: /cvsroot/src/share/man/man3/queue.3,v
retrieving revision 1.33
diff -u -r1.33 queue.3
--- queue.3	7 Mar 2006 18:13:43 -0000	1.33
+++ queue.3	29 Aug 2007 12:50:11 -0000
@@ -1131,6 +1131,57 @@
 if (CIRCLEQ_EMPTY(\*[Am]head))		/* Test for emptiness. */
 	printf("nothing to do\\n");
 .Ed
+.Sh SUMMARY
+The following table summarizes the supported macros for each type of data structure.
+.Pp
+.TS
+box tab(:);
+l | c | c | c | c | c | c
+l | c | c | c | c | c | c
+l | c | c | c | c | c | c
+l | c | c | c | c | c | c
+l | c | c | c | c | c | c
+l | c | c | c | c | c | c.
+:SLIST:LIST:SIMPLEQ:STAILQ:TAILQ:CIRCLEQ
+_
+_EMPTY:+:+:+:+:+:+
+_ENTRY:+:+:+:+:+:+
+_FIRST:+:+:+:+:+:+
+_FOREACH:+:+:+:+:+:+
+_FOREACH_REVERSE:-:-:-:-:+:+
+_HEAD:+:+:+:+:+:+
+_HEAD_INITIALIZER:+:+:+:+:+:+
+_INIT:+:+:+:+:+:+
+_INSERT_AFTER:+:+:+:+:+:+
+_INSERT_BEFORE:-:+:-:-:+:+
+_INSERT_HEAD:+:+:+:+:+:+
+_INSERT_TAIL:-:-:+:+:+:+
+_LAST:-:-:-:-:+:+
+_LOOP_NEXT:-:-:-:-:-:+
+_LOOP_PREV:-:-:-:-:-:+
+_NEXT:+:+:+:+:+:+
+_PREV:-:-:-:-:+:+
+_REMOVE:+:+:+:+:+:+
+_REMOVE_HEAD:+:-:+:+:-:-
+.TE
+.Pp
+As far as the cost of each data structure is concerned:
+.Bl -enum -compact -offset indent
+.It
+.Nm Singly-linked lists
+are ideal for applications with large datasets and few or no removals,
+or for implementing a LIFO queue.
+.It
+.Nm Simple queues
+are ideal for applications with large datasets and few or
+no removals, or for implementing a FIFO queue.
+.It
+For
+.Nm doubly linked types
+of data structures (lists, tail queues, and circle queues),
+the code size and execution time of operations (except for removal) is about
+twice that of the singly-linked data-structures.
+.El
 .Sh HISTORY
 The
 .Nm queue