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

Previous Next

Package: guile;

Reported by: b3timmons <at> speedymail.org

Date: Mon, 16 Jan 2012 19:49:02 UTC

Severity: normal

Done: Andy Wingo <wingo <at> pobox.com>

Bug is archived. No further changes may be made.

Full log


View this message in rfc822 format

From: Daniel Hartwig <mandyke <at> gmail.com>
To: Andy Wingo <wingo <at> pobox.com>
Cc: guile-devel <guile-devel <at> gnu.org>, 10522 <at> debbugs.gnu.org
Subject: bug#10522: Patch: Improve optional variable and keyword notation in manual
Date: Sat, 9 Mar 2013 09:58:47 +0800
On 3 March 2013 17:45, Andy Wingo <wingo <at> pobox.com> wrote:
> On Sun 03 Mar 2013 02:07, Daniel Hartwig <mandyke <at> gmail.com> writes:
>
>> Can I ask whether it is preferred to use, e.g. @code{#f}, for the
>> default values, as some places seem to and others don't.  This patch
>> is not using @code, but then, neither does it touch any doc. that was
>> previously.
>
> Good question.  Do you have an opinion?

I suppose that the context of @deffn is somewhat similar to @code, so
the nesting may be considered redundant.  However, when I look at
cases where non-atomic expressions are used, such as #:lang in:

 -- Scheme Procedure: eval-string string [#:module=#f] [#:file=#f]
          [#:line=#f] [#:column=#f] [#:lang=(current-language)]
          [#:compile?=#f]

we see that there is some potential confusion between the close,
unescaped (as with @code, ‘’) nesting of the parens/brackets.
Further, usage of ‘=’ like that is not valid Scheme code, so the
contexts are actually more distinct than the ealier supposition.

This leads me to have a _slight_ preference for using @code, as being
more technically correct.  Though cases such as the above are in the
minority.




This bug report was last modified 12 years and 102 days ago.

Previous Next


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