-diff -r b16e101c48d3 README
---- a/README Fri Apr 23 11:53:30 2010 -0400
-+++ b/README Fri Apr 23 12:19:58 2010 -0400
+diff -r 73b7b304dd7c README
+--- a/README Fri Apr 23 12:23:54 2010 -0400
++++ b/README Fri Apr 23 16:51:22 2010 -0400
.. -*- restructuredtext -*-
+HgBlog is a set of modifications to the Sphinx project to make it slightly more
+suitable as a blogging engine. It's built for those of us who love using
+reStructuredText markup to write documents.
+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.
-- sudo python setup.py install
++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
++of requesting an object from a database, making it fit into a layout, etc.
++Any webserver should be perfectly capable of serving the content generated by
++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
++by a full-on blogging engine (whatever they may be). People have all sorts of
++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
++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
++ it before) and let Sphinx worry about formatting it.
++* **Consistency**. Again, reStructuredText is a very simple format that will
++ produce consistent, nicely-formatted documents.
++* **Portability**. Since HgBlog generates static HTML, you can put it on any
++ 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>.
++ * HTML, multiple files
++ 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
++ checked into Mercurial, a `distributed version control system <http://2ze.us/eJ>`_.
++ This means that you can easily clone your blog to another system, which is
++ 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.
++* You have a server which offers Python and SSH access, and you're allowed to
++ install your own software within your home directory (or you have full root
++ access to install elsewhere). Run the quickstart utility on your server,
++ clone the repository onto your local machine, write articles, commit them,
++ push them up to your server. When you're ready for those articles to appear
++ online, simply run ``hg up`` on the repository on your server. Make sure your
++ webserver software is configured to serve static content from your ``build/html``
++* Use HgBlog to produce your own, personal wiki. Keep notes on things you do at
++ work or projects you're currently working on.
++* Don't have a server that supports ASP, PHP, Ruby, Python, or whatever
++ language you prefer? Use HgBlog to compose your articles locally, commit
++ changes to the ``.rst`` files, and use an FTP program to upload the HTML
++ files to your hosting provider.
-Send wishes, comments, patches, etc. to email@example.com.
++I've developed and tested HgBlog using Linux, Python 2.6.4, Mercurial 1.5.1,
++Sphinx 1.0-pre, docutils 0.6, Jinja2 2.4.1, and Pygments 1.3.1. However,
++Sphinx suggests the following version requirements. I'm just being safe with
++my requirement on Mercurial's version.
+There are several ways to install HgBlog:
+* Using ``pip`` (recommended)::