[racket] Learning Scribble

I totally empathize, I had the same experience.

Initially I found it completely baffling. The feeling: "Like parens?
Here's three kinds! Good luck remembering when to use which. And be
careful where you put spaces."

That's unfair to the reference docs, which are perfectly clear as I
read them today.

But I agree about examples. What eventually helped me was to look at
some real examples on Planet and in Racket's own doc sources.

So for awhile I learned by rote stuff like:

"Use {} with item but [] with itemize".

@itemize[
  @item{x}
  @item{y}
  @item{z}
]

Or, "Thou shalt not put a space between the ]{ in a defproc form, else
thou shall get an error pointing to a location other than that".

I just rubbed my eyes, refocused on my immediate goal, and got my docs written.

Later I finally grokked why. I can translate the at-exp to the s-exp on the fly.

To be clear, although I love markdown for prose and light tech
writing, I also love Scribble for bigger tech docs. And I've grown to
understand and appreciate at-exps in general. I'm not criticizing
them, just agreeing with you about the learning curve. They can feel
quite fiddly and "random" at first. They are worth the learning curve.


On Thu, Nov 21, 2013 at 1:59 PM, Josh McGrath <mcgrathj at ccs.neu.edu> wrote:
> I've been learning Scribble so that I can document a small library. I think
> that some sort of users guide specifically for documenting libraries that
> hides details would be very useful. I found myself reading quite a bit of
> prose and only having a vague sense of how to do things. Now when I go back
> through the docs (second or third time), they make more sense. So they seem
> to be a good reference, but they were fairly difficult the first time
> through.
>
> Some things that might be useful in such a guide:
> - Condensed version of sections 1.1-1.7
> - Larger examples
>     + Being able to view source and rendered versions?
>     + Idioms. I don't really get a sense of the idiomatic usage for
> documenting libraries
> - Condensed version of section 4
>
> Pointer chasing also seemed to hinder my efforts. Take for example
> http://docs.racket-lang.org/scribble/eval.html. `interaction` (the first
> documented form on the page) has a description "like `racketinput`,
> except...". Following the `racketinput` link brings me to documentation
> "like `racketblock` ...". Following the `racketblock` link brings me to the
> documentation that I was looking for. But then I get down to rest of the
> forms on the eval page and get really lost. Perhaps `deftogether` could help
> here.
>
> I apologize for the above criticism not being very constructive. I'm still
> trying to understand the difficulties I had in learning Scribble (for a
> particular purpose), and the ways in which it could have been easier to
> learn.
>
> Thanks for reading,
> Josh
>
> ____________________
>   Racket Users list:
>   http://lists.racket-lang.org/users
>