From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-Status: No, score=-4.1 required=3.0 tests=AWL,BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,MAILING_LIST_MULTI, SPF_HELO_PASS,SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from sourceware.org (server2.sourceware.org [IPv6:2620:52:3:1:0:246e:9693:128c]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by dcvr.yhbt.net (Postfix) with ESMTPS id 868041F4B4 for ; Tue, 20 Oct 2020 04:08:57 +0000 (UTC) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id A5AC33857C46; Tue, 20 Oct 2020 04:08:55 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org A5AC33857C46 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1603166935; bh=tW+rcnLwORqWyKln0EyPJPLDzRItorQ/LcHBmhcWu+E=; h=References:In-Reply-To:Date:Subject:To:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=LJn87o1/77U75EGHZydA45DC7hnhX7B2xK+4a83Zjm+P7ttDpBmPNK8rTD0M0g+kO 6SMFhZQETNOMqs1A1oQm7yiWPuQl589Sv1i+G1a6m7yy6YNnJWfjEIQ7gmc2GXH20X O4laS6ZXQdbQRF6qsEGr+xZHAYxPbS9WtEN9JQqM= Received: from mail-ot1-x344.google.com (mail-ot1-x344.google.com [IPv6:2607:f8b0:4864:20::344]) by sourceware.org (Postfix) with ESMTPS id 791953857C43 for ; Tue, 20 Oct 2020 04:08:53 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 791953857C43 Received: by mail-ot1-x344.google.com with SMTP id f37so498257otf.12 for ; Mon, 19 Oct 2020 21:08:53 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:reply-to :from:date:message-id:subject:to:cc; bh=tW+rcnLwORqWyKln0EyPJPLDzRItorQ/LcHBmhcWu+E=; b=mpT/NLnHgJIBDrKAAGcpYr3C3o924BPR2hjvZrwtxsPJL+I3QlR890EC8GnjKbx+69 pYZh+46Lbkw+C6UckrCVqNdy4XMKpzXivMAmmL0s/NZHhns8Yj1Kf136r63F/OBXQDX1 /puBjnNvMb4/Gbi7I8iqkh9BxLrAOe9hT+B8O73BEVNz/jXy1uHlzIUcToladFv+jNmY 2XfzOQOejZ4ntkYbXsGjvOPTIJzJIuY7/+VO5T9X5pVSMbO/P1UbC8y4G65eCmSYw8Ni hp/QDlSt/W1tcnJ4AAk5F+AQflXg9hAOLoC4EgRq7CIjmpTRTsE/Y3cJaCoM90KqAi2R c/cQ== X-Gm-Message-State: AOAM5319bBa6rgvX5FPPC/1EIRH/kAbEGx7w9bcLB7Pb1Oj4FkpnOYIf A+yE5aUa4MKF49oLwEuQi+lEXUv5WnjeWS6SreI= X-Google-Smtp-Source: ABdhPJwd3ALU0b8c0qTkLhlARZXhJdDZXwfMausbOeE7jtdm3XcirZKhNIFhHgW1DrNUviBQheera6iGbIKcQ4XCo40= X-Received: by 2002:a9d:5183:: with SMTP id y3mr545981otg.308.1603166932699; Mon, 19 Oct 2020 21:08:52 -0700 (PDT) MIME-Version: 1.0 References: <33af3ca2-d6ea-5f75-6ad2-e2f43eefe4fa@gmail.com> In-Reply-To: <33af3ca2-d6ea-5f75-6ad2-e2f43eefe4fa@gmail.com> Date: Tue, 20 Oct 2020 06:08:41 +0200 Message-ID: Subject: Re: queue.3 overhaul To: Alejandro Colomar Content-Type: text/plain; charset="UTF-8" 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: , From: "Michael Kerrisk \(man-pages\) via Libc-alpha" Reply-To: mtk.manpages@gmail.com Cc: linux-man , "libc-alpha@sourceware.org" Errors-To: libc-alpha-bounces@sourceware.org Sender: "Libc-alpha" Hi Alex, On Mon, 19 Oct 2020 at 17:29, Alejandro Colomar wrote: > > Hi Michael, > > > I'm working on moving and fixing code from queue.3 to different pages. > > I'd like to send you patches against a separate branch, > if you would create one, to ask you some questions from time to time, > and maybe get suggestions. > > Or maybe you could look at my branch on github > (https://github.com/alejandro-colomar/man-pages/commits/queue > (I may force push changes there sometimes)) I created a remote to remote to track your work. But you'll need to ping me from time to tell me to take a look. Also, I think mail to this list to discuss directions (as you are now doing) is great. > (BTW, if you have a look there, > you can see how I'm moving&fixing the code from queue.3 > to the other pages and maybe suggest a different way). This looks okay in principle. > Or maybe I can just show you small pieces of code (no patches), > like in this email. > > Whatever works best for you. Both ;-) > What do you think about this SYNOPSIS for list.3?: > > [[ > .SH SYNOPSIS > .nf > .B #include > .PP > .BI "int LIST_EMPTY(LIST_HEAD *" head ");" > .B " LIST_ENTRY(TYPE);" > .BI "LIST_ENTRY LIST_FIRST(LIST_HEAD *" head ");" > .BI " LIST_FOREACH(TYPE *" var ", LIST_HEAD *" head ", > LIST_ENTRY " NAME ");" > .\".BI " LIST_FOREACH_FROM(TYPE *" var ", LIST_HEAD *" head ", > LIST_ENTRY " NAME ");" > .\".BI " LIST_FOREACH_SAFE(TYPE *" var ", LIST_HEAD *" head ", > LIST_ENTRY " NAME ", TYPE *" temp_var ");" > .\".BI " LIST_FOREACH_FROM_SAFE(TYPE *" var ", LIST_HEAD *" > head ", LIST_ENTRY " NAME ", TYPE *" temp_var ");" > .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_AFTER(TYPE *" listelm ", TYPE *" elm ", > LIST_ENTRY " NAME ");" > .BI "void LIST_INSERT_BEFORE(TYPE *" listelm ", TYPE *" elm ", > LIST_ENTRY " NAME ");" > .BI "void LIST_INSERT_HEAD(LIST_HEAD *" head ", TYPE *" elm ", > LIST_ENTRY " NAME ");" > .BI "LIST_ENTRY LIST_NEXT(TYPE *" elm ", LIST_ENTRY " NAME ");" > .\".BI "LIST_ENTRY LIST_PREV(TYPE *" elm ", LIST_HEAD *" head ", TYPE, > LIST_ENTRY " NAME ");" > .BI "void LIST_REMOVE(TYPE *" elm ", LIST_ENTRY " NAME ");" > .\".BI "void IST_SWAP(LIST_HEAD *" head1 ", LIST_HEAD *" head2 ", > TYPE, LIST_ENTRY " NAME ");" > .fi > ]] > > Things to note: > - The (many) spaces are there because otherwise it's unreadable (at > least for me). But, I find the indentation confusing actually. When I see pieces such as int LIST_EMPTY(LIST_HEAD *head); LIST_ENTRY(TYPE); It visually looks to me as though the LIST_ENTRY piece is some extension of the LIST_EMPTY pest. I think it's best not to do horizontal indentation, but instead just use of vertical separation (.PP). We can perhaps revisit this later, to see if we can come up with something better. > Also, I kept the copyright from the University of California and added > myself: I consider this to be a modified redistribution but not a > derived product; maybe I'm wrong in that (I'm not a lawyer :)). This seems okay to me. Thanks. Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/