I have been using reStructuredText for blogging for months. It’s a good tool but it also has some bizarre tiny things to deal with. For example:
foo*bar*pub
foo**bar**pub
foo``bar``pub
*foo*bar
**foo**bar
``foo``bar
None of above will work as you expect. First three will result some text with asterisks, the last three will raise errors like:
<string>:9: (WARNING/2) Inline emphasis start-string without end-string.
<string>:9: (WARNING/2) Inline strong start-string without end-string.
<string>:9: (WARNING/2) Inline literal start-string without end-string.
The workaround is to escape a space or spaces:
foo\ *bar*\ pub
*foo*\ bar
They will look like foobarpub and foobar as we expect to see.
I have a note1 for reminders and my-rst2html.py for conversion. I think if you are also a blogger who post about coding, you may want to check out the PyRun directive. Since I write some Python code, so a directive like that can make life easier. Also, kbd role is a simple example for role.
I am still a noob, but reStructuredText is better than Markdown because of its extensibility. Certainly, you can hack Markdown library, but it can get ugly and you have to contribute back into the library core. It’s not like you don’t want to, but the code you use may not be useful for others. With Python docutils, you can maintain you own piece of code.
| [1] | https://sites.google.com/site/yjlnotes/notes/restructuredtext is gone. (2015-12-14T21:44:36Z) |
That didn't work for me - the escaped space doesn't show up, but it also doesn't get rid of the warning.
ReplyDeleteI think you doesn't understand, that escaped space is never going to show because it only served as separator if you will.
ReplyDeleteIf you want a space, then just use *foo* bar, since the space already separate the inline-markup and normal text, escaping a space is just doing it wrong.
The stuff written here is about inline-markup and normal text go head-to-head together. You will need the \ to separate them in order to get the inline markup to work.
Here is a working code and there is no errors:
from docutils.core import publish_parts
markup = '''foo\ *bar*\ pub *foo*\ bar'''
doc_parts = publish_parts(markup, writer_name="html")
print(doc_parts['body'])
The output is
<p>foo<em>bar</em>pub <em>foo</em>bar</p>
See how part of a word has inline markup working?
About it doesn't get rid of warning, I am guessing you didn't escape like I did in the post. If you want my help, please include your code and I will take a look at it.