Hi Bruno, Bruno Haible via Gnulib discussion list <bug-gnulib@gnu.org> writes:
> As a step to further its adoption, can someone please document the > modules > version-etc > version-etc-fsf > argp-version-etc > in the Gnulib manual? (Not always me :) Simon? Collin?) Sure, I pushed the attached. I'm not great with texinfo, so feel free to improve if you see fit. For the version-etc module I only documented the version_etc function. I haven't seen the others (e.g. version_etc_va) used externally. And they are close enough that a quick look at version-etc.h would let you understand how they work. Collin
>From 64b120efb9cad480983cb779e4fc552e5fd79230 Mon Sep 17 00:00:00 2001 From: Collin Funk <collin.fu...@gmail.com> Date: Tue, 28 Jan 2025 20:52:17 -0800 Subject: [PATCH] doc: Document version-etc, version-etc, and argp-version-etc. * doc/version-etc.texi: New file. * doc/gnulib.texi (Particular Modules): Include it. --- ChangeLog | 6 +++ doc/gnulib.texi | 3 ++ doc/version-etc.texi | 104 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 113 insertions(+) create mode 100644 doc/version-etc.texi diff --git a/ChangeLog b/ChangeLog index bf91899783..8545974cae 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2025-01-28 Collin Funk <collin.fu...@gmail.com> + + doc: Document version-etc, version-etc, and argp-version-etc. + * doc/version-etc.texi: New file. + * doc/gnulib.texi (Particular Modules): Include it. + 2025-01-28 Bruno Haible <br...@clisp.org> git-version-gen: Change suffix. diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 6a7ba18f5f..851c8ae01c 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -8081,6 +8081,7 @@ @node Particular Modules * Advanced stdio functions:: * libunistring:: * Stack traces:: +* Printing --version and bug-reporting information:: * Recognizing Option Arguments:: * Quoting:: * progname and getprogname:: @@ -8130,6 +8131,8 @@ @node alloca-opt @include stack-trace.texi +@include version-etc.texi + @include argmatch.texi @include quote.texi diff --git a/doc/version-etc.texi b/doc/version-etc.texi new file mode 100644 index 0000000000..6a33c1293b --- /dev/null +++ b/doc/version-etc.texi @@ -0,0 +1,104 @@ +@node Printing --version and bug-reporting information +@section Printing --version and bug-reporting information + +@c Copyright (C) 2025 Free Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.3 or +@c any later version published by the Free Software Foundation; with no +@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +@c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>. + +@c Written by Collin Funk + +Gnulib provides a few modules for printing @code{--version} and +bug-reporting information according to the GNU Coding Standards; see +@ifinfo +@ref{--version,,,standards}. +@end ifinfo +@ifnotinfo +@url{https://www.gnu.org/prep/standards/html_node/_002d_002dversion.html#g_t_002d_002dversion} +@end ifnotinfo + +@mindex version-etc +The @samp{version-etc} module defines functions used to emit +@code{--version} and bug-reporting input in a standard way. The module +expects the string @code{version_etc_copyright} to be defined to display +the copyright holder along with the package release year. The +@code{version_etc} function can then be used like so: + +@smallexample + +const char version_etc_copyright[] = "Copyright %s %d copyright-holder"; + +int +main (void) +@{ + version_etc (stdout, "my-program", "my-package", "1.0", + "author1", "author2", (const char *) NULL); + return 0; +@} +@end smallexample + +The above example generates the following output: + +@smallexample +my-program (my-package) 1.0 +Copyright (C) 2025 copyright-holder +License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>. +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +Written by author1 and author2. +@end smallexample + +The @samp{version-etc} module also defines the function +@code{emit_bug_reporting_address} which emits the bug-reporting location +based on arguments passed to @code{AC_INIT}. For example, using the +following in @file{configure.ac}: + +@smallexample +AC_INIT([gnulib], [0.0], [bug-gnulib@@gnu.org], [gnulib], + [https://www.gnu.org/software/gnulib/]) +@end smallexample + +And the following program: + +@smallexample +#include <config.h> + +#include "version-etc.h" + +int +main (void) +@{ + emit_bug_reporting_address (); + return 0; +@} +@end smallexample + +Will output: + +@smallexample +Report bugs to: bug-gnulib@@gnu.org +gnulib home page: <https://www.gnu.org/software/gnulib/> +General help using GNU software: <https://www.gnu.org/gethelp/> +@end smallexample + +@mindex version-etc-fsf +The @samp{version-etc-fsf} module defines and links to the variable +@code{version_etc_copyright} containing copyright information for Free +Software Foundation. This module should be used by programs which are +FSF-copyrighted and use the @samp{version-etc} module. + +@mindex argp-version-etc +The @samp{argp-version-etc} defines the @code{argp_version_setup} +function takes the program name and authors as arguments. This function +should be called before @code{argp_parse} since it modifies argp global +variables; see +@ifinfo +@ref{Argp Global Variables,,Argp Global Variables,libc}. +@end ifinfo +@ifnotinfo +@url{https://www.gnu.org/software/libc/manual/html_node/Argp-Global-Variables.html}. +@end ifnotinfo -- 2.48.1
