From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 27593 invoked by alias); 30 Nov 2016 12:50:51 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Received: (qmail 27575 invoked by uid 89); 30 Nov 2016 12:50:50 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.2 required=5.0 tests=AWL,BAYES_00,KAM_ASCII_DIVIDERS,RCVD_IN_DNSWL_NONE,SPF_PASS,URIBL_RED autolearn=no version=3.3.2 spammy=PDF, oldest, boxes X-HELO: relay1.mentorg.com Date: Wed, 30 Nov 2016 12:50:00 -0000 From: Joseph Myers To: Florian Weimer CC: Rical Jasan , , Michael Kerrisk , Carlos O'Donell Subject: Re: [PATCH 3/3] manual: Add new header and standards annotations. In-Reply-To: Message-ID: References: <20161123063807.14845-1-ricaljasan@pacific.net> <20161123063807.14845-4-ricaljasan@pacific.net> <64fa1a5a-4af3-5e3f-b192-e79203c3e328@pacific.net> <951c0013-8227-46c3-6d05-678bca61f2ce@pacific.net> User-Agent: Alpine 2.20 (DEB 67 2015-01-07) MIME-Version: 1.0 Content-Type: text/plain; charset="US-ASCII" X-ClientProxiedBy: svr-ies-mbx-01.mgc.mentorg.com (139.181.222.1) To svr-ies-mbx-01.mgc.mentorg.com (139.181.222.1) X-SW-Source: 2016-11/txt/msg01100.txt.bz2 On Wed, 30 Nov 2016, Florian Weimer wrote: > Many programmers would also find annotations which glibc version introduced a > particular functionality *extremely* useful, especially for functions that > were added after glibc 2.5 or so. It's not a standard as such (but LSB would > be), but I think it serves a similar purpose. > > Can we reconsider adding this kind of information to the manual? That seems reasonable (given appropriate automatic checks - that the version documented for a function is the same as the oldest symbol version with that function in any Versions file, I suppose, which would also be a way of populating such annotations for functions though not for non-function interfaces, as long as you don't care about distinguishing versions before 2.1). In HTML and PDF manuals it might be nice (and more compact) if things looked like: ----------------------------- ---------------------- ----------- |Safety (preliminary): | |Standards: | |Added in:| |MT-Safe | AS-Safe | AC-Safe| |POSIX.1 (unistd.h) | |2.4 | ----------------------------- ---------------------- ----------- with a series of boxes that can go next to each other rather than taking a lot of vertical space (and with "Safety" and "Standards" being links to the relevant manual sections). I don't know if this can be achieved with different macro definitions for different output formats (and it's not something to require for the first version of standards annotations, anyway). (There are also issues of what it should look like when you have long standard descriptions, etc.) -- Joseph S. Myers joseph@codesourcery.com