On 9 March 2013 09:58, Daniel Hartwig <mand...@gmail.com> wrote:
> On 3 March 2013 17:45, Andy Wingo <wi...@pobox.com> wrote:
>> On Sun 03 Mar 2013 02:07, Daniel Hartwig <mand...@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.
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 '.
