bug#10522: Patch: Improve optional variable and keyword notation in manual

[Daniel Hartwig <mandyke@gmail.com>]

On 3 March 2013 17:45, Andy Wingo <wingo@pobox.com> wrote:
> On Sun 03 Mar 2013 02:07, Daniel Hartwig <mandyke@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.