Mailing List Archive: 49091 messages
  • Home
  • Script library
  • AltME Archive
  • Mailing list
  • Articles Index
  • Site search

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