Thanks to Eric Grange who asked Which lightweight markup language? I learned about reStructuredText (no cap R!) from a few comments Joseph Mitzen made.
It looks like reStructuredText has been around for much longer than Markdown, has better features (#1 for me: it is unambiguous, #2: native support on GitHub), but isn’t as popular. I think the latter is because finding editors supporting a live preview for it is a bit hard and tools are scattered around the net.
So here are a few notes on how I got reStructuredText to work on my Mac using OS X.
The hardest part was getting the reStructuredText preview for Atom to work:
- Verify you have recent apm/npm
- Download, then install the latest Mac Pandoc release (filename like “pandoc-*-osx.pkg”).
- Open Atom
- Menu “Atom” -> “Preferences” to open a “Settings” tab in the Atom user interface
- In the list “Settings”, “Keybindings”, “Packages”, “Themes”, “Updates”, “Install”, choose the last one: “Install”
- In the “Search packages” textbox, type “language-restructuredtext”, then hit Enter
- Wait a few seconds until “language-restructuredtext” appears in the list, then click the “Install” button next to it
- In the “Search packages” textbox, type “rst-preview-pandoc”, then hit Enter
- Wait a few seconds until “rst-preview-pandoc” appears in the list, then click the “Install” button next to it
- To enable spell checking:
- In “Settings”, go to “Packages”
- Search for “spell-check”
- Click “settings”
- Add “gfm.restructuredtext” to the “Grammars” list
- Note you get “gfm.restructuredtext” from the “language-restructuredtext” package as described in Spell check in Atom – Atom quick tip #3 – Atom Editor Tips and Tricks.
- Restart Atom from the command-line (otherwise it will not find pandoc *)
- Open a reStructuredText file
- Press Ctrl-Shift-e to show the preview
The error you get when pandoc cannot be found is this one:
‘pandoc’ could not be spawned. Is it installed and on your path? If so please open an issue on the package spawning the process.
It is easy to solve by modifying the Atom startup shell script and then don’t start Atom.app, but start atom from the command-line in a terminal window:
atom
For Windows:
- Install Chocolatey Gallery.
- Follow the steps at Hello Windows.
- Fails horribly: “The term ‘Install-ChocolateyPackage’ is not recognized as the name of a cmdlet”.
- Split-Path bug preventing Chocolatey to install a package · Issue #686 · chocolatey/chocolatey · GitHub.
A later try to get Pandoc installed on Windows was much easier: there is a Pandoc for Windows installer now.
Settings changes
I made a few, for instance:
- Ensure Tab to expands to spaces: See Soft Tabs and Tab Length under Settings > Editor Settings. via github – Atom – Change indentation mode – Stack Overflow.
Tables
Tables are always a hard thing in any markup. Luckily truben.no/table/ has a good table editor (it’s the same as table-editor.com) and can emit reStructuredText, Markdown, HTML and other formats.
More in the future
Give me some time, and I will post more about using the format and how it compares to my Markdown past.
Note that pandoc does not fully support reStructuredText (for instance not all table features are supported), but docutils rst2html.py does and also gives better warning/error information when parsing.
Here are some links about the reStructured syntax and how they can be rendered by rst2html.py:
For now, I’ll end with the goals of reStructuredText which I really like:
Read the rest of this entry »
The Wiert Corner - irregular stream of stuff 