Markdown to Scribble converter

Questions & Answers
, , ,
4

I'll try to answer some of your points and will probably miss a few others. :wink:

Why Markdown?

While you can compare Scribble (or Pollen) with Markdown, in my opinion it's not that useful to conclude that one of the two is "better." There are just different tradeoffs for both formats.

These are features I like about Markdown:

  • Relatively easy to read even in non-rendered mode

  • Easier to write. For me, this means that writing Markdown breaks my writing flow much less than writing Scribble. That's why I like to write (at least a draft version) in Markdown, even if I can add more sophisticated markup only later with Scribble.

  • More likely to get contributions because of the previous point and because much more people are familiar with Markdown than with Scribble. This may be not or less true for people in the Racket ecosystem. I really can't tell; I'm quite sure it'll depend on the person you ask.

Use cases

I'll try to describe a bit more why I asked for such a conversion tool from Markdown to Scribble. To integrate well with other Racket documentation, using Scribble (at least eventually) (or Pollen?) is a must. Now the question is: when/why would I write something in Markdown instead of directly in Scribble?

  • One use case is that I wrote a README.md for one of my projects. It makes sense to have this rendered from Markdown on Sourcehut (but would similarly apply to Github or Gitlab). It would be nice if I could create a Scribble version of the README.md file for the documentation on the Racket package server without converting the Markdown to Scribble purely manually. This rationale would also apply to other README files and projects.

  • My other use case: For the glossary project that I mentioned in another thread, I hope to get contributions more easily if I make the threshold for contributions as low as possible. I can hopefully write many of the glossary entries myself, but for others I'm bound to need some help. So having a low "contribution barrier" has the highest priority for me, even if that means I have to convert Markdown contributions to Scribble myself. And of course it would be nice if I didn't have to make these conversions manually. :slight_smile:

For the first use case, the current situation is that I wrote the API documentation for the project directly in Scribble. I may create Scribble documentation for the command line tool later.

For the second use case, I think an either/or approach isn't necessary. Since I rely on contributions, I'll change the README of the glossary project to encourage contributors to send me Markdown or Scribble content, whatever they prefer. :slight_smile:

Markdown extensions

I don't think it should be a goal to make Markdown as expressive as Scribble, Pollen or LaTeX. Markdown isn't designed for that. Moreover, bigger changes/enhancements to Markdown would defeat the purpose of having a format that's easy to write and read.

Relatedly, a middle ground between Markdown and Scribble is reStructuredText, which is quite common in the Python ecosystem. (For example, it's used for the Python documentation.) ReStructuredText allows some things that Markdown doesn't, but I usually dislike writing in reStructuredText compared to Markdown. (That said, the two are much closer to each other than to LaTeX or Scribble.)

2 Likes