[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Scheme file docstring format
From: |
Neil Jerram |
Subject: |
Re: Scheme file docstring format |
Date: |
20 Feb 2001 22:48:59 +0000 |
>>>>> "Carl" == Carl R Witty <address@hidden> writes:
Carl> Neil Jerram <address@hidden> writes:
>> [...]
>>
>> ;; arfle barfle gloop (define (fraz bar) [1] ...)
>>
>> and
>>
>> (define (fraz bar) "arfle barfle gloop" [2] ...)
>>
>> For me, however, [1] somehow _feels_ more i18n-friendly. It
>> suggests a _looser_ association than [2] between code and
>> docstring, and this looseness suggests a space into which
>> i18n/l10n can fit. So, IMO, [1] invites people to believe in
>> the translation mechanism - and therefore go to the trouble of
>> translating the docstrings! - more than [2] does.
Carl> I feel the opposite. With [2], I imagine the docstrings in
Carl> memory as scheme strings, at which point it's easy to call
Carl> gettext. With [1], I imagine the docstrings disappearing
Carl> into a big opaque documentation processing system, with
Carl> HTML/Texinfo/etc. coming out the other end, and no
Carl> convenient place to call gettext.
Yes, I see. Or, I think we may actually be saying the same thing but
in different words: what you call `opaque' I call `looseness' and `a
space'.
Back in concrete terms, you raise an important point by mentioning
HTML/Texinfo. Part of my current motivation for extending docstrings
is to provide short term reference manual documentation for things
that, thus far, are undocumented. This suggests that docstrings, to
be most useful for the reference manual as well, should use Texinfo
markup, and hence that a Texinfo->plain text step is required
somewhere in docstring processing.
Obviously this is debatable, but it would be in step with what we are
already doing with the docstrings from libguile C files.
If this reasoning for Texinfo markup is accepted, then a `gettext'
call is not sufficient for presenting a docstring to the user. In
which case, a `big opaque documentation processing system' may be more
appropriate to our needs.
>> (Oh dear; bye, bye, credibility.)
Carl> Goodbye credibility!
:-)
Regards,
Neil
- Re: Scheme file docstring format, (continued)
- Re: Scheme file docstring format, Keisuke Nishida, 2001/02/22
- Re: Scheme file docstring format, thi, 2001/02/18
- Re: Scheme file docstring format, Michael Livshin, 2001/02/18
- Re: Scheme file docstring format, Neil Jerram, 2001/02/18
- Re: Scheme file docstring format, Michael Livshin, 2001/02/19
- Re: Scheme file docstring format, Neil Jerram, 2001/02/19
- Re: Scheme file docstring format, Carl R. Witty, 2001/02/20
- Re: Scheme file docstring format,
Neil Jerram <=
- Re: Scheme file docstring format, Michael Livshin, 2001/02/21
- Re: Scheme file docstring format, Martin Grabmueller, 2001/02/21
- Re: Scheme file docstring format, Michael Livshin, 2001/02/21
Re: Scheme file docstring format, Neil Jerram, 2001/02/18