##################
buildhtml2 Notes
##################

:Author: Robert W. Brewer
:Date: 2006-01-29

:Abstract:
  Generate a static website from reStructuredText_ source.

.. contents::

What is it?
#############

``buildhtml2.py`` is used to generate my website from
reStructuredText_ (reST) source.  The generated website
consists of mostly static XHTML pages, with a few plain
text files and software tarballs thrown in for good
measure.  

The generated website has a fairly standard heirarchical
file structure.  There is a single `header and footer`__
applied to every generated page, and every page links
to the same CSS_ style file.  This provides a consistent
look throughout the site.  The header contains a logo,
search bar, and navigation bar.  The footer contains
a copyright notice, links for validating the current
page, and a mention at the bottom that the page
was generated from reST source.  

__ /style/headerfooter.txt

Advantages
############

Here are some advantages of using reST markup as the source
content of a website:

+ well-documented, well-designed, extensible, mature,
  lightweight markup language.  Wiki markup just can't
  touch reST.
+ Use the same source documents for generating printed
  documentation.  reST can generate LaTeX now, which
  can provide beautiful PDFs.  It can also generate XML
  which is easily transformed into other markups.
  But unlike writing documents directly in XML with,
  say, docbook, reST is very readable as plain text.
+ use the same markup for README files, full-blown
  documentation, and web pages.  reST is unmatched
  in being able to "go anywhere."  People who download
  your software can read a README file as plain text
  without having any special tools installed.  
  And putting the same README on a nicely formatted
  webpage can be fully automated.

Are there any disadvantages to reST?  Its biggest
drawback is that it isn't too widely used yet.
But that is changing, and some wikis and blogging
tools are supporting it now.

Because of the reST header and footer directives, 
almost no HTML needs to be maintained directly.
In fact, presently the search form is the
only piece of human-edited HTML on my entire website.
That's about 7 lines of HTML.
This is a testament to the power of reST_ for 
doing logical markup, and CSS_ for doing visual
layout and formatting.

For an example of reST in action, check out 
the `source for this page`__.  You can also
try the link at the very bottom of every web page
on this site to view its reST source and get
a feel for it.

__ index.txt

Download
##########

.. NOTE::
   I am not providing this software with any
   expectation that you can just plug it in and
   make a website with it.  It is mainly useful for 
   developers and other curious individuals to see how
   I am creating my site.  That said, I am creating
   my site with it, so it can certainly be made to work.

+ `buildhtml2.tgz <buildhtml2.tgz>`_

License
#########

The main file is GNU GPL, but each file
in the distribution have 
its own copyright notice.  I'm looking
into `Creative Commons`_ licenses to 
see what I like best and may update this 
in the future.

.. _reST:
.. _reStructuredText: http://docutils.sf.net/rst.html
.. _CSS: http://www.w3.org/Style/CSS/ 
.. _Creative Commons: http://creativecommons.org