kc3-lang/gnulib/doc/version-etc.texi

• Show log

  Commit

• Hash : 64b120ef
  Author :
  Date : 2025-01-28T20:52:17
  

  doc: Document version-etc, version-etc, and argp-version-etc.
  
  * doc/version-etc.texi: New file.
  * doc/gnulib.texi (Particular Modules): Include it.
  

Download

• doc/version-etc.texi

• @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
  

Download