/tinyletter

The Programs of a Second Week of Scribbling

This Week’s Program: July 17 - July 21

Last week, I figured out how to build documentation with Scribble. This week, I learned how to write documentation with Scribble. Also, this week, unfortunately, I had some writer’s block.

Here’s what I said last week:

Scribble is effectively a new language. Yeah there’s Racket in there, but the conventions for calling into it as well as the available functions require an additional learning curve.

Here I am, riding the curve.

This is from the Scribble Manual:

The Scribble @ notation is designed to be a convenient facility for free-form text in Racket code, where “@” was chosen as one of the least-used characters in existing Racket code. An @-expression is simply an S-expression in disguise.

The at-exp metalanguage enables this expression form. In Scribble, you have text and then you also have expressions of the form:

@cmd[datum]{body}

This is roughly equivalent to the S-expression: (cmd datum body). This syntax allows you to call any Racket expression but have the syntax tailored for free-form text. Very cool, you can call any Racket expression in a Scribble document. But then each Scribble document has its own form. Beyond just the metalanguage that gives you @-expressions, there’s a bunch of different kinds of Scribble languages, each with their own unique API. Writing a Scribble document means writing stuff, and then grepping around the Scribble manual to see if there’s an expression that does something like what you needed to.

For example, I was writing some installation instructions and wanted to give the reader instructions about running different command line tools. It took me a heck of a time to figure out how to code this properly in Scribble. In HTML there’s <pre> and <code> elements — easy enough. In Scribble there’s @codeblock and @racketblock which are for writing Racket syntax specifically. There’s @tt which just wraps something in a monospace font. Then, finally there’s @exec which is closer to what I wanted. And then, down in the Miscellaneous section is @commandline, which is exactly what I wanted.

So slowly (because of the writer’s block), I spent this week writing bits of documentation for Overscan, learning bits and pieces of Scribble API along the way.

Next week, I hope to have completed a good chunk of this documentation and make it available online, so you can read it.

I still have writer’s block so that’s going to be it for me today. I hope you have a great weekend.

🖋 Mark