[RFC,v3] manual: @standards macro
Commit Message
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
@@ -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
@@ -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