From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wr1-x444.google.com (mail-wr1-x444.google.com [IPv6:2a00:1450:4864:20::444]) by sourceware.org (Postfix) with ESMTPS id 48389385EC4E for ; Mon, 12 Oct 2020 18:47:50 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 48389385EC4E Received: by mail-wr1-x444.google.com with SMTP id h7so20408063wre.4 for ; Mon, 12 Oct 2020 11:47:50 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:cc:subject:to:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=uIkc77kFXLdTYhNQ7TRYHEDCbzyZzV5AlgloUroJepo=; b=do/GDkglt+iv4iE2i10yt0ZkxGYDJ/RrN+21wFp3/cF413mqNoRlLLw6EJC/qbaEZE 6X3mMVYpfmhpEaCo186jGG6e8BT4J01AqT3gYE4JIwq+MP8hA3RsiZ/e+EPy5Luajy/4 P/+eYqI1/QcRIuylio56ZOzuOHAi/uyJLb1ydFUXXpx8lUNkt2pMre09pNTKmcarqWHj 5cv2GtubNvGuAgYzN+cA3swK+wfOVqe+BZdQZ7cY7lyE1dqn8xFYVO+LO0gFvvAcwzwL w7CdXuuVHLOjE/Akby5oa4g6fD1A9+2fbJU+kibnFSFTr0GqkxwrFnfWOmzP11oqY0ki PuXg== X-Gm-Message-State: AOAM5319tUvt+ZBVD66RJ6dioImx7sPCXMQ05gMtD4KCFW0Lf1T7jlbi ksst4OTHdqMFp3Sa9DdZ01RnLfV5mxI= X-Google-Smtp-Source: ABdhPJxuSeZs+YGG856yPg4v6/EkXbGYB9pTCq8b37DbhhvkljZ0uCe8vmdWM1NwHdrMZ9+rrgpq7w== X-Received: by 2002:adf:ed52:: with SMTP id u18mr32832242wro.357.1602528469042; Mon, 12 Oct 2020 11:47:49 -0700 (PDT) Received: from [192.168.1.10] (static-176-175-73-29.ftth.abo.bbox.fr. [176.175.73.29]) by smtp.gmail.com with ESMTPSA id t6sm29090551wre.30.2020.10.12.11.47.47 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Mon, 12 Oct 2020 11:47:48 -0700 (PDT) Cc: mtk.manpages@gmail.com, linux-man , GNU C Library Subject: Re: [PATCH] queue.3: Replace incomplete example by a complete example To: Zack Weinberg , Alejandro Colomar References: <20201010190226.19236-1-colomar.6.4.3@gmail.com> From: "Michael Kerrisk (man-pages)" Message-ID: Date: Mon, 12 Oct 2020 20:47:46 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.11.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit X-Spam-Status: No, score=-4.4 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_FROM, KAM_SHORT, NICE_REPLY_A, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 12 Oct 2020 18:47:53 -0000 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 > 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. > > 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/