Re: Scheme file docstring format

[Neil Jerram]

>>>>> "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