From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 5506 invoked by alias); 2 Dec 2016 11:54:08 -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 5484 invoked by uid 89); 2 Dec 2016 11:54:07 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-4.0 required=5.0 tests=AWL,BAYES_00,KAM_ASCII_DIVIDERS,RCVD_IN_DNSWL_NONE,RP_MATCHES_RCVD,SPF_PASS autolearn=ham version=3.3.2 spammy=3-4, played, Concepts, annoying X-HELO: mail.pacific.net Subject: Re: [PATCH 3/3] manual: Add new header and standards annotations. To: Joseph Myers , Florian Weimer 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> Cc: libc-alpha@sourceware.org, Michael Kerrisk , "Carlos O'Donell" From: Rical Jasan Message-ID: Date: Fri, 02 Dec 2016 11:54:00 -0000 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.4.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 8bit X-Null-Tag: 159fa702512f39188da5a78f69ce7fa0 X-SW-Source: 2016-12/txt/msg00044.txt.bz2 On 11/30/2016 04:50 AM, Joseph Myers wrote: > 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.) I don't think that format will work well because the safety lines are very long. In PDF format, the line always wraps. If we did want to do that, I think we'd wrap the annotations in @multitable to get what we want, but I haven't played with it. A little off-topic, but the "Preliminary" field is completely unused, by the way. Compare: $ grep -c '@prelim{}' manual/*.texi to $ grep -c '@prelim{[^}]+}' manual/*.texi I hack my copy for regular use to get rid of it because "Preliminary: | MT..." is annoying (specifically, the empty field following the colon before the pipe separator for every single annotation, or the pipe separator before anything to bother separating MT from, however you look at it). Even then, though, the line still wraps. Back to the topic, I'm not sure that columns would take up less vertical space than lines anyway. If you gave safety half the table width (which isn't even half the page width since the annotation is nested under the function description), and it always takes two lines, it'd probably require at least 3, maybe 4 lines, and I can't imagine it'd look very good. If we're going to pay the 3-4 line price regardless, it'd probably be easier to just give each thing its own line. For example (getcwd): Safety: MT-Safe | AS-Unsafe heap | AC-Unsafe mem fd | See Section 1.2.2.1 [POSIX Safety Concepts], page 2. Standards: POSIX.1 (unistd.h), See Section 1.3.4 [Feature Test Macros], page 15. Added in: 2.0 As a general documentation standard, perhaps we'd use: @(def|item)... [@safety{...}] # required for @def* @standards{...} [@standards{...}] @addedin{...} We could also make @addedin{} an empty macro whose arguments were used by an external script (like summary.awk) to add the information into the entry in the Summary of Library Facilities, but not the full description in the manual. If people really want that info, though, it's probably better to put it there (or in both places). I can't say much about automated validation of Added In versions, as I'm not familiar with the Versions files at all. Rical