Re: [PATCH] queue.3: Replace incomplete example by a complete example

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

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/