From patchwork Wed Feb 8 10:36:09 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Rical Jasan X-Patchwork-Id: 19171 Received: (qmail 18030 invoked by alias); 8 Feb 2017 10:36:21 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 16428 invoked by uid 89); 8 Feb 2017 10:36:20 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.1 required=5.0 tests=AWL, BAYES_00, RCVD_IN_DNSWL_NONE, RP_MATCHES_RCVD, SPF_PASS autolearn=ham version=3.3.2 spammy=tes, Standards, Macros, argp X-HELO: mail.pacific.net To: libc-alpha Cc: Joseph Myers , Michael Kerrisk , "Carlos O'Donell" From: Rical Jasan Subject: [RFC] [PATCH v3] manual: @standards macro Message-ID: Date: Wed, 8 Feb 2017 02:36:09 -0800 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.5.1 MIME-Version: 1.0 X-Null-Tag: 3ac5754d1539b0176a9105b2495cc375 Here is a simple take on the @standards macro, modelled after the suggestion in [1]. I put it directly under the function/variable/etc., and above @safety, because the @safety annotations are often followed by comments, sometimes more than a screenfull's worth. Doing it that way keeps all the annotations clearly grouped together, and is also visually consistent with non-functions, which will have @standards directly below them since they don't have @safety annotations. In the macro definition, I use "@sp 0" to force a paragraph break without adding extra blank lines. It accomplishes the same thing as two blank lines within the macro definition but keeps the "@end macro" more closely tied to the block of code it relates to, which is nice. I don't really have an opinion on its use; I was just sure Texinfo provided a way to force a paragraph break, so I was playing with it. It does cost a couple extra bytes. :) On the formatting of the output, specifically, listing "STD (HDR)", I would like to point out the Summary does exactly the opposite. Rical diff --git a/manual/argp.texi b/manual/argp.texi index bca3ca5..03aa0a0 100644 --- a/manual/argp.texi +++ b/manual/argp.texi @@ -36,6 +36,7 @@ needed in @code{main}. @comment argp.h @comment GNU @deftypefun {error_t} argp_parse (const struct argp *@var{argp}, int @var{argc}, char **@var{argv}, unsigned @var{flags}, int *@var{arg_index}, void *@var{input}) +@standards{GNU, argp.h} @safety{@prelim{}@mtunsafe{@mtasurace{:argpbuf} @mtslocale{} @mtsenv{}}@asunsafe{@ascuheap{} @ascuintl{} @asulock{} @asucorrupt{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} @c Optionally alloca()tes standard help options, initializes the parser, @c then parses individual args in a loop, and then finalizes. @@ -111,6 +112,7 @@ These variables make it easy for user programs to implement the @comment argp.h @comment GNU @deftypevar {const char *} argp_program_version +@standards{GNU, argp.h} If defined or set by the user program to a non-zero value, then a @samp{--version} option is added when parsing with @code{argp_parse}, which will print the @samp{--version} string followed by a newline and diff --git a/manual/macros.texi b/manual/macros.texi index 9cf8031..0b73c72 100644 --- a/manual/macros.texi +++ b/manual/macros.texi @@ -267,4 +267,10 @@ cwd\comments\ @end macro @end ifnottex +@c Format which header and standard something comes from. +@macro standards {standard, header} +Standards: \standard\ (@file{\header\}). @xref{Feature Test Macros}. +@sp 0 +@end macro + @end ifclear