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

Previous Next

To reply to this bug, email your comments to 71800 AT debbugs.gnu.org.

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

Previous Next

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