Commits

Josh VanderLinden committed 954a7f7

More updates to the README

Comments (0)

Files changed (1)

 
 diff -r 73b7b304dd7c README
 --- a/README	Fri Apr 23 12:23:54 2010 -0400
-+++ b/README	Fri Apr 23 16:51:22 2010 -0400
-@@ -1,33 +1,161 @@
++++ b/README	Fri Apr 23 17:02:48 2010 -0400
+@@ -1,33 +1,180 @@
  .. -*- restructuredtext -*-
  
 -=================
 +reStructuredText markup to write documents.
  
 -Use ``setup.py``::
++.. 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.
+ 
+-    python setup.py build
+-    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.
  
--    python setup.py build
--    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.
  
+-Reading the docs
+-================
 +Why?? Aren't There Enough Blog Engines Already?
 +===============================================
  
--Reading the docs
--================
+-After installing::
 +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
 +HgBlog.
  
--After installing::
+-    cd doc
+-    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.
  
--    cd doc
--    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``.
+-Or read them online at <http://sphinx.pocoo.org>.
 +* **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>.
 +    * HTML, multiple files
 +    * HTML, single file
 +    * epub
 +    * Plain text
 +    * man pages
  
+-Contributing
 +  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
 +  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.
-+* 
- 
--Contributing
++
 +Possible Workflows
 +==================
 +
 +...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
++repository::
++
++    [hooks]
++    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.
++
 +TODOs
 +=====
 +