diff -r 73b7b304dd7c README
--- a/README Fri Apr 23 12:23:54 2010 -0400
-+++ b/README Fri Apr 23 16:51:22 2010 -0400
++++ b/README Fri Apr 23 17:02:48 2010 -0400
.. -*- restructuredtext -*-
+reStructuredText markup to write documents.
++.. note:: HgBlog assumes a level of familiarity with RST and Mercurial. You
++ can certainly use and enjoy using HgBlog if you've never used either one
++ of them. I recommend reviewing a `tutorial for Mercurial <http://2ze.us/o2M>`_
++ if you've never used it or are unfamiliar with how Mercurial affects your
+- sudo python setup.py install
+The quickstart wizard handles setting up an HgBlog for you. This includes all
+of the usual things that the Sphinx quickstart utility does, but it creates a
+Mercurial repository and installs a hook and intelligent ignores for you. The
+hook will automatically convert the ``.rst`` files that Mercurial is tracking
+into HTML using Sphinx when you commit changes to the repository.
-- sudo python setup.py install
+Additionally, when you pull changes in from a remote clone of the repository,
+the hook will do the conversion just like when you commit locally. You can set
+the hook up on remote clones as well. The hook *only* converts ``.rst`` files
+that are tracked by Mercurial. This means you can work on new blog articles
+without committing them to the repository to have them not appear online.
+Why?? Aren't There Enough Blog Engines Already?
+Yes, there are. And most of them rely on databases that require regular
+maintenance and backup. Databases can also slow down your blog. HgBlog offers
+you a way to serve up your blog articles as static HTML without the overhead
+Any webserver should be perfectly capable of serving the content generated by
+- sphinx-build . _build/html
+I'm not saying there's anything wrong with database-backed blogs. I maintain
+my own blog that is Django powered (and database-backed). It works fine for
+me. However, some people might not want to be confined to the rules imposed
+reasons for doing things differently. Some people don't need a reason at all.
+It boils down to what works for you.
-- sphinx-build . _build/html
+-Then, direct your browser to ``_build/html/index.html``.
+What does HgBlog offer you that *should* be attractive?
-Then, direct your browser to ``_build/html/index.html``.
+* **Speed**. No need to deal with the formatting headaches of whatever
+ WYSIWYG editor your blogging engine has dictated is the best. Just use
+ reStructuredText markup (which is quite easy to learn if you've never used
+ server. In fact, you don't even need any server software--just a web
+ browser. Also, Sphinx allows you to export your articles in several formats:
--Or read them online at <http://sphinx.pocoo.org>.
+ With other tools, you can even turn your ``.rst`` files into PDF or ODT
+* **Redundancy**. Since every article you want to have on your blog must be
+ a very fast and effective way to backup your articles. If the primary
+ "server" for your blog ever dies, you are likely to have at least one full,
+ up-to-date backup of your blog if you're using Mercurial as it's designed.
+...to add and commit it to your Mercurial repository. At this point, Sphinx will
+be asked to generate the HTML for your blog based on your ``.rst`` files.
++If you feel like using Mercurial to clone your blog articles to another system,
++you might be interested in adding to the new repository the same hooks that are
++installed by the quickstart utility. First off, this requires HgBlog to be
++installed on the other system. Next, edit the ``.hg/hgrc`` file for the new
++ update.hgblog = python:hgblog.generate_html.htmlize_articles
++ commit.hgblog = python:hgblog.generate_html.htmlize_articles
++These hooks make it so the HTML version of your pages will be generated each
++time you commit changes to the local repository and each time you update your
++local repository using changesets pulled in from elsewhere.