On Sep 25, 2016, at 2:10 AM, Eli Barzilay <e...@barzilay.org> wrote:
> *Don't* confuse scribble-the-documentation-system with the syntax -- the
> syntax is useful for many other cases, and designed to make sense in
> other cases. See my description (specifically section 4, which is very
> relevant here), and the scribble/text and scribble/html languages.
To be fair, the documentation invites this kind of confusion. All the material
about the at-reader is within the Scribble docs. This makes it look like it's
dependent on Scribble, when really it's a separate thing.
In general, I think the word "Scribble" is misleadlingly overloaded within
Racket. IMO "Scribble" should refer only to the family of languages that use
the Scribble document model, including Racket documentation.
At some point the docs for "Scribble as a Preprocessor" were broken out from
the main Scribble docs — I'm guessing to emphasize that they're conceptually
separate from Scribble. But AFAICT what they really have in common is the
at-reader, not the document model. Because they don't use the Scribble document
model, I'm unclear why they're called `scribble/text` and `scribble/html`.
Meanwhile, I'd argue that the at-reader — itself an obsolete name, since one
can swap out the @ for any Unicode char — deserves to have its documentation
broken out into a separate top-level section, which would more accurately
reflect its status within Racket.
> So maybe phrase this as a challenge: see if you can come up with an actual
> example where the scribble syntax won't do what you want,
When I started out with at-expressions, I too resisted some of the conventions.
But as I worked with more complicated cases, I came to understand the wisdom of
Eli's design choices. At this point I have two lingering wishes:
+ String splitting within {...} delimiters: I agree this is the right default
behavior, but it doesn't seem unreasonable to wish for shorthand for when you
really do want things concatenated into a single argument, given that Racket is
full of cognates like let/let*, for/for*, list/list*, etc. That said, I don't
have a good idea what the notation would be.
+ I wish at-expressions could use multiple [...] and {...} parts, in any order.
--
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.
