From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wr1-x442.google.com (mail-wr1-x442.google.com [IPv6:2a00:1450:4864:20::442]) by sourceware.org (Postfix) with ESMTPS id B89403857C44 for ; Fri, 2 Oct 2020 13:51:20 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org B89403857C44 Received: by mail-wr1-x442.google.com with SMTP id j2so1921243wrx.7 for ; Fri, 02 Oct 2020 06:51:20 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:cc:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=Vba10Vt0Q0e+Fcq2NQXhqcLYP73jXyfFw64w/PRkS04=; b=chCybjCsHWYSe6oJ8xYhQ5BjwBUM902m5U97S26kuWZBVGOd0d4tx1g4vS9LNk4nKv 74wdo6sBkUDZthiV5UqOD9kiI3x3m+cRUSZ0bv/aN9NsJfKA8cNK4DmGO782vXSz/rF5 YigFYnatofupGHw/l+MR0Y6PpoHPlzgEuxDa0Ug9iGwWBDyDQ7aTlwZN5GdjYYCX94Ox UqvXvTAy9buo4eHk76Q6h+0GBv27CfOglz5wOL6fEN6ypv4XIgiA0H+XBd1Kz/gexkPA AEIdP/6J2V5qardcHqSNyOkrmOgXv8QpGIW/z6KvJDsi0sOiOCIQkuDKhk2VUJO/Vz71 5rjw== X-Gm-Message-State: AOAM532qjgeZrmOjkCVrKqimqqE0TAB3PSDFvYForCL2AWZLqcuYOLTV ST2dSWHVSJ07fED8dRadwTg= X-Google-Smtp-Source: ABdhPJwLwY8J/GK5s7NhzaUOdIpBuHRondijHUaTN4Eebis6cTq3wLry2NFuJwwJLQzFvb71tVIgWw== X-Received: by 2002:adf:a3d4:: with SMTP id m20mr3433422wrb.29.1601646679785; Fri, 02 Oct 2020 06:51:19 -0700 (PDT) Received: from [192.168.1.143] ([170.253.60.68]) by smtp.gmail.com with ESMTPSA id a15sm1966268wrn.3.2020.10.02.06.51.18 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Fri, 02 Oct 2020 06:51:19 -0700 (PDT) Subject: Re: [PATCH v2 1/2] system_data_types.7: Add 'void *' To: Jonathan Wakely Cc: "Michael Kerrisk (man-pages)" , Paul Eggert , linux-man , GNU C Library , "linux-kernel@vger.kernel.org" , "gcc@gcc.gnu.org" References: <41affebd-3354-9420-0048-bffd14535e95@gmail.com> <20201001154946.104626-2-colomar.6.4.3@gmail.com> <538b683f-01d2-6148-4f1d-1b293eb5cd6b@cs.ucla.edu> <4b86f6e9-0d8a-f14a-73ce-ebbdc9d9edba@gmail.com> <63826e82-7a19-0ecc-f73c-56aa560a842f@gmail.com> From: Alejandro Colomar Message-ID: <4422e4bc-f54c-02cf-9b47-808d07ce8ba5@gmail.com> Date: Fri, 2 Oct 2020 15:51:17 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.12.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit X-Spam-Status: No, score=-4.8 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_ENVFROM_END_DIGIT, FREEMAIL_FROM, NICE_REPLY_A, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=unavailable 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: Fri, 02 Oct 2020 13:51:22 -0000 Hi Jonathan, On 2020-10-02 15:27, Jonathan Wakely wrote: > On Fri, 2 Oct 2020 at 14:20, Alejandro Colomar wrote: >> >> >> >> On 2020-10-02 15:06, Jonathan Wakely wrote: >> > On Fri, 2 Oct 2020 at 12:31, Michael Kerrisk (man-pages) >> > wrote: >> >> >> >> On Fri, 2 Oct 2020 at 12:49, Jonathan Wakely >> wrote: >> >>> >> >>> On Fri, 2 Oct 2020 at 09:28, Alejandro Colomar via Gcc >> wrote: >> >>>> However, it might be good that someone starts a page called >> >>>> 'type_qualifiers(7)' or something like that. >> >>> >> >>> Who is this for? Who is trying to learn C from man pages? Should >> >>> somebody stop them? >> >> >> >> Yes, I think so. To add context, Alex has been doing a lot of work to >> >> build up the new system_data_types(7) page [1], which I think is >> >> especially useful for the POSIX system data types that are used with >> >> various APIs. >> > >> > It's definitely useful for types like struct siginfo_t and struct >> > timeval, which aren't in C. >> >> Hi Jonathan, >> >> But then the line is a bit diffuse. >> Would you document 'ssize_t' and not 'size_t'? > > Yes. My documentation for ssize_t would mention size_t, refer to the C > standard, and not define it. > >> Would you not document intN_t types? >> Would you document stdint types, including 'intptr_t', and not 'void *'? > > I would document neither. > > I can see some small value in documenting size_t and the stdint types, > as they are technically defined by the libc headers. But documenting > void* seems very silly. It's one of the most fundamental built-in > parts of the C language, not an interface provided by the system. > >> I guess the basic types (int, long, ...) can be left out for now, > > I should hope so! > >> and apart from 'int' those rarely are the most appropriate types >> for most uses. >> But other than that, I would document all of the types. >> And even... when all of the other types are documented, >> it will be only a little extra effort to document those, >> so in the future I might consider that. > > [insert Jurassic Park meme "Your scientists were so preoccupied with > whether or not they could, they didn't stop to think if they should." > ] > > I don't see value in bloating the man-pages with information nobody > will ever use, and which doesn't (IMHO) belong there anyway. We seem > to fundamentally disagree about what the man pages are for. I don't > think they are supposed to teach C programming from scratch. Agree in part. I'll try to think about it again. In the meantime, I trust Michael to tell me when something is way off :) Thanks, really! Alex > > >> But yes, priority should probably go to Linux/POSIX-only types.