Mike Orr has this cool little howto explaining how to do various HTML markup techniques using reST:

http://sluggo.kicks-ass.org/python/rest/rest_for_html_users.html

It's unfinished, but it's full of useful advice for beginning to think of your plain-text layout as markup instead of trying to do everything with particular tags.

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:

Nutella 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.

So one somewhat bothersome aspect of the blosxom system is that if you edit a file, that bumps it up to the top of the listing. This is because pyblosxom sorts all entries by the modification time of the original posting.

There are quite a few old entries in here that could do with a few repairs, but they really don't belong at the top of the page or the RSS feed. So for you folks, I give you the magic of touch!

Here is an example of how to use cp and touch to edit old entries while keeping their posting date the same:

$ cd /var/www/motd/madness/goober/
$ cp -a no-its-true.txt /tmp/old-entry
$ vi no-its-true.txt
$ touch no-its-true.txt -r /tmp/old-entry

First, the cp -a causes the file in /tmp/ to have the same exact modification time as the oirginal file. We are actually just backing up the modification time here, and don't care about the contents.

Then we edit the file as normal (I use vi, but I know that many folks like nano).

Finally, we use touch -r to make the edited entry have the same modification time as our backup in /tmp/.

So this would be helpful for folks like Nutella, who need to go in and mass-replace a lot of <br> and <p> stuff with ordinary blank lines.

If you edit an old entry, let me know and I'll give the full site build a push. Right now pyblosxom only updates files that have brand new mtimes, so this trick will sneak past that. I can force a full rebuild that will update everything.

So we now have the latest 1.3.2 Pyblosxom, which means we have proper RSS now. I've updated the little XML box, but the long and short of it is that you should change "index.rss" to "index.rss20" for your feeds.

http://zork.net/motd/index.rss20 <-- teh new url.

http://zork.net/motd/nick/index.rss20 <-- example user RSS category feed.

I noticed nutella mumbling about the ability to check the output of his entries. I only just realized that he was actually entering everything in HTML, and ignoring the actual plain-text formatting that motd uses. Even his entries that were just blank unadorned paragraphs were separated with <p> tags instead of blank lines.

Well I've now switched laziness away from the old "genericwiki" formatter, and over to reST. This means that shoving HTML code inline will no longer work, and you'll have to learn reST layout in order to punch in unicode entities or make non-trivial links. The end result, however, will be to banish those hideous less-than/greater-than symbols from everyone's posts.

But the bonus is that you can always test by running rest2html on an entry and checking your result in a browser.

I just ripped off the RSS 2.0 theme files from another pyblosxom package, so now the feeds should be working again, though at a different URL.

http://zork.net/motd/index.rss <-- teh new url.

http://zork.net/motd/nick/index.rss <-- example user RSS category feed.

Welcome to the land of WikiWords. Now everything in StudlyCaps becomes a GoogleSearch. (Yeah, I upgraded pyblosxom, and grabbed some caching and formatting extensions along the way)

This is getting to be ridiculous, what with all the messages being about the system itself.

We're now running the <a href="http://roughingit.subtlehints.net/pyblosxom/weblogs/tools/pyblosxom/pyblosxom.0+5i_rev2.html">latest version</a> with some <a href="http://roughingit.subtlehints.net/pyblosxom/weblogs/tools/hep/minor_bugfix.html">fixes</a> and features I submitted. It's all in the <a href="http://roughingit.subtlehints.net/code/ChangeLog.html">ChangeLog</a>.

And I still need to finish that article.

So after Nate threw a hissy fit and broke this thing, holding his breath until it was fixed, I threw in an exception wrapper.

try:
    story = file(filename).readlines()
except:
    return current_date

I submitted that fix upstream, so life should be good.

I have made a madness/ directory, and it is world-writable, with the tmp bit on. This means that anyone can make a new file and play with it, but you can't futz with other peoples' entries. I'll prime it in a moment.

I dunno how I'd manage the colored entries, really. This system doesn't pay much attention to a file before slurping it up, so I'm not sure what styles I could throw on in a per-directory fashion.

So I hacked up pyblosxom to support flavors in more than just the top-level dir. You can play with them by hacking up the .html files from /var/www/motd, and copying them to your MOTD dir. See http://zork.net/motd/nick for an example of how I abused this, and look through /var/www/motd/nick to see how I got this to work (and how I made it stick in my subcategories).

I just noticed that the clock rolled back to 1am, thanks to daylight savings ending here in California.

I'm curious as to whether or not this entry (roughly 1:05PST) will be placed later than the previous one (1:27PDT).

So nobody should notice, but I switched from the Perl version of blosxom to the python version. One bonus this gives is the ability to define little filter modules to the text. I had hand-hacked in the blank-lines-separate-paragraphs bit to the Perl version, but I've been able to do still more by simply hacking pyblosxom to use a default filter.

It can cache the files if things get too slow, but I don't imagine that will happen.

The most notable changes are that URLs such as http://www.lnx-bbc.org/ and http://www.lnx-bbc.org/logo.png will be translated (the second one was "http://www.lnx-bbc.org/logo.png", and the URL has to be separated by whitespace -- I may add angle brackets or something to the mix at some point).

Also, you can do emphatic text with the application of asterisks. (that was just "emphatic text" -- again, spaces make the magic happen).

Okay, sorry folks. I was just testing out blagg. You can look at ~nick/.blagg for a sample config file. It's probably not all that useful, but you can just set the thing up to troll various sites and slurp in articles.

I really only installed it for completeness, but I should have probably made a subdir for the stuff before I started monkeying.

But that <a href="http://zork.net/motd/2002/10/25#nick/raelitybytes.Essential_Blogg...gging">book entry</a> is actually the book I'm reviewing.

<a href="http://zork.net/motd/2002/10/24#octal/motd">Octal</a>:

I figure I'll post it once enough of the wrinkles are ironed out. It looks like <a href="http://zork.net/motd/muse">muse</a> and <a href="http://zork.net/motd/inkblot">inkblot</a> managed to use the script to set up their dirs, so things are probably about ready to announce.

This is partly just a neat little hack that I'm using as part of the research for an article, but at some point this will reach a level of functionality where I figure it could be a useful fixture for zork. I'm interested partly in installing blagg and seeing how to integrate that into a multi-user environment. The blosxom stuff was mostly written with a single-user MacOSX system in mind, so I'm playing and fiddling.

Note that there's also a <a href="http://zork.net/motd2">python version</a> of this software that supports the same data files. the difference is that I added the one-line hack to get the blank-line-denotes-paragraphs feature to the perl version, while the python system has a more elaborate parser setup that I have yet to fully work out.

At any rate, I'll play and fiddle for at least a week yet.

<a href="http://zork.net/motd/2002/10/24#octal/2002-10-24T20:28:29-0700">Octal</a>:

The script enforces a bit of policy by making the user's subdir and giving the file the appropriate .txt extension. Did you know that you can type "motd tinkerbell" and it'll make a tinkerbell.txt file?

Of course, it's not as powerful as simply editing the files yourself. It can't do sub-subdirs, for example (all slashes get turned to underscores). But it's good for getting folks to make entries off the bat.

Did you know you can make subdirs of your personal dirs, and categorize your entries thusly?

Wow, this stuff is coming along, eh.

woop.

I'm playing with my new fancy motd script, which makes new entries in your motd dir.

Neat like my feet.

I'm also playing with pyblosxom, which promises more advanced froofergee.

But it doesn't seem to actually work.

Let's see if this does the trick...

...?

So I've been writing this big article on why diaries are not weblogs, etc, and blosxom was the only free software it listed. <p/> I'm a little irritated that I have to type in HTML, but I may just throw a big PRE tag in.