docs reorg, generate static website from in-repo rst files

Using pandoc as a guide.

CONTRIBUTORS

@@ -1,5 +1,6 @@
+==============================
 Contributor Agreement and List
-##############################
+==============================
 
 hledger Contributor Agreement
 =============================

HOME

@@ -0,0 +1,71 @@
+hledger
+=======
+
+**Welcome! hledger is...**
+
+- a command-line (or curses or web-based) double-entry accounting tool.  It reads a
+  `plain text ledger <http://joyful.com/repos/hledger/sample.ledger>`_
+  describing your transactions and displays precise 
+  `balance <http://hledger.org:5000/balance>`_ and 
+  `register <http://hledger.org:5000/register?a=checking>`_ reports.
+- a remix, in `haskell <http://haskell.org>`_, of John Wiegley's excellent
+  c++ `ledger <http://wiki.github.com/jwiegley/ledger>`_ (because I
+  did not want to hack on c++ and because haskell seemed a good fit).
+- a Free Software project developed since 2008 by
+  `Simon Michael <http://joyful.com>`_ and contributors.
+
+**hledger aims to be...**
+
+- a practical, accessible tool for end users. I use it every day to track money and time, and as the basis for client invoices and tax returns.
+- a useful library for finance-minded haskell programmers
+- a successful, time-and-money-solvent project within a thriving ecosystem of financial software projects.
+
+**To get help...** 
+
+ chat me (sm) on the `#ledger irc channel
+ <irc://irc.freenode.net/#ledger>`_ which we share with ledger, or join
+ the `hledger google group <http://groups.google.com/group/hledger>`_.
+ Or for something private, `email me <mailto:simon@joyful.com>`_.
+
+Download
+--------
+hledger works on all major platforms, but does not yet have binaries or platform packages;
+you'll need to install `GHC <http://haskell.org/ghc>`_ and `cabal
+<http://www.haskell.org/cabal/download.html>`_, then
+install hledger from `hackage
+<http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hledger>`_ with:
+``cabal install hledger``
+
+Documentation
+-------------
+`User's Guide <README.html>`_ |
+`News <NEWS.html>`_ |
+`Developer API docs <http://joyful.com/repos/hledger/api-doc>`_ |
+`Developer Notes <http://joyful.com/darcsweb/darcsweb.cgi?r=hledger;a=plainblob;f=/NOTES>`_ |
+`Contributor List <CONTRIBUTORS.html>`_ |
+See also ledger's `home page <http://wiki.github.com/jwiegley/ledger>`_
+and `manual <http://joyful.com/repos/ledger/doc/ledger.html>`_.
+
+Screenshots
+-----------
+
+ .. raw:: html
+
+  <a href="SCREENSHOTS.html#hledger-screen-1"><img src=http://hledger.org/hledger-screen-1.png border=0 height=100></a>
+  <a href="SCREENSHOTS.html#sshot"><img src=http://hledger.org/sshot.png border=0 height=100></a>
+  <a href="SCREENSHOTS.html#watchhours"><img src=http://hledger.org/watchhours.png border=0 height=100></a>
+
+Code repository
+---------------
+``darcs get http://joyful.com/repos/hledger`` (or `browse with darcsweb <http://joyful.com/darcsweb/darcsweb.cgi?r=hledger>`_)
+
+Related projects
+----------------
+- `ledger <http://wiki.github.com/jwiegley/ledger>`_ inspired hledger, and the two projects are coevolving. If you liked hledger, try ledger too. It has more reporting options and is faster.
+- Tim Docker's `ledger-reports <http://dockerz.net/repos/ledger-reports>`_ uses hledger as a library to generate `html reports <http://dockerz.net/software/hledger_report_sample/report.html>`_. 
+- I have a few older bits and pieces at http://joyful.com/Ledger .
+
+.. easy analytics access
+.. raw:: html
+
+ <a href="https://www.google.com/analytics/reporting/?reset=1&id=15489822" accesskey="a"></a>

Makefile

@@ -120,10 +120,16 @@ sample.ledger:
 ######################################################################
 # DOCS
 
-DOCS=README NEWS
+DOCS=HOME README NEWS CONTRIBUTORS SCREENSHOTS
 
 # rebuild all docs
-docs: pdf api-docs
+docs: html pdf api-docs
+
+buildwebsite:
+	mkdir -p website
+	-cp doc/*.png website
+	for d in $(DOCS); do pandoc -r rst $$d >website/$$d.html; done
+	(cd website; rm -f index.html; ln -s HOME.html index.html)
 
 # rebuild pdf docs
 pdf:
@@ -341,6 +347,9 @@ emacstags:
 clean:
 	rm -f `find . -name "*.o" -o -name "*.hi" -o -name "*~" -o -name "darcs-amend-record*"`
 
+clean-docs:
+	rm -rf website
+
 Clean: clean clean-docs
 	rm -f hledger TAGS tags
 

NEWS

@@ -1,13 +1,13 @@
-2009/05/23 hledger 0.5.1 released
+hledger news
----------------------------------
+============
-Changes:
+
+2009/05/23 hledger 0.5.1
+.................................
 
   * two fixes: really disable vty flag by default, and include ConvertCommand in cabal file
 
-2009/05/23 hledger 0.5 released
+2009/05/23 hledger 0.5
--------------------------------
+...............................
-
-Changes:
 
   * the vty flag is disabled by default again, to ease installation on windows
   * use ledger 3 terminology: a ledger contains transactions which contain postings
@@ -16,8 +16,8 @@ Changes:
   * new "histogram" command shows transaction counts per day or other reporting interval
   * most commands now work properly with UTF8-encoded text (Sergey Astanin)
   * invoking as "hours" is now less different: it just uses your timelog, not your ledger
-  * --quarterly/-Q option summarises by quarter
+  * ..quarterly/-Q option summarises by quarter
-  * --uncleared/-U option looks only at uncleared transactions
+  * ..uncleared/-U option looks only at uncleared transactions
   * be more accurate about checking balanced amounts, don't rely on display precision
   * enforce balancing for bracketed virtual postings
   * fix bug in eliding of posting amounts
@@ -31,24 +31,16 @@ Changes:
   * code, api and documentation updates
   * add a contributor agreement/list
 
-Release contributors:
-
-  * Simon Michael
-  * Sergey Astanin
-
 Release stats:
 
+  * Contributors: Simon Michael, Sergey Astanin
   * Days since last release: 51
-  * Committers: 2
   * Commits: 101
   * Lines of non-test code: 2795
-  * Known errors: 0
   * Tests: 76
-
+  * Known errors: 0
+  * Performance:
 ..
-
-  * Performance::
-
                               || hledger-0.4 | hledger-0.5 | ledger
      =========================++=============+=============+=======
      -f sample.ledger balance ||        0.01 |        0.01 |   0.06
@@ -56,15 +48,12 @@ Release stats:
      -f 10000.ledger balance  ||       15.28 |       16.35 |   4.67
 
 
-
+2009/04/03 hledger 0.4
-2009/04/03 hledger 0.4 released
+...............................
--------------------------------
-
-Changes:
 
   * new "web" command serves reports in a web browser (install with -f happs to build this)
   * make the vty-based curses ui a cabal build option, which will be ignored on MS windows
-  * drop the --options-anywhere flag, that is now the default
+  * drop the ..options-anywhere flag, that is now the default
   * patterns now use not: and desc: prefixes instead of ^ and ^^
   * patterns are now case-insensitive, like ledger
   * !include directives are now relative to the including file (Tim Docker)
@@ -74,96 +63,73 @@ Changes:
   * balance report now passes all ledger compatibility tests
   * balance report now shows subtotals by default, like ledger 3
   * balance report shows the final zero total when -E is used
-  * balance report hides the final total when --no-total is used
+  * balance report hides the final total when ..no-total is used
-  * --depth affects print and register reports (aggregating with a reporting interval, filtering otherwise)
+  * ..depth affects print and register reports (aggregating with a reporting interval, filtering otherwise)
   * register report sorts transactions by date
   * register report shows zero-amount transactions when -E is used
   * provide more convenient timelog querying when invoked as "hours"
   * multi-day timelog sessions are split at midnight
   * unterminated timelog sessions are now counted. Accurate time reports at last!
-  * the test command gives better --verbose output
+  * the test command gives better ..verbose output
-  * --version gives more detailed version numbers including patchlevel for dev builds
+  * ..version gives more detailed version numbers including patchlevel for dev builds
   * new make targets include: ghci, haddocktest, doctest, unittest, view-api-docs
   * a doctest-style framework for functional/shell tests has been added
 
+Release stats:
+
+  * Contributors: Simon Michael, Tim Docker; thanks to the HAppS, happstack and testpack developers
+  * Days since release: 76
+  * Commits: 144
+  * Lines of non-test code: 2367
+  * Tests: 56
+  * Known errors: 0
+  * Performance:
 ..
-
-  * performance has decreased slightly::
-
                                    || hledger-0.3 | hledger-0.4 | ledger-0.3
      ==============================++=============+=============+===========
      -f sample.ledger balance      ||        0.02 |        0.01 |       0.07
      -f sample1000.ledger balance  ||        1.02 |        1.39 |       0.53
      -f sample10000.ledger balance ||       12.72 |       14.97 |       4.63
 
-Contributors:
 
-  * Simon Michael
+2009/01/17 hledger 0.3
-  * Tim Docker
+...............................
-  * HAppS, happstack and testpack developers
-
-Stats:
-
-  * Known errors: 0
-  * Commits: 144
-  * Committers: 2
-  * Tests: 56
-  * Non-test code lines: 2367
-  * Days since release: 76
-
-
-2009/01/17 hledger 0.3 released
--------------------------------
-
-Fixes:
 
   * count timelog sessions on the day they end, like ledger, for now
   * when options are repeated, use the last instead of the first
   * builds with ghc 6.10 as well as 6.8
-  * runs much faster than 0.2::
-
-     $ bench hledger-0.2 hledger ledger
-                                       || hledger-0.2 | hledger | ledger
-     ==================================++=============+=========+=======
-     -f 2008.ledger -s balance         ||        2.59 |    0.26 |   0.11
-     -f 10000entries.ledger -s balance ||      566.68 |    2.72 |   0.96
-
-Features:
-
   * a simple ui for interactive report browsing: hledger ui
   * accept smart dates everywhere (YYYYMMDD, Y/M/D, Y, M/D, D, jan, today, last week etc.)
-  * --period/-p flag accepting period expressions like "in 2008", "weekly from last month"..
+  * ..period/-p flag accepting period expressions like "in 2008", "weekly from last month"..
   * -W/-M/-Y convenience flags to summarise register weekly, monthly, yearly
-  * --depth and -E flags also affect summarised register reports (including depth=0)
+  * ..depth and -E flags also affect summarised register reports (including depth=0)
-  * --display/-d flag supporting date predicates (like "d<[DATE]", "d>=[DATE]")
+  * ..display/-d flag supporting date predicates (like "d<[DATE]", "d>=[DATE]")
   * !include directive to include additional ledger files
   * !account directive to set a default parent account
   * Added support for reading historical prices from files
   * timelog and ledger entries can be intermixed in one file
   * modifier and periodic entries can appear anywhere (but are still ignored)
   * help and readme improvements
+  * runs much faster than 0.2
 
-Contributors:
+Release stats:
 
-  * Simon Michael
+  * Contributors: Simon Michael, Nick Ingolia, Tim Docker; thanks to Corey O'Connor & the vty team
-  * Nick Ingolia
-  * Tim Docker
-  * Corey O'Connor & the vty team
-
-Stats:
-
-  * Known errors: 1
-  * Tests: 58
   * Lines of non-test code: 2123
+  * Tests: 58
+  * Known errors: 1
+  * Performance:
+..
+     $ bench hledger-0.2 hledger ledger
+                                       || hledger-0.2 | hledger | ledger
+     ==================================++=============+=========+=======
+     -f 2008.ledger -s balance         ||        2.59 |    0.26 |   0.11
+     -f 10000entries.ledger -s balance ||      566.68 |    2.72 |   0.96
 
 
-2008/11/23 hledger 0.2 released
+2008/11/23 hledger 0.2
 ...............................
 
-Summarised changes:
-
-* fixes
-
   * fix balance report totals when filtering by account
   * fix balance report selection of accounts when filtering by account
   * fix a bug with account name eliding in balance report
@@ -171,48 +137,41 @@ Summarised changes:
   * fix print command filtering by account
   * omit transactions with zero amount from register report
   * Fix bug in parsing of timelogs
-  * rename --showsubs to --subtotal, like ledger
+  * rename ..showsubs to ..subtotal, like ledger
-  * drop --usage flag
+  * drop ..usage flag
   * don't require quickcheck
-
+  * priced amounts (eg "10h @ $50") and ..basis/..cost/-B flag to show them with cost basis
-* features
+  * easy ..depth option, equivalent to c++ ledger's -d 'l<=N'
-
-  * priced amounts (eg "10h @ $50") and --basis/--cost/-B flag to show them with cost basis
-  * easy --depth option, equivalent to c++ ledger's -d 'l<=N'
   * smarter y/m/d date parsing for -b and -e
     (any number of digits, month and day default to 1, separator can be / - or .)
   * -n flag for balance command
-  * --empty/-E flag
+  * ..empty/-E flag
   * build a library, as well as the exe
   * new home page url (http://joyful.com/hledger)
   * publish html and pdf versions of README
   * detect display preferences for each commodity like c++ ledger
   * support amounts with multiple currencies/commodities
-  * support --real/-R flag
+  * support ..real/-R flag
-  * support -C/--cleared flag to filter by entry status (not transaction status)
+  * support -C/..cleared flag to filter by entry status (not transaction status)
   * support virtual and balanced virtual transactions
   * parse comment lines beginning with a space, as from M-; in emacs ledger-mode
   * allow any non-whitespace in account names, perhaps avoiding misleading missing amounts errors
   * clearer error message when we can't balance an entry
   * when we fail because of more than one missing amount in an entry, show the full entry
-  * document the built-in test runner in --help
+  * document the built-in test runner in ..help
-  * add a --verbose/-v flag, use it to show more test-running detail
+  * add a ..verbose/-v flag, use it to show more test-running detail
 
-Contributors:
+Release stats:
 
-  * Simon Michael
+  * Contributors: Simon Michael, Tim Docker
-  * Tim Docker
-
-Stats:
-
-  * Known errors: 0
-  * Tests: 43
   * Lines of non-test code: 1350
+  * Tests: 43
+  * Known errors: 0
 
 
-2008/10/15 hledger 0.1 released
+2008/10/15 hledger 0.1
 ...............................
 
-Contributors:
+Release stats:
 
-  * Simon Michael
+  * Contributors: Simon Michael

README

@@ -1,17 +1,17 @@
+hledger User's Guide
+====================
 
 Welcome to hledger! 
 
-hledger is a partial haskell clone of John Wiegley's text-based accounting
+hledger is a partial haskell clone of John Wiegley's "ledger" command-line
-tool, ledger (http://wiki.github.com/jwiegley/ledger). hledger generates
+accounting tool. hledger generates ledger-compatible register & balance
-ledger-compatible register & balance reports from a plain text journal,
+reports from a plain text ledger file, allows precise batch-mode or
-allows precise batch-mode or interactive querying, and demonstrates a pure
+interactive querying, and demonstrates a pure functional implementation of
-functional implementation of ledger.  For more information, see
+ledger.  For more information, see http://hledger.org .
-http://hledger.org .
 
 Copyright (c) 2007-2009 Simon Michael <simon@joyful.com>
 Released under GPL version 3 or later.
 
-
 Installation
 ------------
 
@@ -56,7 +56,6 @@ results.  Here are some commands to try::
  hledger web                           # web ui, installed with -fhapps
  echo >new; hledger -f new add         # input transactions from the command line
 
-
 Time reporting
 --------------
 
@@ -213,4 +212,4 @@ Other differences
 * hledger register report always sorts transactions by date
 * hledger doesn't show description comments as part of the description
 * hledger print puts a blank line after the entry, not before it
-* hledger doesn't print the trailing spaces after amount-elided postings
+* hledger doesn't print trailing spaces after amount-elided postings

SCREENSHOTS

@@ -0,0 +1,30 @@
+.. raw:: html 
+
+  <hr><a name=hledger-screen-1>
+
+Basic command-line reports, like ledger:
+
+ .. image:: http://hledger.org/hledger-screen-1.png
+
+
+.. raw:: html 
+
+  <hr><a name=sshot>
+
+The interactive curses interface ("hledger ui")
+
+ .. image:: http://hledger.org/sshot.png
+
+
+.. raw:: html 
+
+  <hr><a name=watchhours>
+
+A time dashboard in emacs. The upper window displays today's time report every minute (using ansi-term, watch, a helper script, and hledger invoked via "hours" symlink.) The lower window is viewing the timelog file, to tweak clock-ins/clock-outs made with C-x t i and C-x t o. (`ledgerutils.el <http://joyful.com/Ledger/#ledgertools>`_ has some related bits.):
+
+ .. image:: http://hledger.org/watchhours.png
+
+
+.. raw:: html 
+
+  <hr>

doc/HCAR-HOWTO

@@ -0,0 +1,129 @@
+From: Janis Voigtlaender <voigt@tcs.inf.tu-dresden.de>
+Newsgroups: gmane.comp.lang.haskell.cafe,gmane.comp.lang.haskell.general
+Subject: Call for Contributions - Haskell Communities and
+ Activities Report, May 2009 edition
+Date: Wed, 01 Apr 2009 15:08:49 +0200
+Organization: Dresden University of Technology
+
+Dear Haskellers,
+
+so much has happened in the Haskell world in the past months.
+Therefore, I would very much like to collect contributions for
+the 16th edition of the
+
+================================================================
+             Haskell Communities & Activities Report
+               http://www.haskell.org/communities/
+
+                 Submission deadline: 1 May 2009
+
+      (please send your contributions to hcar at haskell.org,
+                  in plain text or LaTeX format)
+================================================================
+
+This is the short story:
+
+* If you are working on any project that is in some way related
+   to Haskell, please write a short entry and submit it. Even if
+   the project is very small or unfinished or you think it is not
+   important enough -- please reconsider and submit an entry anyway!
+
+* If you are interested in any project related to Haskell that has not
+   previously been mentioned in the HC&A Report, please tell me, so that
+   I can contact the project leaders and ask them to submit an entry.
+
+* Feel free to pass on this call for contributions to others that
+   might be interested.
+
+More detailed information:
+
+The Haskell Communities & Activities Report is a bi-annual overview of
+the state of Haskell as well as Haskell-related projects over the
+last, and possibly the upcoming six months. If you have only recently
+been exposed to Haskell, it might be a good idea to browse the
+November 2008 edition -- you will find interesting topics described as
+well as several starting points and links that may provide answers to
+many questions.
+
+Contributions will be collected until the submission deadline. They
+will then be compiled into a coherent report that is published online
+as soon as it is ready. As always, this is a great opportunity to
+update your webpages, make new releases, announce or even start new
+projects, or to talk about developments you want every Haskeller to
+know about!
+
+Looking forward to your contributions,
+
+Janis (current editor)
+
+
+FAQ:
+
+Q: What format should I write in?
+
+A: The required format is a LaTeX source file, adhering to the template
+that is available at:
+
+     http://haskell.org/communities/05-2009/template.tex
+
+There is also a LaTeX style file at
+
+     http://haskell.org/communities/05-2009/hcar.sty
+
+that you can use to preview your entry. If you do not know LaTeX, then
+use plain text. If you modify an old entry that you have written for an
+earlier edition of the report, you should receive your old entry as a
+template soon (provided I have your valid email address). Please modify
+that template, rather than using your own version of the old entry as a
+template.
+
+Q: Can I include images?
+
+A: Yes, you are even encouraged to do so. Please use .jpg format, then.
+
+Q: How much should I write?
+
+A: Authors are asked to limit entries to about one column of text. This
+corresponds to approximately one page, or 40 lines of text, with the
+above style and template.
+
+A general introduction is helpful. Apart from that, you should focus on
+recent or upcoming developments. Pointers to online content can be given
+for more comprehensive or ``historic'' overviews of a project. Images do
+not count towards the length limit, so you may want to use this
+opportunity to pep entries up. There is no minimum length of an entry!
+The report aims at being as complete as possible, so please consider
+writing an entry, even if it is only a few lines long.
+
+Q: Which topics are relevant?
+
+A: All topics which are related to Haskell in some way are relevant. We
+usually had reports from users of Haskell (private, academic, or
+commercial), from authors or contributors to projects related to
+Haskell, from people working on the Haskell language, libraries, on
+language extensions or variants. We also like reports over distributions
+of Haskell software, Haskell infrastructure, books and tutorials on
+Haskell. Reports on past and upcoming events related to Haskell are also
+relevant. Finally, there might be new topics we do not even think about.
+As a rule of thumb: if in doubt, then it probably is relevant and has a
+place in the HCAR. You can also ask the editor.
+
+Q: Is unfinished work relevant? Are ideas for projects relevant?
+
+A: Yes! You can use the HCAR to talk about projects you are currently
+working on. You can use it to look for other developers that might help
+you. You can use it to write ``wishlist'' items for libraries and
+language features you would like to see implemented.
+
+Q: If I do not update my entry, but want to keep it in the report, what
+should I do?
+
+A: Tell the editor that there are no changes. The old entry will be
+reused in this case, but it might be dropped if it is older than a year,
+to give more room and more attention to projects that change a lot.
+Do not resend complete entries if you have not changed them.
+
+-- 
+Dr. Janis Voigtlaender
+http://wwwtcs.inf.tu-dresden.de/~voigt/
+mailto:voigt@tcs.inf.tu-dresden.de