GNU bug report logs - #10522
Patch: Improve optional variable and keyword notation in manual

Previous Next

Full log

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

From: Bake Timmons <b3timmons <at> speedymail.org>
To: bug-guile <at> gnu.org
Subject: Patch: Improve optional variable and keyword notation in manual
Date: Mon, 16 Jan 2012 14:46:38 -0500

[Message part 1 (text/plain, inline)]

Attached is a patch to improve optional variable and keyword notation of
Texinfo function definitions.

While this patch fixes blatant errors, it's not particularly
interesting, except for how we improve some keyword notation in the
manual.  It is useful and natural to refer to the associated value of a
keyword '#:foo' by using '@var{foo}'.  Consider the following example
from the patch and the associated final version of the function
definition:

----------------------------------------------------------------------
-@deffn {Scheme Procedure} resolve-module name [autoload=#t] [version=#f] [#:ensure=#t]
+@deffn {Scheme Procedure} resolve-module name [autoload=#t [version=#f]] @
+                          [#:ensure ensure=#t]
 @deffnx {C Function} scm_resolve_module (name)
 Find the module named @var{name} and return it.  When it has not already
 been defined and @var{autoload} is true, try to auto-load it.  When it




@deffn {Scheme Procedure} resolve-module name [autoload=#t [version=#f]] @
                          [#:ensure ensure=#t]
@deffnx {C Function} scm_resolve_module (name)
Find the module named @var{name} and return it.  When it has not already
been defined and @var{autoload} is true, try to auto-load it.  When it
can't be found that way either, create an empty module if @var{ensure}
is true, otherwise return @code{#f}.  If @var{version} is true, ensure
that the resulting module is compatible with the given version reference
(@pxref{R6RS Version References}).  The name is a list of symbols.
@end deffn
----------------------------------------------------------------------


'[ensure]' cannot be used here, since that refers to an optional
variable 'ensure'.  '[#:ensure]' could be used, but then we lose the
default value.  '[#:ensure=#t]' is reasonable and concise, but sloppy
conceptually since the keyword by itself is meaningless without its
associated value.  This could confuse a novice.

The only other possibility I can think of right now is something like

    resolve-module name [autoload=#t [version=#f]] [keyword-options]

where the keyword-options are elaborated on, in, say, a table presented
in the body of the function definition.

This in fact is being used in the manual.  I see the choice right now
being between this one and the one I made in the patch.  We could go
with either one.  Another option is to do as my patch does, but use
'[keyword-options]' on a case-by-case basis, i.e., for a certain minimum number
of keywords, an advantage conferred by a table to present complex or
important information, etc.

Or maybe there is a better notation entirely?  Thoughts anyone?

Bake

[0001-Improve-optional-variable-and-keyword-notation-of-Te.patch (text/x-diff, attachment)]

Previous Next

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