Scribble: The Racket Documentation Tool | Hacker News Reader

Scribble: The Racket Documentation Tool

docs.racket-lang.org

89 pointsTomte21 comments

There is a guile remake of this, skribilo, which is what I have more experience with, but scribble is the bomb diggity.

Scribble-style markup languages aren't "markup", they're merely a series of reader macros on top of a full lisp!

Lisp I tell you! It's wonderful when you compare it to markdown/rst or those horrifying template languages.

Another vote for Skribilo! My pro website (just a single-page academic cv effort) uses it. It was way less scaffolding required than Hakyll, I found.

There is also Pollen built on top of Scribble: http://docs.racket-lang.org/pollen/Backstory.html#%28part._....

I'm happy to see Racket related things appear here on HN

Well since Hacker News is built on Arc (A language built with Racket) it actually gets quite a bit of exposure. I have fallen in love with Racket and I learned about it through HN. Tried to learn Haskell three times and was frustrated and jumped into Racket and it was like when I first used Python (Coming from Pascal, FORTRAN and Assembly).

Scribble is amazing! I've seriously considered writing a Django template language plugin that would use Scribble. I'm convinced it's one of the nicest ways to write parametrised markup.

The main issue is, of course, that now you need to be running Racket on your machine as well when deploying. I'm sure it's possible to embed Racket, but I don't really hear about that happening so assume it's a bit tricky.

Vim can be compiled with support for Racket (a.k.a. mzscheme), providing roughly the same interface it provides via Python, Ruby, Lua, Perl, Tcl, etc.

I haven't looked at it recently, but the last time I tried embedding Racket it wasn't terribly difficult compared to, say, Python or Perl, but it also wasn't quite as nice as embedding, say, Lua or Tcl. I've found its embedding interface to be fairly similar to other interpreted Scheme systems, such as Guile or Chibi.

> I'm sure it's possible to embed Racket, ...

http://docs.racket-lang.org/inside/embedding.html

I use R more then any other language and I always struggle with RMarkDown and Latex documents coming out the way i want them. I really need to add this to my tool set since I love Racket.

I keep wanting to create an implementation of R in Racket (called Arket, because R is a PIA to google). And then I never quite get around to doing it.

As an aside, I too mostly code R but love Racket. Learning a bit of Racket is what unlocked R for me.

I had the same thing happen to me. I now view R totally different after learning Racket and my code changed. My code from a year ago seems like a child wrote it :) R became this functional language and I can see the OO stuff and avoid it now.

I've tried to reproduce toy examples and analyses from R in Racket. Things like plotting aren't too bad in Racket. I start to feel like I could almost code data things entirely in Racket if it weren't for all the R packages missing. That's when I come back to having an implementation of R that I can mix and match with Racket. A man can dream...

embeded Racket in R? Though I find a domain specific language like R is just an awesome tool for its need.

Racket project for me are one's that simplify one sub-domain and do that well.

My idea was a scrapping and munging language in Racket. One that could be used with OpenRefine and spit out R code.

I would seriously love to give this a shot and replace some of the static documents (markdown) that I have. The only thing that's stopping me from it is the fact the HTML output is not mobile-friendly.

Having had to write in Scribble, Markdown, HTML, LaTeX, and a other similar environments, I'm very surprised everyone is that excited about Scribble. It's not bad, but it was never a game changer for me. Is it just because of the ability to use LISP macros? Is that really that big a deal for you? Personally, I really like Jinja2 for my dynamic sites, MarkDown for writing static documents quickly, and LaTeX for anything where a professional document should be created. What do you think is the major advantage of Scribble?

It's similar to the appeal of LaTeX: you can write macros (ordinary Racket functions) to do common things. I could build on Scribble to make an online textbook, for example, with cross-referenced theorems and definitions, by defining some extra Scribble functions.

Except, unlike LaTeX, you have a sane programming language instead of hairy macros.

Pollen takes Scribble and strips out much of the structure, leaving a very interesting core: http://docs.racket-lang.org/pollen/

The abstraction behind Scribble is to treat documentation as a compilation phase analogous to Racket's macro-expansion phases. Matthew Flatt talks about it in this video: https://vimeo.com/6630691

He wrote Scribble to scratch his own itch...or rather remove his own pain from having to maintain LaTeX based documentation for Racket/MzScheme. To me, the proof is in the pudding: Racket's documentation is exceptionally good pretty much from top to bottom despite the breadth of projects that fall within the standard download.

For professional looking docs, you can still write them in Markdown, and then have Pandoc process them into LaTeX. Pandoc even lets you put raw LaTeX commands into your Markdown.

The possibility to have a fully-fledged programming language under the hood gives Scribble definitely an edge. Btw, the same is basically true for Luatex. But I think the expressiveness of Scheme might be more suitable for documentation purposes than that of Lua.

Any major players in the market using this tool?

Cynical me says no. There was an "XML all the things" craze back in the early 2000s. My wife is a tech writer, and from what I can tell, the vast amount of tooling created at that time is still king today, albeit in a nominally updated form. At least that seems to be the big enterprisey market.

Startups and other hip young companies do whatever's sexy in the moment. This is the sort of tool I'd use as a consultant doing technical things, however, because I can do powerful things quickly. I mostly use org-mode, but this holds appeal too.

Reply on news.ycombinator.com