# HG changeset patch
# User Bruno Haible <bruno@clisp.org>
# Date 1546790276 -3600
# Node ID 7201768c5696bb61bcc1ca323314ebfc6a7c5587
# Parent  943155cd4a869554a6add6888d07d216d3791aa5
doc: Update documentation about 'progname' module.

* doc/progname.texi: Rename from doc/error.texi. Change node name and
title. Rewrite.
* doc/gnulib.texi (Particular Modules): Update.

diff -r 943155cd4a86 -r 7201768c5696 ChangeLog
--- a/ChangeLog	Sun Jan 06 15:58:46 2019 +0100
+++ b/ChangeLog	Sun Jan 06 16:57:56 2019 +0100
@@ -1,3 +1,10 @@
+2019-01-06  Bruno Haible  <bruno@clisp.org>
+
+	doc: Update documentation about 'progname' module.
+	* doc/progname.texi: Rename from doc/error.texi. Change node name and
+	title. Rewrite.
+	* doc/gnulib.texi (Particular Modules): Update.
+
 2019-01-06  Bruno Haible  <bruno@clisp.org>
 
 	doc: Document the xstdopen and *-safer modules.
diff -r 943155cd4a86 -r 7201768c5696 doc/error.texi
--- a/doc/error.texi	Sun Jan 06 15:58:46 2019 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,26 +0,0 @@
-@node error and progname
-@section error and progname
-@findex error
-@findex progname
-@vindex program_name
-
-@c Copyright (C) 2007, 2009-2019 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
-@c Texts.  A copy of the license is included in the ``GNU Free
-@c Documentation License'' file as part of this distribution.
-
-The @code{error} function uses the @code{program_name} variable, but
-does not depend on the @code{progname} module.  Why?  Because
-@code{error} is released under the LGPL, whereas @code{progname} is
-GPL.  RMS does not want additional baggage accompanying the
-@code{error} module, so an LGPL user must provide their own
-replacement @code{program_name}, and a GPL user should manually
-specify using the @code{progname} module.
-
-Additionally, using the @code{progname} module is not something that
-can be done implicitly. It requires that every @code{main} function
-be modified to set @code{program_name} as one of its first actions.
diff -r 943155cd4a86 -r 7201768c5696 doc/gnulib.texi
--- a/doc/gnulib.texi	Sun Jan 06 15:58:46 2019 +0100
+++ b/doc/gnulib.texi	Sun Jan 06 16:57:56 2019 +0100
@@ -6368,7 +6368,7 @@
 * Closed standard fds::
 * String Functions in C Locale::
 * Quoting::
-* error and progname::
+* progname and getprogname::
 * gcd::
 * Profiling of program phases::
 * Library version handling::
@@ -6401,7 +6401,7 @@
 
 @include quote.texi
 
-@include error.texi
+@include progname.texi
 
 @include gcd.texi
 
diff -r 943155cd4a86 -r 7201768c5696 doc/progname.texi
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/progname.texi	Sun Jan 06 16:57:56 2019 +0100
@@ -0,0 +1,33 @@
+@node progname and getprogname
+@section progname and getprogname
+
+@c Copyright (C) 2007, 2009-2019 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
+@c Texts.  A copy of the license is included in the ``GNU Free
+@c Documentation License'' file as part of this distribution.
+
+Gnulib has two modules for retrieving the name of the currently executing
+program: @code{progname} and @code{getprogname}.
+
+@findex progname
+@vindex program_name
+The @code{progname} module defines a variable @code{program_name}.
+It contains the name of the currently executing program, on all platforms.
+But it cannot be used implicitly:  It requires that every @code{main}
+function be modified to invoke @code{set_program_name (argv[0])} as one
+of its first actions.
+
+@findex getprogname
+The @code{getprogname} module defines a function @code{getprogname()}.
+It returns the name of the currently executing program, on most platforms.
+The advantage of this module is that it can be used without prior
+initializations.  But it has limitations:  In some rare situations, it
+cannot determine the name; then it returns @code{"?"} instead.  And on
+some platforms, it returns a truncated program name.
+
+@findex error
+The @code{error} function uses the @code{getprogname} module.