diff mbox

[RFC,v3] manual: @standards macro

Message ID aefb779f-40ee-9dbc-1449-b0fceead5812@pacific.net
State New
Headers show

Commit Message

Rical Jasan Feb. 8, 2017, 10:36 a.m. UTC 
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 mbox

Patch

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