That’s a long title, but it describes rather exactly what this note is about.
In the spring of this year, I set myself the task of learning [ReStructured Text] as an alternative to Markdown for lightweight document markup. I was interested in learning what, if any, advantages ReST might have when it comes to composing long or complex documents, the kinds of texts which are not the focus of Markdown development — though a number of developers, most notably [Fletcher Penney] (with MultiMarkdown) and [Michele Fortin] (with Markdown Extra) have extended Markdown’s capabilities to accommodate some of my needs.
I was, and am, interested in ReST as an alternative to composing in LaTeX. My colleague, and occasional collaborator, Jonathan Goodwin was the one who finally plunged me into learning LaTeX. It’s not hard to learn — though its various incantations, as Goodwin once called them, can confound you — but it’s also not pretty to look at. I was hoping for something with a lighter touch that could also output to LaTeX if I needed it to do so. ReST can do that, thanks to `docutils`.
In fact, to get access to ReST functionality you need to install `docutils`, which I did from within the comfort of MacPorts. But I’m not yet ready to write any scripts: I’ve got no customary tasks that I need to automate. I mostly need to see what the output of various elements I try look like. All I want is to:
% rst2html thisdocument
I ran into a number of difficulties, and I chronicled them on [AskDifferent], and then paraphrased them and asked them on the [Macintoshian Achaia]. The chief difficulty was simply running that above command. The answer is quite simple:
It’s not clear if adding the following to `/etc/paths` wasn’t also helpful:
I hope this helps someone else. (Also: if anyone has an explanation for how to access Python scripts included with various libraries, that would be great — I know I’m not using the right vocal. I’m working on it.)
[ReStructured Text]: http://docutils.sourceforge.net/rst.html
[Fletcher Penney]: http://fletcherpenney.net/multimarkdown/
[Michele Fortin]: https://michelf.ca/projects/php-markdown/
[Macintoshian Achaia]: http://arstechnica.com/civis/viewtopic.php?f=19&t=1252647