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

[Daniel Hartwig]

On 9 March 2013 09:58, Daniel Hartwig <address@hidden> wrote:
> On 3 March 2013 17:45, Andy Wingo <address@hidden> wrote:
>> On Sun 03 Mar 2013 02:07, Daniel Hartwig <address@hidden> 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.

So I should also mention that omitting @code seems a bit more readable
in the resulting documentation.  At least we can clean up where some
values (symbols, empty lists) appear prefixed with unnecessary '.