The Wiert Corner – irregular stream of stuff

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

  • My badges

    Mastodon

  • Twitter Updates

  • My Flickr Stream

    20140508-Delphi-2007--Project-Options--Cannot-Edit-Application-Title-HelpFile-Icon-Theming20140430-Fiddler-Filter-Actions-Button-Run-Filterset-now20140424-VMware-Fusion-6.0.3.-no-reclaimable
    More Photos

  • Pages

  • All categories

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

    Join 1,860 other subscribers

Archive for the ‘reStructuredText’ Category

Next Entries »

Comparison of Common markup for Markdown and reStructuredText · GitHub

Posted by jpluimers on 2017/10/09

This is a very good comparison of how to use reStructuredText and Markdown well for rendering at GitHub: [WayBack] Common markup for Markdown and reStructuredText · GitHub.

It is being updated by Alex Dupuy over time at https://gist.github.com/dupuy/1855764 and has two sections:

And it refers to http://pandoc.org/try/ which I had missed when starting with reStructuredText a long time ago.

Examples in there are actually more useful to me than these reStructuredText ones:

–jeroen

Posted in Development, Lightweight markup language, MarkDown, Power User, reStructuredText, Software Development | 2 Comments »

reStructuredText Interpreted Text Roles

Posted by jpluimers on 2017/10/04

There is so much great stuff in reStructuredText, take for instance [WayBack] reStructuredText Interpreted Text Roles where basically can create your own role (for instance :csharp: or :delphi: roles based on :code: for syntax-highlighted code blocks given the right syntax highlighters).

I got there via this great piece by[WayBack] Chris who answered [WayBack] Inline code highlighting in reStructuredText – Stack Overflow:

Having looked into this some more I stumbled upon the document reStructuredText Interpreted Text Roles. From this document:

Interpreted text uses backquotes (`) around the text. An explicit role marker may optionally appear before or after the text, delimited with colons. For example:

This is `interpreted text` using the default role.

This is :title:`interpreted text` using an explicit role.

It seems that there is a code role, so you can simply type

:code:`a = b + c`

to render an inline code block. To get syntax highlighting you can define a custom role. For example

.. role:: bash(code)
   :language: bash

which you can then use like so:

Here is some awesome bash code :bash:`a = b + c`.

Note, the document I link to makes no mention of the version of docutils to which it refers. The code role is not available in docutils 0.8.1 (which is the only version I have to test against).

–jeroen

Posted in .NET, C#, Delphi, Development, Lightweight markup language, reStructuredText, Software Development | Leave a Comment »

Inline code highlighting in reStructuredText – Stack Overflow

Posted by jpluimers on 2017/08/15

To inline code inside reStructuredText embed it with back-ticks and pre-pend the first back-tick with :code:

This is how some text with :code:`a = b + c` embedded will look like.

This is how some text with a = b + c embedded will look like.

Source: Inline code highlighting in reStructuredText – Stack Overflow [WayBack]

The above is in addition to the a = b + c that renders to default code as described for instance by reST – reStructuredText — Sphinx/Rest Memo v1.0-14-ga2798e1 documentation [WayBack]

–jeroen

Posted in Development, Lightweight markup language, reStructuredText, Software Development | Leave a Comment »

If only there was a plugin to convert a Google Suite Document into Markdown S…

Posted by jpluimers on 2017/06/29

via If only there was a plugin to convert a Google Suite Document into Markdown Syntax… – Kristian Köhntopp – Google+ [WayBack]

GitHub – mangini/gdocs2md: Convert a Google Drive Document to the Markdown format, suitable for publishing. [WayBack]

In the gapps language: Apps Script  |  Google Developers

Maybe one day – when I use Google Docs more often – I make a reStructuredText version

–jeroen

Posted in Development, gapps Google Apps Script, Google, Google Apps, Lightweight markup language, MarkDown, Power User, reStructuredText, Scripting, Software Development | Leave a Comment »

Github reStructuredText parser got less strict so it now does display parts it cannot fully render

Posted by jpluimers on 2017/05/25

As the pull request had been in the pipeline for almost 2 years, I missed it went through:

Before that, Github would not render parts of reStructuredText files at all it could not fully render them. Now it renders them as raw reStructuredText so at least you can see the content.

Examples:

.. function:: code_to_ast(codeobj)

–jeroen

Posted in Development, Lightweight markup language, reStructuredText, Software Development | Leave a Comment »

reStructuredText Markup Specification – sections (that translate to HTML headings)

Posted by jpluimers on 2017/05/05

So I won’t forget; source: reStructuredText Markup Specification – Sections

[2]

The following are all valid section title adornment characters:

! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~

Some characters are more suitable than others. The following are recommended:

= - ` : . ' " ~ ^ _ * + #

Rather than imposing a fixed number and order of section title adornment styles, the order enforced will be the order as encountered. The first style encountered will be an outermost title (like HTML H1), the second style will be a subtitle, the third will be a subsubtitle, and so on.

Below are examples of section title styles:

===============
 Section Title
===============

---------------
 Section Title
---------------

Section Title
=============

Section Title
-------------

Section Title
`````````````

Section Title
'''''''''''''

Section Title
.............

Section Title
~~~~~~~~~~~~~

Section Title
*************

Section Title
+++++++++++++

Section Title
^^^^^^^^^^^^^

When a title has both an underline and an overline, the title text may be inset, as in the first two examples above. This is merely aesthetic and not significant. Underline-only title text may not be inset.

A blank line after a title is optional. All text blocks up to the next title of the same or higher level are included in a section (or subsection, etc.).

All section title styles need not be used, nor need any specific section title style be used. However, a document must be consistent in its use of section titles: once a hierarchy of title styles is established, sections must use that hierarchy.

Each section title automatically generates a hyperlink target pointing to the section. The text of the hyperlink target (the “reference name”) is the same as that of the section title.

I prefer this order because of decreasing “greyness”:

# * = + ^ ~ - : . _ ` ' "

–jeroen

Posted in Development, Lightweight markup language, Power User, reStructuredText, Software Development | Leave a Comment »

Printing from the Atom editor

Posted by jpluimers on 2017/05/04

Atom is a great editor, but printing from it is still lacking, even though the issue has been opened again.

There is export-html, but it only prints the current source code, not the built-in Markdown Preview or add-on reStructuredText Preview Pandoc packages “Toggle Preview” views.

By name print-atom looks promising, but contrary to the advertised “Print current atom window using print dialog”, it prints the whole Atom UI, which is of no use at all.

The little red icon isn't an adornment. Even though it doesn't look like a button: It's clickable!

The little red icon isn’t an adornment. Even though it doesn’t look like a button: It’s clickable!

Then there is broadcast which at first only worked for me in 1.6.2 but not in 1.7.2. I even removed the whole ~/.atom directory to get it working: to no avail. It finally occurred to me that in the lower right there was a tiny red icon (which was blue in 1.6.2).

Below is the process to fix broadcast, and after that you can live-view from your web browser through http://localhost:8000 either of the rendered source text in the Atom editor, or the Preview pane in the Atom editor.

Even though hardly documented, these are the broadcast settings:

Only enable

Only enable “Broadcast To Others” if you want to access port 8000 from another machine.

Getting broadcast to work again

  • wasn’t caused by changes in the theming between 1.6.2 and 1.7.2 (where lots of colours changed)
  • wasn’t just an adornment: it’s in fact clickable

As soon as you click it you see this in the right pane:

Read the rest of this entry »

Posted in atom editor, Development, Lightweight markup language, MarkDown, Power User, reStructuredText, Software Development, Text Editors | Leave a Comment »

Lightweight Markup: Markdown, reStructuredText, MediaWiki, AsciiDoc, Org-mode – Hyperpolyglot

Posted by jpluimers on 2017/05/03

A great table with comparison of various constructs in Lightweight Markup: Markdown, reStructuredText, MediaWiki, AsciiDoc, Org-mode – Hyperpolyglot

It works much better than the examples in Lightweight markup language – Wikipedia, the free encyclopedia (which does include more languages).

As I’ve switched to “all source – including docs – should be in text format” years ago, I’m a heavy markdown user, but also use reStructuredText, so this table is of great help.

Reminder to self: reStructuredText does not support strikethrough out of the box.

–jeroen

Posted in Development, Lightweight markup language, MarkDown, Polyglot, reStructuredText, Software Development | Leave a Comment »

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, : 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:

Read the rest of this entry »

Posted in Development, MarkDown, Perl, PHP, Power User, Python, reStructuredText, Scripting, Software Development | Leave a Comment »

Next Entries »