Linux-man Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH] queue.3: Replace incomplete example by a complete example
@ 2020-10-10 19:02 Alejandro Colomar
  2020-10-10 19:08 ` Alejandro Colomar
                   ` (2 more replies)
  0 siblings, 3 replies; 7+ messages in thread
From: Alejandro Colomar @ 2020-10-10 19:02 UTC (permalink / raw)
  To: mtk.manpages; +Cc: Alejandro Colomar, linux-man, libc-alpha

I added the EXAMPLES section.
The examples in this page are incomplete
(you can't copy&paste&compile&run).
I fixed the one about TAILQ first,
and the rest should follow.

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---

Hi Michael,

I think this page needs a big overhaul.

First of all, it's a very big page,
where it's a bit difficult to go to the subsection you want.
Then, the examples are incomplete.
And also, the language of the page is weird.

I thought about having queue.h with an overview of all the different
data structures, and the differences about them.

And then separate pages for each data structure:
slist.3, list.3,
stailq.3, tailq.3,
simpleq.3 (which right now isn't documented),
and circleq.3
with details about each macro and a complete example program.

Your thoughts?

Cheers,

Alex


 man3/queue.3 | 115 ++++++++++++++++++++++++++-------------------------
 1 file changed, 59 insertions(+), 56 deletions(-)

diff --git a/man3/queue.3 b/man3/queue.3
index 55cd5847e..ea43f018b 100644
--- a/man3/queue.3
+++ b/man3/queue.3
@@ -1220,62 +1220,8 @@ from the tail queue.
 .\" .Fa head1
 .\" and
 .\" .Fa head2 .
-.Ss Tail queue example
-.Bd -literal
-TAILQ_HEAD(tailhead, entry) head =
-    TAILQ_HEAD_INITIALIZER(head);
-struct tailhead *headp;			/* Tail queue head. */
-struct entry {
-	...
-	TAILQ_ENTRY(entry) entries;	/* Tail queue. */
-	...
-} *n1, *n2, *n3, *np;
-
-TAILQ_INIT(&head);			/* Initialize the queue. */
-
-n1 = malloc(sizeof(struct entry));	/* Insert at the head. */
-TAILQ_INSERT_HEAD(&head, n1, entries);
-
-n1 = malloc(sizeof(struct entry));	/* Insert at the tail. */
-TAILQ_INSERT_TAIL(&head, n1, entries);
-
-n2 = malloc(sizeof(struct entry));	/* Insert after. */
-TAILQ_INSERT_AFTER(&head, n1, n2, entries);
-
-n3 = malloc(sizeof(struct entry));	/* Insert before. */
-TAILQ_INSERT_BEFORE(n2, n3, entries);
-
-TAILQ_REMOVE(&head, n2, entries);	/* Deletion. */
-free(n2);
-					/* Forward traversal. */
-TAILQ_FOREACH(np, &head, entries)
-	np\-> ...
-.\" 					/* Safe forward traversal. */
-.\" TAILQ_FOREACH_SAFE(np, &head, entries, np_temp) {
-.\" 	np\->do_stuff();
-.\" 	...
-.\" 	TAILQ_REMOVE(&head, np, entries);
-.\" 	free(np);
-.\" }
-					/* Reverse traversal. */
-TAILQ_FOREACH_REVERSE(np, &head, tailhead, entries)
-	np\-> ...
-					/* TailQ Deletion. */
-while (!TAILQ_EMPTY(&head)) {
-	n1 = TAILQ_FIRST(&head);
-	TAILQ_REMOVE(&head, n1, entries);
-	free(n1);
-}
-					/* Faster TailQ Deletion. */
-n1 = TAILQ_FIRST(&head);
-while (n1 != NULL) {
-	n2 = TAILQ_NEXT(n1, entries);
-	free(n1);
-	n1 = n2;
-}
-
-TAILQ_INIT(&head);
-.Ed
+.Pp
+See the EXAMPLES section below for an example program using a tail queue.
 .Ss Circular queues
 A circular queue is headed by a structure defined by the
 .Nm CIRCLEQ_HEAD
@@ -1462,6 +1408,63 @@ while (n1 != (void *)&head) {
 
 CIRCLEQ_INIT(&head);
 .Ed
+.Sh EXAMPLES
+.Ss Tail queue example
+.Bd -literal
+#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/queue.h>
+
+struct entry {
+    int data;
+    TAILQ_ENTRY(entry) entries;             /* Tail queue. */
+};
+
+TAILQ_HEAD(tailhead, entry);
+
+int
+main(void)
+{
+    struct entry    *n1, *n2, *n3, *np;
+    struct tailhead head;                   /* Tail queue head. */
+    int     i;
+
+    TAILQ_INIT(&head);                      /* Initialize the queue. */
+
+    n1 = malloc(sizeof(struct entry));      /* Insert at the head. */
+    TAILQ_INSERT_HEAD(&head, n1, entries);
+
+    n1 = malloc(sizeof(struct entry));      /* Insert at the tail. */
+    TAILQ_INSERT_TAIL(&head, n1, entries);
+
+    n2 = malloc(sizeof(struct entry));      /* Insert after. */
+    TAILQ_INSERT_AFTER(&head, n1, n2, entries);
+
+    n3 = malloc(sizeof(struct entry));      /* Insert before. */
+    TAILQ_INSERT_BEFORE(n2, n3, entries);
+
+    TAILQ_REMOVE(&head, n2, entries);       /* Deletion. */
+    free(n2);
+                                            /* Forward traversal. */
+    i = 0;
+    TAILQ_FOREACH(np, &head, entries)
+        np->data = i++;
+                                            /* Reverse traversal. */
+    TAILQ_FOREACH_REVERSE(np, &head, tailhead, entries)
+        printf("%i\en", np->data);
+                                            /* TailQ Deletion. */
+    n1 = TAILQ_FIRST(&head);
+    while (n1 != NULL) {
+        n2 = TAILQ_NEXT(n1, entries);
+        free(n1);
+        n1 = n2;
+    }
+    TAILQ_INIT(&head);
+
+    exit(EXIT_SUCCESS);
+}
+.Ed
 .Sh CONFORMING TO
 Not in POSIX.1, POSIX.1-2001 or POSIX.1-2008.
 Present on the BSDs.
-- 
2.28.0


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] queue.3: Replace incomplete example by a complete example
  2020-10-10 19:02 [PATCH] queue.3: Replace incomplete example by a complete example Alejandro Colomar
@ 2020-10-10 19:08 ` Alejandro Colomar
  2020-10-11  6:00 ` Michael Kerrisk (man-pages)
  2020-10-12 12:53 ` Zack Weinberg
  2 siblings, 0 replies; 7+ messages in thread
From: Alejandro Colomar @ 2020-10-10 19:08 UTC (permalink / raw)
  To: mtk.manpages; +Cc: linux-man, libc-alpha



On 2020-10-10 21:02, Alejandro Colomar wrote:
> I thought about having queue.h with an overview of all the different
I meant queue.3 (instead of queue.h).
However, thinking about it,
if we strip if from the details about all of the macros,
it might be better as queue.7.

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] queue.3: Replace incomplete example by a complete example
  2020-10-10 19:02 [PATCH] queue.3: Replace incomplete example by a complete example Alejandro Colomar
  2020-10-10 19:08 ` Alejandro Colomar
@ 2020-10-11  6:00 ` Michael Kerrisk (man-pages)
  2020-10-11  9:03   ` Alejandro Colomar
  2020-10-12 12:53 ` Zack Weinberg
  2 siblings, 1 reply; 7+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-10-11  6:00 UTC (permalink / raw)
  To: Alejandro Colomar; +Cc: mtk.manpages, linux-man, libc-alpha

Hello Alex:

On 10/10/20 9:02 PM, Alejandro Colomar wrote:
> I added the EXAMPLES section.
> The examples in this page are incomplete
> (you can't copy&paste&compile&run).
> I fixed the one about TAILQ first,
> and the rest should follow.
> 
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>

I have not (yet) applied this patch, because...

> ---
> 
> Hi Michael,
> 
> I think this page needs a big overhaul.

... you are probably right. (And thank you for thinking
about the big picture.)

As you are probably aware, the page was essentially
lifted from BSD, and lightly edited, and this accounts
for many oddities by comparison with other pages.

> First of all, it's a very big page,
> where it's a bit difficult to go to the subsection you want.

Agreed.

> Then, the examples are incomplete.
> And also, the language of the page is weird.

Yes, there are some rather strange pieces in the page.
Just now, I noticed statements about % code size increase, etc,
which I'm sure were not measured on Linux (and in any case, such
numbers are prone to change, and don't belong in a manual page).

> I thought about having queue.h with an overview of all the different
> data structures, and the differences about them.
> 
> And then separate pages for each data structure:
> slist.3, list.3,
> stailq.3, tailq.3,
> simpleq.3 (which right now isn't documented),
> and circleq.3
> with details about each macro and a complete example program.
> 
> Your thoughts?

The above sounds about right to me. I'd happily accept patches
to do that, if you want to work on this.

One thing I'd ask though. Unlike almost every page in
man-pages, this page uses mandoc mark-up (rather than "man").
This was a matter of the history, where at some point I
refreshed the page from BSD, and decided to retain the
mandoc markup,so that if a refresh was ever again done,
the diff would be easy to comprehend. If you do decide
to do this work, I think it would be desirable
to switch to "man" markup. Sound okay?

Replying to your other mail:

On 10/10/20 9:08 PM, Alejandro Colomar wrote:
> 
> 
> On 2020-10-10 21:02, Alejandro Colomar wrote:
>> I thought about having queue.h with an overview of all the different
> I meant queue.3 (instead of queue.h).

Okay.

> However, thinking about it,
> if we strip if from the details about all of the macros,
> it might be better as queue.7.

Let's leave it as queue.3 for the moment. If it makes 
sense, we can easily switch it later, as the final step.

Thanks,

Michael

-- 
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] 7+ messages in thread

* Re: [PATCH] queue.3: Replace incomplete example by a complete example
  2020-10-11  6:00 ` Michael Kerrisk (man-pages)
@ 2020-10-11  9:03   ` Alejandro Colomar
  2020-10-11 12:24     ` Michael Kerrisk (man-pages)
  0 siblings, 1 reply; 7+ messages in thread
From: Alejandro Colomar @ 2020-10-11  9:03 UTC (permalink / raw)
  To: Michael Kerrisk (man-pages); +Cc: linux-man, libc-alpha



On 2020-10-11 08:00, Michael Kerrisk (man-pages) wrote:
> Hello Alex:
> 
> On 10/10/20 9:02 PM, Alejandro Colomar wrote:
>> I added the EXAMPLES section.
>> The examples in this page are incomplete
>> (you can't copy&paste&compile&run).
>> I fixed the one about TAILQ first,
>> and the rest should follow.
>>
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> 
> I have not (yet) applied this patch, because...


Hi Michael,

I thought that we could do it in the following steps:

1) Fix the current page:
	- Complete examples
	- Use standard sections (such as EXAMPLES)
2) Move the code from this page to new separate pages
3) Fix the code in all of those pages to use "man" macros

This way, the history can be easily followed in git,
instead of having a few commits breaking everything.

Also, I think this way it might be easier,
and the improvements (such as better examples)
can be seen from the beginning.
Part 1 could be applied directly,
while parts 2 & 3 should be applied at once.

If the change was done abruptly, you couldn't apply any commits
until all of the work is finished
(otherwise, you would have broken pages).

So I think this patch can be applied as part of this change.

Cheers,

Alex

> 
>> ---
>>
>> Hi Michael,
>>
>> I think this page needs a big overhaul.
> 
> ... you are probably right. (And thank you for thinking
> about the big picture.)
> 
> As you are probably aware, the page was essentially
> lifted from BSD, and lightly edited, and this accounts
> for many oddities by comparison with other pages.
> 
>> First of all, it's a very big page,
>> where it's a bit difficult to go to the subsection you want.
> 
> Agreed.
> 
>> Then, the examples are incomplete.
>> And also, the language of the page is weird.
> 
> Yes, there are some rather strange pieces in the page.
> Just now, I noticed statements about % code size increase, etc,
> which I'm sure were not measured on Linux (and in any case, such
> numbers are prone to change, and don't belong in a manual page).


Agreed.

> 
>> I thought about having queue.h with an overview of all the different
>> data structures, and the differences about them.
>>
>> And then separate pages for each data structure:
>> slist.3, list.3,
>> stailq.3, tailq.3,
>> simpleq.3 (which right now isn't documented),
>> and circleq.3
>> with details about each macro and a complete example program.
>>
>> Your thoughts?
> 
> The above sounds about right to me. I'd happily accept patches
> to do that, if you want to work on this.


:-)

> 
> One thing I'd ask though. Unlike almost every page in
> man-pages, this page uses mandoc mark-up (rather than "man").
> This was a matter of the history, where at some point I
> refreshed the page from BSD, and decided to retain the
> mandoc markup,so that if a refresh was ever again done,
> the diff would be easy to comprehend. If you do decide
> to do this work, I think it would be desirable
> to switch to "man" markup. Sound okay?


Yes.

> 
> Replying to your other mail:
> 
> On 10/10/20 9:08 PM, Alejandro Colomar wrote:
>>
>>
>> On 2020-10-10 21:02, Alejandro Colomar wrote:
>>> I thought about having queue.h with an overview of all the different
>> I meant queue.3 (instead of queue.h).
> 
> Okay.
> 
>> However, thinking about it,
>> if we strip if from the details about all of the macros,
>> it might be better as queue.7.
> 
> Let's leave it as queue.3 for the moment. If it makes
> sense, we can easily switch it later, as the final step.


Agree.

> 
> Thanks,
> 
> Michael
> 

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] queue.3: Replace incomplete example by a complete example
  2020-10-11  9:03   ` Alejandro Colomar
@ 2020-10-11 12:24     ` Michael Kerrisk (man-pages)
  0 siblings, 0 replies; 7+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-10-11 12:24 UTC (permalink / raw)
  To: Alejandro Colomar; +Cc: mtk.manpages, linux-man, libc-alpha

Hello Alex,

On 10/11/20 11:03 AM, Alejandro Colomar wrote:
> 
> 
> On 2020-10-11 08:00, Michael Kerrisk (man-pages) wrote:
>> Hello Alex:
>>
>> On 10/10/20 9:02 PM, Alejandro Colomar wrote:
>>> I added the EXAMPLES section.
>>> The examples in this page are incomplete
>>> (you can't copy&paste&compile&run).
>>> I fixed the one about TAILQ first,
>>> and the rest should follow.
>>>
>>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>>
>> I have not (yet) applied this patch, because...
> 
> 
> Hi Michael,
> 
> I thought that we could do it in the following steps:
> 
> 1) Fix the current page:
> 	- Complete examples
> 	- Use standard sections (such as EXAMPLES)
> 2) Move the code from this page to new separate pages
> 3) Fix the code in all of those pages to use "man" macros
> 
> This way, the history can be easily followed in git,
> instead of having a few commits breaking everything.
> 
> Also, I think this way it might be easier,
> and the improvements (such as better examples)
> can be seen from the beginning.
> Part 1 could be applied directly,
> while parts 2 & 3 should be applied at once.
> 
> If the change was done abruptly, you couldn't apply any commits
> until all of the work is finished
> (otherwise, you would have broken pages).
> 
> So I think this patch can be applied as part of this change.
Thanks for the excellent clarification. Patch applied!

Cheers,

Michael

-- 
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] 7+ messages in thread

* Re: [PATCH] queue.3: Replace incomplete example by a complete example
  2020-10-10 19:02 [PATCH] queue.3: Replace incomplete example by a complete example Alejandro Colomar
  2020-10-10 19:08 ` Alejandro Colomar
  2020-10-11  6:00 ` Michael Kerrisk (man-pages)
@ 2020-10-12 12:53 ` Zack Weinberg
  2020-10-12 18:47   ` Michael Kerrisk (man-pages)
  2 siblings, 1 reply; 7+ messages in thread
From: Zack Weinberg @ 2020-10-12 12:53 UTC (permalink / raw)
  To: Alejandro Colomar; +Cc: Michael Kerrisk (man-pages), linux-man, GNU C Library

On Sat, Oct 10, 2020 at 3:04 PM Alejandro Colomar via Libc-alpha
<libc-alpha@sourceware.org> wrote:
>
> I think this page needs a big overhaul.
>
> First of all, it's a very big page,
> where it's a bit difficult to go to the subsection you want.
> Then, the examples are incomplete.
> And also, the language of the page is weird.

<sys/queue.h> was, IIUC, originally an implementation detail of the
original BSD kernel, not intended for use elsewhere. Elsewhere started
using it anyway, and that's why glibc has it; there was, at one time,
enough user space software that assumed its existence to make a
compatibility implementation worthwhile. But I don't think its use
should be encouraged in new software, and in fact I'm not sure it
should be documented at all.

zw

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] queue.3: Replace incomplete example by a complete example
  2020-10-12 12:53 ` Zack Weinberg
@ 2020-10-12 18:47   ` Michael Kerrisk (man-pages)
  0 siblings, 0 replies; 7+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-10-12 18:47 UTC (permalink / raw)
  To: Zack Weinberg, Alejandro Colomar; +Cc: mtk.manpages, linux-man, GNU C Library

Hi Zack,

On 10/12/20 2:53 PM, Zack Weinberg wrote:
> On Sat, Oct 10, 2020 at 3:04 PM Alejandro Colomar via Libc-alpha
> <libc-alpha@sourceware.org> wrote:
>>
>> I think this page needs a big overhaul.
>>
>> First of all, it's a very big page,
>> where it's a bit difficult to go to the subsection you want.
>> Then, the examples are incomplete.
>> And also, the language of the page is weird.
> 
> <sys/queue.h> was, IIUC, originally an implementation detail of the
> original BSD kernel, not intended for use elsewhere. Elsewhere started
> using it anyway, and that's why glibc has it; there was, at one time,
> enough user space software that assumed its existence to make a
> compatibility implementation worthwhile. But I don't think its use
> should be encouraged in new software, and in fact I'm not sure it
> should be documented at all.

Thanks for the input.

From my perspective, not documenting something is a poor 
way of discouraging the use of that something. Instead,
some people just use it badly. I've no problem with
adding a note discouraging the use of the APIs, if that's
the rough consensus, though.

Thanks,

Michael

-- 
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] 7+ messages in thread

end of thread, back to index

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-10-10 19:02 [PATCH] queue.3: Replace incomplete example by a complete example Alejandro Colomar
2020-10-10 19:08 ` Alejandro Colomar
2020-10-11  6:00 ` Michael Kerrisk (man-pages)
2020-10-11  9:03   ` Alejandro Colomar
2020-10-11 12:24     ` Michael Kerrisk (man-pages)
2020-10-12 12:53 ` Zack Weinberg
2020-10-12 18:47   ` Michael Kerrisk (man-pages)

Linux-man Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-man/0 linux-man/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-man linux-man/ https://lore.kernel.org/linux-man \
		linux-man@vger.kernel.org
	public-inbox-index linux-man

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-man


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git