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.

1 files changed, 33 insertions, 0 deletions

diff --git a/doc/progname.texi b/doc/progname.texi
new file mode 100644
index 0000000000..13c9c7ba97
--- /dev/null
+++ b/doc/progname.texi
@@ -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.