GNU bug report logs - #71800
[PATCH 0/2] Improve documentation about using modules.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 71800 in the body.
You can then email your comments to 71800 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Tomas Volf <~@wolfsden.cz>
To: bug-guile <at> gnu.org
Cc: Tomas Volf <~@wolfsden.cz>
Subject: [PATCH 0/2] Improve documentation about using modules.
Date: Thu, 27 Jun 2024 16:17:16 +0200

Document the #:hide argument.  Correct text for implication of leaving
all optional arguments out.

Tomas Volf (2):
  doc: Document #:hide.
  doc: Fix implication of omitting optional arguments.

 doc/ref/api-modules.texi | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)

--
2.45.1

Message #8 received at 71800 <at> debbugs.gnu.org (full text, mbox):

From: Tomas Volf <~@wolfsden.cz>
To: 71800 <at> debbugs.gnu.org
Cc: Tomas Volf <~@wolfsden.cz>
Subject: [PATCH 1/2] doc: Document #:hide.
Date: Thu, 27 Jun 2024 16:18:51 +0200

* doc/ref/api-modules.texi (Using Guile Modules): Document #:hide.
---
 doc/ref/api-modules.texi | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi
index 9f2bba02d..efe739a25 100644
--- a/doc/ref/api-modules.texi
+++ b/doc/ref/api-modules.texi
@@ -196,25 +196,32 @@ whose public interface is found and used.
 @cindex binding renamer
 @lisp
  (MODULE-NAME [#:select SELECTION]
+              [#:hide HIDE]
               [#:prefix PREFIX]
               [#:renamer RENAMER])
 @end lisp
 
 in which case a custom interface is newly created and used.
 @var{module-name} is a list of symbols, as above; @var{selection} is a
-list of selection-specs; @var{prefix} is a symbol that is prepended to
-imported names; and @var{renamer} is a procedure that takes a symbol and
-returns its new name.  A selection-spec is either a symbol or a pair of
-symbols @code{(ORIG . SEEN)}, where @var{orig} is the name in the used
-module and @var{seen} is the name in the using module.  Note that
-@var{seen} is also modified by @var{prefix} and @var{renamer}.
+list of selection-specs; @var{hide} is a list of bindings which should
+not be imported; @var{prefix} is a symbol that is prepended to imported
+names; and @var{renamer} is a procedure that takes a symbol and returns
+its new name.  A selection-spec is either a symbol or a pair of symbols
+@code{(ORIG . SEEN)}, where @var{orig} is the name in the used module
+and @var{seen} is the name in the using module.  Note that @var{seen} is
+also modified by @var{prefix} and @var{renamer}.
 
-The @code{#:select}, @code{#:prefix}, and @code{#:renamer} clauses are
-optional.  If all are omitted, the returned interface has no bindings.
-If the @code{#:select} clause is omitted, @var{prefix} and @var{renamer}
-operate on the used module's public interface.
+The @code{#:select}, @code{#:hide}, @code{#:prefix}, and
+@code{#:renamer} clauses are optional.  If all are omitted, the returned
+interface has no bindings.  If the @code{#:select} clause is omitted,
+@var{prefix} and @var{renamer} operate on the used module's public
+interface.
 
-In addition to the above, @var{spec} can also include a @code{#:version} 
+The @code{#:hide} operates on list of bindings in the module being
+imported, before any renaming is performed.  If both @code{#:select} and
+@code{#:hide} contain a binding, the @code{#:hide} wins.
+
+In addition to the above, @var{spec} can also include a @code{#:version}
 clause, of the form:
 
 @lisp
-- 
2.45.1

Message #11 received at 71800 <at> debbugs.gnu.org (full text, mbox):

From: Tomas Volf <~@wolfsden.cz>
To: 71800 <at> debbugs.gnu.org
Cc: Tomas Volf <~@wolfsden.cz>
Subject: [PATCH 2/2] doc: Fix implication of omitting optional arguments.
Date: Thu, 27 Jun 2024 16:18:52 +0200

According to the previous wording, omitting all optional arguments led
to empty interface.  That however was not the case and was only a
documentation bug (as confirmed by wingo on IRC).  So let us fix that.

* doc/ref/api-modules.texi (Using Guile Modules): Fix implication of
omitting optional arguments.
---
 doc/ref/api-modules.texi | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi
index efe739a25..115ebbac2 100644
--- a/doc/ref/api-modules.texi
+++ b/doc/ref/api-modules.texi
@@ -212,10 +212,10 @@ and @var{seen} is the name in the using module.  Note that @var{seen} is
 also modified by @var{prefix} and @var{renamer}.
 
 The @code{#:select}, @code{#:hide}, @code{#:prefix}, and
-@code{#:renamer} clauses are optional.  If all are omitted, the returned
-interface has no bindings.  If the @code{#:select} clause is omitted,
-@var{prefix} and @var{renamer} operate on the used module's public
-interface.
+@code{#:renamer} clauses are optional.  If all are omitted, this form
+behaves identically to the previous one.  If the @code{#:select} clause
+is omitted, @var{prefix} and @var{renamer} operate on the used module's
+public interface.
 
 The @code{#:hide} operates on list of bindings in the module being
 imported, before any renaming is performed.  If both @code{#:select} and
-- 
2.45.1

Message #14 received at 71800 <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: Tomas Volf <~@wolfsden.cz>
Cc: 71800 <at> debbugs.gnu.org
Subject: Re: bug#71800: [PATCH 0/2] Improve documentation about using modules.
Date: Mon, 01 Jul 2024 23:31:28 -0400

Hi Tomas!

Tomas Volf <~@wolfsden.cz> writes:

> Document the #:hide argument.  Correct text for implication of leaving
> all optional arguments out.
>
> Tomas Volf (2):
>   doc: Document #:hide.
>   doc: Fix implication of omitting optional arguments.
>

This looks good to me.

Reviewed-by: Maxim Cournoyer <maxim.cournoyer <at> gmail>

-- 
Thanks,
Maxim

Message #19 received at 71800-done <at> debbugs.gnu.org (full text, mbox):

From: Ludovic Courtès <ludo <at> gnu.org>
To: Tomas Volf <~@wolfsden.cz>
Cc: 71800-done <at> debbugs.gnu.org
Subject: Re: bug#71800: [PATCH 0/2] Improve documentation about using modules.
Date: Sat, 26 Oct 2024 19:28:33 +0200

Tomas Volf <~@wolfsden.cz> skribis:

> Document the #:hide argument.  Correct text for implication of leaving
> all optional arguments out.
>
> Tomas Volf (2):
>   doc: Document #:hide.
>   doc: Fix implication of omitting optional arguments.

Applied, thanks!

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.