From: Bruno Haible <bruno@clisp.org>
To: bug-gnulib@gnu.org
Subject: doc: Update documentation about 'progname' module
Date: Sun, 06 Jan 2019 17:00:39 +0100 [thread overview]
Message-ID: <1933534.gtIeCVZTjb@omega> (raw)
The documentation section "error and progname" is not up-to-date any more,
since 'error' was changed to use 'getprogname()' on 2016-09-05. This patch
fixes it.
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.
diff --git a/doc/error.texi b/doc/error.texi
deleted file mode 100644
index e450388..0000000
--- a/doc/error.texi
+++ /dev/null
@@ -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 --git a/doc/progname.texi b/doc/progname.texi
new file mode 100644
index 0000000..13c9c7b
--- /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.
diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index ef1cda3..4378668 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -6368,7 +6368,7 @@ to POSIX that it can be treated like any other Unix-like platform.
* 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 @@ to POSIX that it can be treated like any other Unix-like platform.
@include quote.texi
-@include error.texi
+@include progname.texi
@include gcd.texi
reply other threads:[~2019-01-06 16:00 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://lists.gnu.org/mailman/listinfo/bug-gnulib
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1933534.gtIeCVZTjb@omega \
--to=bruno@clisp.org \
--cc=bug-gnulib@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).