reST and HTML woes
Well, I went through and cleaned up my old entries, using this technique. When I was done, I decided to clean up all the entries that were generating reST errors because reST was freaking out trying to interpret raw HTML. I basically went through and cleaned up all of Nutella's entries and a bunch of Sam's.
For Nutella, he essentially wrote everything as one solid block of HTML, often with no newlines at all. So what I did was wrap most of his entries in reST's raw html directive, like so:
.. raw:: html
<cite>blarblarblar</cite> etc etc <a
href="http://zork.net/motd">a link</a>
The outcome is as you'd expect:
blarblarblar etc etc a linkNutella used <cite> a lot, and decimal unicode entities to print hanzi.
For Sam, he had written most of his entries in the wiki markup, using only occasional HTML for URLs and <pre> blocks and so on. I wrapped a few individual paragraphs in the .. raw:: html bit, but mostly I just fixed his bad entries to be properly reSTy.
A Few Good Tags
The switch to reST may be preventing some folks from using this, so here's a few basic tips to cut most of the noise from the quickref.
First, pre blocks are handled using a double-colon and some strict indenting:
::
Note that
there is a blank line
between this paragraph
and the ::.
It won't stop being <pre> until we outdent back flush
with the ::!
...becomes...
Note that
there is a blank line
between this paragraph
and the ::.
It won't stop being <pre> until we outdent back flush
with the ::!
Next up is hyperlinks. The finnicky bit about these is that they tend to behave more like footnotes or endnotes. Basically if you end a word (or a string enclosed in backticks) with an underscore, it becomes a link to a URL specified later on (after the paragraph, or at the end of the file, or wherever you like):
The switch to reST may be preventing some folks from using this, so here's a few basic tips to cut most of the noise from the quickref_. .. _quickref: http://docutils.sourceforge.net/docs/user/rst/quickref.html First, `pre blocks`_ are handled using a double-colon and some strict indenting:: [...] .. _pre blocks: http://docutils.sourceforge.net/docs/user/rst/quickref.html#literal-blocks
Then there's images. This is handled with the .. image:: directive, as follows:
.. image:: http://zork.net/laziness/face/squarenick.jpg
:target: http://zork.net/gallery/sanfrancisco
:alt: Nick Moffitt
:align: right
Finally there's Unicode. There are a few ways to do this. For example, in Ubuntu I use SCIM to input UTF8 text in any application, so I can just hit ctrl-space and start banging in 日本語. But some folks don't have that luxury, so here's a few ways to do this:
|nihongo| is |ni| (sun), |hon| (origin), and |go| (language). Thus, |ni| |hon| |go| is "the language of the rising sun". .. |ni| unicode:: 0x65e5 .. |hon| unicode:: 0x672c .. |go| unicode:: 0x8a9e .. |nihongo| unicode:: 0x65e5 0x672c 0x8a9e
日本語 is 日 (sun), 本 (origin), and 語 (language). Thus, 日 本 語 is "the language of the rising sun".
But again, you can always just go back to HTML character entities and wrap a paragraph in .. raw:: html.
The rest is uncommon enough that you can just consult the quickref or look at the .txt file for an entry you see doing what you want. Also, feel free to pop into nwall and ask for help if you're trying to do something advanced with reST.
But most of what you do will just be ordinary plain text paragraphs, separated by blank lines.