Markup in our documentation is rendered differently by Pandoc and Spynx

Our man pages contain many strings like this (this one comes from 
gnt-instance.rst):
  --disk *N*:add,size=*SIZE*[,options...]
N and SIZE should be emphasized in the intention of the writer, but according 
to the RST specifications 
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html the * markup 
should be preceded by a space when beginning the markup and followed by a space 
or a punctuation character at the end. Actually the rules are a little more 
complicated, but this is the core of the problem.

So, according to the above rules, N should be emphasized, while SIZE should 
not. This is what Sphinx does, and leaves ugly asterisks, but Pandoc is less 
strict and emphasizes both. If we were to follow the RST rules, we should put 
an escaped space "\ " around the second markup sequence, like this:
  --disk *N*:add,size=\ *SIZE*\ [,options...]
as any escaped space should be removed from the output. This works for Sphinx, 
but again Pandoc has its own ideas and treats an escaped space as a 
non-breaking space.

Pandoc doesn't claim to be RST-compliant, but only supports a subset of its 
specifications, so I don't think we'll have much luck in obtaining a change 
there.

One possible solution could be to add escaped spaces, so that our documentation 
is RST-compliant, and remove them by piping the text through sed before running 
Pandoc.

Original issue reported on code.google.com by bdals...@google.com on 8 May 2013 at 3:47

olopez32 / ganeti

Markup in our documentation is rendered differently by Pandoc and Spynx #456