This is my second book written with Sphinx, after the new Learn TLA+. Sphinx uses a peculiar markup called reStructured Text (rST), which has a steeper learning curve than markdown. I only switched to it after writing a couple of books in markdown and deciding I needed something better. So I want to talk about why rst was that something.
↫ Hillel Wayne
I’ve never liked Markdown – I find it quite arbitrary and unpleasant to look at, and the fact there’s countless variants that all differ a tiny bit doesn’t help – so even though I don’t actually use Markdown for anything, I always have a passing interest in possible alternatives, if only to see what other, different, and unique ideas are out there when it comes to relatively simple markup languages. Now, I’m quite sure reStructured Text isn’t for me either, since I feel like it’s far more powerful than Markdown, and serves a different, more complex purpose.
That being said, I figured I’d highlight it here since it seems it may be interesting to some of you who work on documentation for your software projects or similar endeavours.
I’m guessing you’re familiar with Asciidoc?
I’ve used Markdown (I advise insisting on CommonMark), reStructuredText, and Asciidoc at various points… though the latter much less than the others.
My general attitude is that all lightweight markup languages are uncomfortable… but Markdown’s ecosystem puts its user experience heads and shoulders above the alternatives.
I find Ruby unacceptably fragile, so asciidoctor is out, and, as a Python developer, I don’t like depending on Python’s dependency management situation for Sphinx or the original Asciidoc implementation if I can avoid it… and that’s before you get into autoformatting.
With a CommonMark implementation, I may be missing reST’s intentional support for syntax extension which Sphinx relies heavily on, but at least I’ve got Prettier via Vim’s ALE so I can get reformat-on-save (which helps with catching typos since the reformat makes structure-affecting typos blazingly obvious and then I hit Undo, fix, and re-save) and I can do what I’ve started relying on more and more… incorporating the Rust pulldown-cmark crate into a self-developed tool that starts, runs, and exits in a split second… even on the 2011 Athlon I was using until this January.
…and, with the help of pulldown-cmark’s support for not-yet-in-commonmark syntax extensions (eg. concise tables) and a patch to loosen pulldown-cmark’s interpretation of whitespace when recognizing GitHub’s syntax extension for admonitions so Prettier doesn’t break them, it even starts to approximate the full range of constructs AsciiDoc has.
Aside from the hassle of cross-compilation, the result is stupid simple to build and, with the help of the musl-libc target for Linux, all supported platforms can be a Go-like self-contained binary that depends on nothing but the kernel (or, in the case of non-Linux platforms, the libc which is developed as part of the kernel and acts as the platform’s official ABI stability boundary.)
Would I prefer reStructuredText if it also had an autoformatter and a mature Rust implementation with syntax extensions comparable to Sphinx’s? Yes… but we use what we’re given.
I share your experience. We at manticore-projects.com stick with Sphinx/ReST for building our website but honestly, coming from a Java eco-system we are not happy with it and see it as the smallest common denominator:
1) ReST is the more power full syntax and features but the worst tooling and theming
2) Sphinx is very dated, to the brink of unmaintained
3) They just broke theming between 5.3 and recent release — without any real benefit. This is no joke because you can’t just “take out time” and upgrade themes.
4) There is no good way to publish APIs (other than Python). Lots of unmaintained broken modules around.
If I would start all over again then I would go for JBake and ASCII Doctor. Although migration will take serious effort and we are kicking down the can as long as we can.
As a very long-time Emacs user, I was thrilled to find org-mode slightly over ten years ago. It is a lightweight markup language that has a notion of structure, and Emacs has modes that export it to various other formats – HTML, LaTeX, ODT…
I have written several books using org-mode, and use it for most of my everyday tasks, even when they need nothing fancy. It’s just a comfortable way to write, with no frills and distractions.
Of course, it has extensions for many other use cases. I do my presentations in LaTeX Beamer, and the org-mode integration is superb – it is clearly better than writing LaTeX, faster and easier (for my brain) than using a graphical presentation design program.
I don’t use many of org-mode’s other features (to-do tracking, spreadsheets, etc.) Part of the beauty of the tool is that it works for you, but does not suck you into its worldview if you don’t want to get any deeper in the rabbit hole.
At least we aren’t all still using BBCode.
Incidentally, I’ve been reading LearnTLA+ which is pretty great.
I may take Hillel’s advice to check out typst, which I just found out about last week; I grew to hate LaTeX after using it in graduate school, even though I was initially excited about it. Eventually, I managed to slog through and write my whole dissertation using it. Although not as challenging as the underlying work, using LaTeX certainly did not make the experience easier or less stressful.
Incidentally once again, Leslie Lamport takes credit for both TLA and LaTeX. I don’t begrudge him on LaTeX too much, just like I don’t begrudge the creators of C for C. It was a different era. If you’re a programmer though, or anyone designing systems, check out LearnTLA+.
If you must to write LATEX, then in my opinion the LYX UI is a must.
If you want to write structured documents, then DocBook is the better choice in my opinion and from there convert into any dialect you want/need via XSLT.
I think typst is great, but I’ve mainly used it as a way to generate pdf documents, which it does very nicely. Its aim is to replace the LaTeX ecosystem, but it also improves on solutions that make pdf from html.
I think I like bbcode the most, due to its close similarity to HTML, just with square brackets instead of the angled ones.
> I’ve never liked Markdown – I find it quite arbitrary and unpleasant to look at[.]
L take
Regardless of aesthetic preference the big advantage with Markdown is that is very simple to explain to non-technical people who you need to write it in this form. I have to do that fairly often and often people will grasp it immediately. Its forgivingness helps with that. reStructuredText may be great too but the ubiquity of Markdown in recent years has been a blessing for getting non-technical people to contribute to well structured documents without having to learn any HTML. For that I’ll take its ugliness (if you say so).