Commits

Josh VanderLinden committed 36411bc

Lots of updates to the README

Comments (0)

Files changed (1)

 # HG changeset patch
-# Parent b16e101c48d3294ec1f8a80f04be94a808a32b64
+# Parent 73b7b304dd7cb436acbe3d17fdfa6c163b01e837
 
-diff -r b16e101c48d3 README
---- a/README	Fri Apr 23 11:53:30 2010 -0400
-+++ b/README	Fri Apr 23 12:19:58 2010 -0400
-@@ -1,33 +1,78 @@
+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 @@
  .. -*- restructuredtext -*-
  
 -=================
 -README for Sphinx
 -=================
++=============
++HgBlog Readme
++=============
+ 
+-Installing
+-==========
 +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.
  
--Installing
--==========
+-Use ``setup.py``::
 +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.
  
--Use ``setup.py``::
+-    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.
  
--    python setup.py build
--    sudo python setup.py install
--
--
++Why?? Aren't There Enough Blog Engines Already?
++===============================================
+ 
 -Reading the docs
 -================
--
++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.
+ 
 -After installing::
--
++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.
+ 
 -    cd doc
 -    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
++    * 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.
++* 
+ 
 -Contributing
-+Installation
++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
++  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``
++  directory.
++* 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.
++
++Requirements
  ============
  
 -Send wishes, comments, patches, etc. to sphinx-dev@googlegroups.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.
+ 
++* Python 2.4+
++* docutils 0.4+
++* Jinja2 2.2+
++* Pygments 0.8+
++* Mercurial 1.5+
++
++Installation
++============
++
 +There are several ways to install HgBlog:
- 
++
 +* Using ``pip`` (recommended)::
 +
 +    pip install -U hgblog