.. -*- restructuredtext -*-

=============
HgBlog Readme
=============

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.

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

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.

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

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.

What does HgBlog offer you that *should* be attractive?

* **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:

    * HTML, multiple files
    * HTML, single file
    * epub
    * LaTeX
    * LaTeX PDF
    * Plain text
    * man pages

  With other tools, you can even turn your ``.rst`` files into PDF or ODT
  documents.
* **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.

Possible Workflows
==================

* 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
  onli