From 8905c3b2c64efe53d1cdab0711f36d6da9b6c0b7 Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Tue, 2 Jun 2009 19:54:45 +0000
Subject: [PATCH] simplify docs infrastructure

---
 doc/HCAR-HOWTO => HCAR-HOWTO              |   0
 Makefile                                  |  82 ++++++++++------------
 hledger-hcar-200811.tex                   |  19 +++++
 hledger-hcar-200905.tex                   |  19 +++++
 {doc/misc => website}/api-doc-frames.html |   2 +-
 {doc => website}/footer.html              |   0
 {doc => website}/header.html              |   0
 {doc => website}/hledger-screen-1.png     | Bin
 {doc => website}/hledger.css              |   0
 {doc/misc => website}/hoogle-small.html   |   0
 {doc => website}/sshot.png                | Bin
 {doc => website}/watchhours.png           | Bin
 12 files changed, 76 insertions(+), 46 deletions(-)
 rename doc/HCAR-HOWTO => HCAR-HOWTO (100%)
 create mode 100644 hledger-hcar-200811.tex
 create mode 100644 hledger-hcar-200905.tex
 rename {doc/misc => website}/api-doc-frames.html (88%)
 rename {doc => website}/footer.html (100%)
 rename {doc => website}/header.html (100%)
 rename {doc => website}/hledger-screen-1.png (100%)
 rename {doc => website}/hledger.css (100%)
 rename {doc/misc => website}/hoogle-small.html (100%)
 rename {doc => website}/sshot.png (100%)
 rename {doc => website}/watchhours.png (100%)

diff --git a/doc/HCAR-HOWTO b/HCAR-HOWTO
similarity index 100%
rename from doc/HCAR-HOWTO
rename to HCAR-HOWTO
diff --git a/Makefile b/Makefile
index a05779fb9..f2a84170d 100644
--- a/Makefile
+++ b/Makefile
@@ -22,7 +22,8 @@ BENCHEXES=hledger-0.4 hledger-0.5 ledger
 # command to run during profiling
 PROFCMD=-f 1000x1000x10.ledger balance
 
-# command to view postscript output
+# document viewing commands
+VIEWHTMLCMD=open
 VIEWPSCMD=open
 
 default: tag hledger
@@ -150,68 +151,66 @@ sample.ledger:
 	ghc -e 'putStr $$ unlines $$ replicate 100000 "!include sample.ledger"' >100000.ledger
 
 ######################################################################
-# DOCS
+# DOCUMENTATION
+
+# website/ and website/api-doc/ always exist. website contains both
+# generated files (UPPERCASE.html) and revision-controlled resource files
+# (everything else).  website/api-doc contains only generated files.
+cleandocs:
+	rm -rf website/[A-Z]*.html website/api-doc/*
 
 # rebuild all docs
-docs: buildwebsite pdf api-docs
+docs: web pdf api-docs
 
-buildwebsite: website
-	-cp doc/*.css website
-	-cp doc/*.png website
-	for d in $(DOCFILES); do pandoc -s -H doc/header.html -A doc/footer.html -r rst $$d >website/$$d.html; done
-	(cd website; rm -f index.html; ln -s HOME.html index.html)
+# build the main hledger.org website
+web:
+	for d in $(DOCFILES); do pandoc -s -H website/header.html -A website/footer.html -r rst $$d >website/$$d.html; done
+	cd website; rm -f index.html; ln -s HOME.html index.html
 
-pdf: website
-	for d in $(DOCFILES); do rst2pdf $$d -o website/$$d.pdf; done
+# generate pdf versions of main docs
+pdf:
+	-for d in $(DOCFILES); do rst2pdf $$d -o website/$$d.pdf; done
 
-website:
-		mkdir -p website
-
-# rebuild api docs
+# generate api docs
 # We munge haddock and hoogle into a rough but useful framed layout.
 # For this to work the hoogle cgi must be built with base target "main".
-api-docs: haddock hoogleweb
+api-docs: haddock hoogle
 	echo "Converting api docs to frames" ; \
-	sed -i -e 's%^></HEAD%><base target="main"></HEAD%' api-doc/modules-index.html ; \
-	cp doc/misc/api-doc-frames.html api-doc/index.html ; \
-	cp doc/misc/hoogle-small.html hoogle
+	sed -i -e 's%^></HEAD%><base target="main"></HEAD%' website/api-doc/modules-index.html ; \
+	cp website/api-doc-frames.html website/api-doc/index.html ; \
+	cp website/hoogle-small.html website/api-doc
 
-# build and preview the api docs
-BROWSER=open
+# generate and view the api docs
 view-api-docs: api-docs
-	$(BROWSER) api-doc/index.html
-
-api-doc-dir:
-	mkdir -p api-doc
+	$(VIEWHTMLCMD) website/api-doc/index.html
 
 MAIN=hledger.hs
 
-# --ignore-all-exports here means these are actually implementation docs
+# --ignore-all-exports means we are documenting internal implementation, not library api
 HADDOCK=haddock -B `ghc --print-libdir` --no-warnings --ignore-all-exports $(subst -D,--optghc=-D,$(BUILDFLAGS))
-haddock: api-doc-dir hscolour $(MAIN)
+haddock: hscolour $(MAIN)
 	echo "Generating haddock api docs with source" ; \
-	$(HADDOCK) -o api-doc -h --source-module=src-%{MODULE/./-}.html --source-entity=src-%{MODULE/./-}.html#%N $(filter-out %api-doc-dir hscolour,$^) && \
-		cp api-doc/index.html api-doc/modules-index.html
+	$(HADDOCK) -o website/api-doc -h --source-module=src-%{MODULE/./-}.html --source-entity=src-%{MODULE/./-}.html#%N $(filter-out %api-doc-dir hscolour,$^) && \
+		cp website/api-doc/index.html website/api-doc/modules-index.html
 
 HSCOLOUR=HsColour -css 
-hscolour: api-doc-dir
+hscolour:
 	echo "Generating colourised source" ; \
 	for f in $(SOURCEFILES); do \
-		$(HSCOLOUR) -anchor $$f -oapi-doc/`echo "src/"$$f | sed -e's%/%-%g' | sed -e's%\.hs$$%.html%'` ; \
+		$(HSCOLOUR) -anchor $$f -owebsite/api-doc/`echo "src/"$$f | sed -e's%/%-%g' | sed -e's%\.hs$$%.html%'` ; \
 	done ; \
-	cp api-doc/src-hledger.html api-doc/src-Main.html ; \
-	HsColour -print-css >api-doc/hscolour.css
+	cp website/api-doc/src-hledger.html website/api-doc/src-Main.html ; \
+	HsColour -print-css >website/api-doc/hscolour.css
 
 #set up the hoogle web interface
 #uses a hoogle source tree configured with --datadir=., patched to fix haddock urls/target frame
 HOOGLESRC=/usr/local/src/hoogle
 HOOGLE=$(HOOGLESRC)/dist/build/hoogle/hoogle
 HOOGLEVER=`$(HOOGLE) --version |tail -n 1 | sed -e 's/Version /hoogle-/'`
-hoogleweb: hoogleindex
+hoogle: hoogleindex
 	echo "Configuring hoogle web interface" ; \
 	if test -f $(HOOGLE) ; then \
-		mkdir -p hoogle && \
-		cd hoogle && \
+		cd website/api-doc && \
 		rm -f $(HOOGLEVER) && \
 		ln -s . $(HOOGLEVER) && \
 		cp -r $(HOOGLESRC)/src/res/ . && \
@@ -224,14 +223,10 @@ hoogleweb: hoogleindex
 #generate a hoogle index
 hoogleindex: $(MAIN)
 	echo "Generating hoogle index" ; \
-	mkdir -p hoogle && \
-	$(HADDOCK) -o hoogle --hoogle $^ && \
-	cd hoogle && \
+	$(HADDOCK) -o website/api-doc --hoogle $^ && \
+	cd website/api-doc && \
 	hoogle --convert=main.txt --output=default.hoo
 
-cleandocs:
-	rm -rf api-doc hoogle
-
 ######################################################################
 # RELEASING
 
@@ -383,9 +378,6 @@ 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
+Clean: clean cleandocs
 	rm -f hledger TAGS tags
 
diff --git a/hledger-hcar-200811.tex b/hledger-hcar-200811.tex
new file mode 100644
index 000000000..99ab61123
--- /dev/null
+++ b/hledger-hcar-200811.tex
@@ -0,0 +1,19 @@
+\begin{hcarentry}{hledger}
+\report{Simon Michael}%11/08
+\participants{}
+\makeheader
+
+hledger is a command-line accounting tool similar to John Wiegley’s ledger tool.
+
+The first release has been published on Hackage, and has attracted some
+interest. It can be used for generating simple balance and transaction
+reports from a plain-text general ledger. A home page and mail list has
+also been created.
+
+Immediate plans are to add some more of the most useful features from c++
+ledger, so that hledger can be used for day-to-day finances, and to grow
+the community of contributors.
+
+\FurtherReading
+  \url{http://joyful.com/hledger}
+\end{hcarentry}
diff --git a/hledger-hcar-200905.tex b/hledger-hcar-200905.tex
new file mode 100644
index 000000000..280f29b35
--- /dev/null
+++ b/hledger-hcar-200905.tex
@@ -0,0 +1,19 @@
+\begin{hcarentry}{hledger}
+\report{Simon Michael}%05/09
+\participants{}
+\makeheader
+
+hledger is a (primarily) command-line accounting tool similar to John
+Wiegley's "ledger".  It reads a plain text journal file describing money
+or commodity transactions, or timelog entries, and generates precise
+activity and balance reports.
+
+Since the last report, hledger has reached release 0.4 on Hackage. It has
+60 test cases, new features such as basic curses and web-based interfaces,
+and has had some performance tuning. It is now quite useful for day to day
+reporting of money and time. Also, the project has a new web address
+(hledger.org), and has attracted two new committers.
+
+\FurtherReading
+  \url{http://hledger.org}
+\end{hcarentry}
diff --git a/doc/misc/api-doc-frames.html b/website/api-doc-frames.html
similarity index 88%
rename from doc/misc/api-doc-frames.html
rename to website/api-doc-frames.html
index b85c7b891..5b8eac47f 100644
--- a/doc/misc/api-doc-frames.html
+++ b/website/api-doc-frames.html
@@ -7,7 +7,7 @@
 <frameset cols="30%, 70%">
 	<frameset rows="90%, 10%">
 		<frame name="side1" src="modules-index.html">
-		<frame name="side2" src="../hoogle/hoogle-small.html">
+		<frame name="side2" src="hoogle-small.html">
 	</frameset>
   <frame name="main" src="Main.html">
 
diff --git a/doc/footer.html b/website/footer.html
similarity index 100%
rename from doc/footer.html
rename to website/footer.html
diff --git a/doc/header.html b/website/header.html
similarity index 100%
rename from doc/header.html
rename to website/header.html
diff --git a/doc/hledger-screen-1.png b/website/hledger-screen-1.png
similarity index 100%
rename from doc/hledger-screen-1.png
rename to website/hledger-screen-1.png
diff --git a/doc/hledger.css b/website/hledger.css
similarity index 100%
rename from doc/hledger.css
rename to website/hledger.css
diff --git a/doc/misc/hoogle-small.html b/website/hoogle-small.html
similarity index 100%
rename from doc/misc/hoogle-small.html
rename to website/hoogle-small.html
diff --git a/doc/sshot.png b/website/sshot.png
similarity index 100%
rename from doc/sshot.png
rename to website/sshot.png
diff --git a/doc/watchhours.png b/website/watchhours.png
similarity index 100%
rename from doc/watchhours.png
rename to website/watchhours.png