Deren Dohoda wrote on 01/27/2018 06:34 PM:
If I understand the implication: how is turbo-racket practically different from scribble/lp2? —Just that the code is not put in the document?

Put one way, I think literate programming is more about expressing the programmer's *how* of the module/package internals, but I'm much more concerned with documenting the engineering *what* of a package external interface.

Background for students: In software engineering, we often intentionally hide the *how* from external users of a module, not just through programming language mechanisms for information hiding, but also through human-readable specifications.  These specifications are the *what*, to which you commit, to other parties, such as other developers on a single large system that is the only place the module will ever be used, or other developers who reuse the module in other systems.  Any *how* mentioned tends to be also treated as *what* specification -- which encumbers maintenance when you have to preserve the *how* on which others now depend, and/or creates correctness problems elsewhere, when you don't manage preserve all the *how*.

We should try to document the *how* with readable code and judicious use of internal comments.

You can see this software engineering discipline of maintaining the how/what, implementation/interface distinction many places, including in core Racket.

Also, I want the language to be "lightweight", to lower friction to developing modules that are potentially reusable (intra-organization, and/or as open source), and literate programming tools aren't optimized for that.

Aside on literate programming chunks and reordering: I've been releasing reusable open source Scheme code libraries with linear embedded interface documentation since around 2000, and, so far, having the documentation order follow the code definitions order has not been a big problem.  (I don't mention that as an attempt at argument from authority, but merely that that's my own anecdotal experience thus far, while trying to figure out some good practices for this kind of reuse-oriented development.)  And `#lang racket/base` toplevel has some flexibility in forward references.  A documentation "Introduction" section can mitigate any awkwardness of ordering of the rest of the document, and "Introduction" is a good idea, anyway, and you can also use it to show off what's cool about your *what*.

(BTW, I quickly threw in the name `turbo-racket`, just to show that a custom `#lang` would need to be used, but I wouldn't actually use that particular name.  It's a trademark-violating homage to the venerable Turbo Pascal of the early 1980s.)

--
You received this message because you are subscribed to the Google Groups "Racket 
Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Reply via email to