[REBOL] Re: [Fwd: Re: RSL: Rebol Standard Library]
From: joel:neely:fedex at: 24-May-2001 16:56
Hi, folks...
(Remind me never to get tied up in all-day meetings again...)
Chris wrote:
> > <alert type="feature bloat">
> > I could envision a mechanism, perhaps a flag, where this
> > hypothetical central server would deliver the correct version
> > based on some configurable feature or flag.
> > </alert>
>
> In other words, keep two copies of the scripts on the server:
> one containing all the comments and code and one stripped
> version and indicate in the request which you require...
>
Actually, what I was in my head (for those who can't read
*MY* mind ;-) was a bit simpler, for some definitions of
simpler
...
I'm all for documentation, but I tend to view "comments" as
covering (at least) three very different things:
1) internal comments about some implementation detail,
useful for someone needing to understand the code itself,
2) the interface help/hints in function specs, useful for
someone interactively asking for a reminder about the
calling conventions, and
3) the kind of long-running-narrative-text descriptions that
explain the intended usage of a library unit, including
tutorials, examples, etc., useful to someone browsing the
library or trying to understand usage of a unit, but not
interested in the implementation details.
I'd also observe that we *WANT* for (3) to be as big and
detailed and feature-rich and example-laden as is needed to
provide comprehensive, self-contained reference material.
My imaginary description from earlier in the thread assumed
that all of the above were present in the library unit file,
but that (3) was in a separate section of the file, (instead
of distributed throughout the code or contained within the
REBOL header) so that the installation could split the file
into the documentation part (browsable at will) and the
loadable part (still containing whatever of (1) and (2) that
the author deemed fit, but not containing the readme/reference/
etc. content of (3).
It was a conjecture as to how to resolve these conflicting
forces:
1) We want the loaded components to be lean and mean,
2) We want authors to be free to write as much reference
material as necessary,
3) We want all of the above "in one place" at least for
the purposes of deployment.
-jn-
