]> Savannah Git Hosting - gnulib.git/commitdiff
doc: Document version-etc, version-etc, and argp-version-etc.
authorCollin Funk <collin.funk1@gmail.com>
Wed, 29 Jan 2025 04:52:17 +0000 (20:52 -0800)
committerCollin Funk <collin.funk1@gmail.com>
Wed, 29 Jan 2025 04:52:17 +0000 (20:52 -0800)
* doc/version-etc.texi: New file.
* doc/gnulib.texi (Particular Modules): Include it.

ChangeLog
doc/gnulib.texi
doc/version-etc.texi [new file with mode: 0644]

index bf91899783aac75b4779f42eca8e3d3ed01671d8..8545974cae9bcf1dd290370361c1e4307c79e931 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2025-01-28  Collin Funk  <collin.funk1@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  <bruno@clisp.org>
 
        git-version-gen: Change suffix.
index 6a7ba18f5fda50f885a0cdfdb87f6502f56c50e6..851c8ae01cf9cccbb63eef59eff8bc59daa8cf01 100644 (file)
@@ -8081,6 +8081,7 @@ to POSIX that it can be treated like any other Unix-like platform.
 * Advanced stdio functions::
 * libunistring::
 * Stack traces::
+* Printing --version and bug-reporting information::
 * Recognizing Option Arguments::
 * Quoting::
 * progname and getprogname::
@@ -8130,6 +8131,8 @@ to POSIX that it can be treated like any other Unix-like platform.
 
 @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 (file)
index 0000000..6a33c12
--- /dev/null
@@ -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