The Wiert Corner – irregular stream of stuff

Jeroen W. Pluimers on .NET, C#, Delphi, databases, and personal interests

  • My work

  • My badges

  • Twitter Updates

  • My Flickr Stream

  • Pages

  • All categories

  • Enter your email address to subscribe to this blog and receive notifications of new posts by email.

    Join 1,798 other followers

reStructuredText notes (.rst file extension)

Posted by jpluimers on 2016/04/28

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:

  1. Verify you have recent apm/npm
  2. Download, then install the latest Mac Pandoc release (filename like “pandoc-*-osx.pkg”).
  3. Open Atom
  4. Menu “Atom” -> “Preferences” to open a “Settings” tab in the Atom user interface
  5. In the list “Settings”, “Keybindings”, “Packages”, “Themes”, “Updates”, “Install”, choose the last one: “Install”
  6. In the “Search packages” textbox, type “language-restructuredtext”, then hit Enter
  7. Wait a few seconds until “language-restructuredtext” appears in the list, then click the “Install”  button next to it
  8. In the “Search packages” textbox, type “rst-preview-pandoc”, then hit Enter
  9. Wait a few seconds until “rst-preview-pandoc” appears in the list, then click the “Install” button next to it
  10. To enable spell checking:
    1. In “Settings”, go to “Packages”
    2. Search for “spell-check”
    3. Click “settings”
    4. Add “gfm.restructuredtext” to the “Grammars” list
    5. 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.
  11. Restart Atom from the command-line (otherwise it will not find pandoc *)
  12. Open a reStructuredText file
  13. Press Ctrl-Shift-e to show the preview
  • pandoc error:

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:

  1. Install Chocolatey Gallery.
  2. Follow the steps at Hello Windows.
  3. Fails horribly: “The term ‘Install-ChocolateyPackage’ is not recognized as the name of a cmdlet”.
    1. 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:

  1. 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:

Goals

The primary goal of reStructuredText is to define a markup syntax for
use in Python docstrings and other documentation domains, that is
readable and simple, yet powerful enough for non-trivial use. The
intended purpose of the reStructuredText markup is twofold:

  • the establishment of a set of standard conventions allowing the
    expression of structure within plaintext, and
  • the conversion of such documents into useful structured data
    formats.

The secondary goal of reStructuredText is to be accepted by the Python
community (by way of being blessed by PythonLabs and the BDFL [1]) as
a standard for Python inline documentation (possibly one of several
standards, to account for taste).

[1] Python’s creator and “Benevolent Dictator For Life”,
Guido van Rossum.

To clarify the primary goal, here are specific design goals, in order,
beginning with the most important:

  1. Readable. The marked-up text must be easy to read without any
    prior knowledge of the markup language. It should be as easily
    read in raw form as in processed form.
  2. Unobtrusive. The markup that is used should be as simple and
    unobtrusive as possible. The simplicity of markup constructs
    should be roughly proportional to their frequency of use. The most
    common constructs, with natural and obvious markup, should be the
    simplest and most unobtrusive. Less common constructs, for which
    there is no natural or obvious markup, should be distinctive.
  3. Unambiguous. The rules for markup must not be open for
    interpretation. For any given input, there should be one and only
    one possible output (including error output).
  4. Unsurprising. Markup constructs should not cause unexpected output
    upon processing. As a fallback, there must be a way to prevent
    unwanted markup processing when a markup construct is used in a
    non-markup context (for example, when documenting the markup syntax
    itself).
  5. Intuitive. Markup should be as obvious and easily remembered as
    possible, for the author as well as for the reader. Constructs
    should take their cues from such naturally occurring sources as
    plaintext email messages, newsgroup postings, and text
    documentation such as README.txt files.
  6. Easy. It should be easy to mark up text using any ordinary text
    editor.
  7. Scalable. The markup should be applicable regardless of the length
    of the text.
  8. Powerful. The markup should provide enough constructs to produce a
    reasonably rich structured document.
  9. Language-neutral. The markup should apply to multiple natural (as
    well as artificial) languages, not only English.
  10. Extensible. The markup should provide a simple syntax and
    interface for adding more complex general markup, and custom
    markup.
  11. Output-format-neutral. The markup will be appropriate for
    processing to multiple output formats, and will not be biased
    toward any particular format.

The design goals above were used as criteria for accepting or
rejecting syntax, or selecting between alternatives.

It is emphatically not the goal of reStructuredText to define
docstring semantics, such as docstring contents or docstring length.
These issues are orthogonal to the markup syntax and beyond the scope
of this specification.

Also, it is not the goal of reStructuredText to maintain compatibility
with StructuredText or Setext. reStructuredText shamelessly steals
their great ideas and ignores the not-so-great.

Author’s note:

Due to the nature of the problem we’re trying to solve (or,
perhaps, due to the nature of the proposed solution), the above
goals unavoidably conflict. I have tried to extract and distill
the wisdom accumulated over the years in the Python Doc-SIG
mailing list and elsewhere, to come up with a coherent and
consistent set of syntax rules, and the above goals by which to
measure them.

There will inevitably be people who disagree with my particular
choices. Some desire finer control over their markup, others
prefer less. Some are concerned with very short docstrings,
others with full-length documents. This specification is an
effort to provide a reasonably rich set of markup constructs in a
reasonably simple form, that should satisfy a reasonably large
group of reasonable people.

David Goodger (goodger@python.org), 2001-04-20

–jeroen

via: reStructuredText tool support – Stack Overflow.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

 
%d bloggers like this: