[racket] Learning Scribble

On Fri, Nov 22, 2013 at 6:41 PM, Sam Tobin-Hochstadt
<samth at cs.indiana.edu> wrote:
> On Fri, Nov 22, 2013 at 8:46 AM, Eli Barzilay <eli at barzilay.org> wrote:
>>
>>> Later I finally grokked why. I can translate the at-exp to the s-exp
>>> on the fly.
>>
>> It's probably good to make this an important goal when learning the
>> system, even though it's a small corner of the whole thing now...
>
> I think Eli means "the documentation system" by "the whole thing", but
> the equivalence between at-exps and s-exps is at the heart of why
> at-exps are great, and why Eli's design succeeded where many many
> other people have failed in this space.  If you're learning about
> at-exps, keeping this equivalence in mind is very useful.

Thank you for pointing that out. I wasn't aware of the history and
didn't appreciate the difficulty.

Again: I love at-exps (now).


p.s To loop back to Josh's original point:

I've written a library. I've tested the code. I'm eager to release my
first-ever Racket package! The last hurdle is to write docs. I go
learn how to do this in Racket.

At that point, the last thing I probably want to learn is an
equivalence for s-expressions. :)  Instead I want to focus on writing
clear text and including good examples. And I want to finish it soon.

(And the last thing the rest of us probably want, is for someone to
give up and release the package without docs.)

So I completely understand where Josh is coming from.  Fortunately I
think even just (a) a few examples and (b) a few tips like I mentioned
above, would go a long way for practicality. Plus (c) Sam's point that
hey, when you're not under pressure, you should really learn at-exps
for real.

Let me see if I can find time to review the current docs for Planet
and the new package system, and see where more examples/tips -- or at
least links to examples -- could go, and submit a PR.