simplify docs infrastructure

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
+# build the main hledger.org website
-	-cp doc/*.css website
+web:
-	-cp doc/*.png website
+	for d in $(DOCFILES); do pandoc -s -H website/header.html -A website/footer.html -r rst $$d >website/$$d.html; done
-	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
-	(cd website; rm -f index.html; ln -s HOME.html index.html)
 
-pdf: website
+# generate pdf versions of main docs
-	for d in $(DOCFILES); do rst2pdf $$d -o website/$$d.pdf; done
+pdf:
+	-for d in $(DOCFILES); do rst2pdf $$d -o website/$$d.pdf; done
 
-website:
+# generate api docs
-		mkdir -p website
-
-# rebuild 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 ; \
+	sed -i -e 's%^></HEAD%><base target="main"></HEAD%' website/api-doc/modules-index.html ; \
-	cp doc/misc/api-doc-frames.html api-doc/index.html ; \
+	cp website/api-doc-frames.html website/api-doc/index.html ; \
-	cp doc/misc/hoogle-small.html hoogle
+	cp website/hoogle-small.html website/api-doc
 
-# build and preview the api docs
+# generate and view the api docs
-BROWSER=open
 view-api-docs: api-docs
-	$(BROWSER) api-doc/index.html
+	$(VIEWHTMLCMD) website/api-doc/index.html
-
-api-doc-dir:
-	mkdir -p api-doc
 
 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,$^) && \
+	$(HADDOCK) -o website/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
+		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 ; \
+	cp website/api-doc/src-hledger.html website/api-doc/src-Main.html ; \
-	HsColour -print-css >api-doc/hscolour.css
+	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 website/api-doc && \
-		cd hoogle && \
 		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 website/api-doc --hoogle $^ && \
-	$(HADDOCK) -o hoogle --hoogle $^ && \
+	cd website/api-doc && \
-	cd hoogle && \
 	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:
+Clean: clean cleandocs
-	rm -rf website
-
-Clean: clean clean-docs
 	rm -f hledger TAGS tags
 

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}

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}

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">