Cogito: Cleanup documentation building and add quick reference

Cogito: Cleanup documentation building and add quick reference

[Jonas Fonseca]

Hi,

Here are a few patches that makes it possible to build documentation as
PDF using docbook2pdf (chosen because xmlto doesn't seem to be able to
generate PDFs).

All the patches leads up to adding a quick reference with often used
Cogito commands and associated option. It is inspired by svn-ref and the
goal is to have the PDF version under two pages long. The grouping of
commands could need some more comments.

The quick reference can be translated into HTML, PDF and cg-ref(7)
manpage. The last one is achieved by stripping much of the markup from
the 'default' version since manpages cannot have table layout. Note the
HTML and PDF versions are generated as quick-reference.{html,pdf}. We
might want to generate cg-ref.{html,pdf} instead.

-- 
Jonas Fonseca

[PATCH 1/4] Simplify wildcards for match files to be ignored

[Jonas Fonseca]

Signed-off-by: Jonas Fonseca <fonseca@diku.dk>

---

 Documentation/Makefile |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 3aad2fb..661c259 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -1,4 +1,4 @@
-CG_IGNORE=$(wildcard ../cg-X* ../cg-*.orig ../cg-*.rej ../cg-*.in)
+CG_IGNORE=$(wildcard ../cg-X* ../cg-*.*)
 CG_SRC=$(filter-out $(CG_IGNORE), $(wildcard ../cg*))
 
 PACKAGE=cogito

-- 
Jonas Fonseca

Re: [PATCH 1/4] Simplify wildcards for match files to be ignored

[Horst von Brand]

Jonas Fonseca <fonseca@diku.dk> wrote:
> Signed-off-by: Jonas Fonseca <fonseca@diku.dk>
> 
> ---
> 
>  Documentation/Makefile |    2 +-
>  1 files changed, 1 insertions(+), 1 deletions(-)
> 
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 3aad2fb..661c259 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -1,4 +1,4 @@
> -CG_IGNORE=$(wildcard ../cg-X* ../cg-*.orig ../cg-*.rej ../cg-*.in)
> +CG_IGNORE=$(wildcard ../cg-X* ../cg-*.*)

Nope. Better be specific in what you delete. It is not exactly
performance-critical...
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                     Fono: +56 32 654431
Universidad Tecnica Federico Santa Maria              +56 32 654239
Casilla 110-V, Valparaiso, Chile                Fax:  +56 32 797513

Re: [PATCH 1/4] Simplify wildcards for match files to be ignored

[Jonas Fonseca]

Horst von Brand <vonbrand@inf.utfsm.cl> wrote Fri, Mar 10, 2006:
> Jonas Fonseca <fonseca@diku.dk> wrote:
> > Signed-off-by: Jonas Fonseca <fonseca@diku.dk>
> > 
> > ---
> > 
> >  Documentation/Makefile |    2 +-
> >  1 files changed, 1 insertions(+), 1 deletions(-)
> > 
> > diff --git a/Documentation/Makefile b/Documentation/Makefile
> > index 3aad2fb..661c259 100644
> > --- a/Documentation/Makefile
> > +++ b/Documentation/Makefile
> > @@ -1,4 +1,4 @@
> > -CG_IGNORE=$(wildcard ../cg-X* ../cg-*.orig ../cg-*.rej ../cg-*.in)
> > +CG_IGNORE=$(wildcard ../cg-X* ../cg-*.*)
> 
> Nope. Better be specific in what you delete. It is not exactly
> performance-critical...

The intention was to ignore also cg-*.patch, but then ignoring any file
with a dot in makes sense and avoids a lot more errors when building
documentation in a dirty tree.

-- 
Jonas Fonseca

[PATCH 2/4] Encode the manpage section in the file name

[Jonas Fonseca]

This makes it easier to handle other document types.

Signed-off-by: Jonas Fonseca <fonseca@diku.dk>

---

 Documentation/Makefile |   39 +++++++++++++++++++++++++++------------
 1 files changed, 27 insertions(+), 12 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 661c259..00e9276 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -3,13 +3,13 @@ CG_SRC=$(filter-out $(CG_IGNORE), $(wild
 
 PACKAGE=cogito
 
-MAN1_TXT=$(patsubst ../cg%,cg%.txt,$(CG_SRC))
-MAN7_TXT=$(PACKAGE).txt
+MAN1_TXT=$(patsubst ../cg%,cg%.1.txt,$(CG_SRC))
+MAN7_TXT=$(PACKAGE).7.txt
 
 DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) introduction.html
 
-DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT))
-DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT))
+DOC_MAN1=$(patsubst %.txt,%,$(MAN1_TXT))
+DOC_MAN7=$(patsubst %.txt,%,$(MAN7_TXT))
 
 prefix=$(HOME)
 bin=$(prefix)/bin
@@ -56,28 +56,43 @@ install-html: html
 	$(INSTALL) $(DOC_HTML) $(DESTDIR)/$(htmldir)
 
 clean:
-	rm -f *.xml *.html *.1 *.7 cg*.txt $(PACKAGE).txt
+	rm -f *.xml *.html *.1 *.7 cg*.[17].txt $(PACKAGE).7.txt
 
 .PRECIOUS: cg%.txt
 
 introduction.html: ../README
 	asciidoc -b xhtml11 -d article -f asciidoc.conf -o $@ $<
 
-%.html : %.txt
+%.1.html : %.1.txt
 	asciidoc -b xhtml11 -d manpage -f asciidoc.conf $<
 
-%.1 %.7 : %.xml
-	xmlto man $<
+%.7.html : %.7.txt
+	asciidoc -b xhtml11 -d manpage -f asciidoc.conf $<
 
-%.xml : %.txt
+%.html : %.txt
+	asciidoc -b xhtml11 -d article -f asciidoc.conf -o $@ $<
+
+%.1.xml : %.1.txt
 	asciidoc -b docbook -d manpage -f asciidoc.conf $<
 
-$(PACKAGE).txt : make-$(PACKAGE)-asciidoc
+%.7.xml : %.7.txt
+	asciidoc -b docbook -d manpage -f asciidoc.conf $<
+
+%.xml : %.txt
+	asciidoc -b docbook -d article -f asciidoc.conf $<
+
+%.1 : %.1.xml
+	xmlto man $<
+
+%.7 : %.7.xml
+	xmlto man $<
+
+$(PACKAGE).7.txt : make-$(PACKAGE)-asciidoc
 	./make-$(PACKAGE)-asciidoc > $@
 
 # It seems that cg%.txt won't match this so use an explicit rule
-cg.txt : ../cg make-cg-asciidoc
+cg.1.txt : ../cg make-cg-asciidoc
 	CGPACKAGE=$(PACKAGE) ./make-cg-asciidoc $< > $@
 
-cg-%.txt : ../cg-% make-cg-asciidoc
+cg-%.1.txt : ../cg-% make-cg-asciidoc
 	CGPACKAGE=$(PACKAGE) ./make-cg-asciidoc $< > $@

-- 
Jonas Fonseca

[PATCH 3/4] Generate PDF documents using docbook2pdf

[Jonas Fonseca]

Unfortunately xmlto cannot be used for this,

Signed-off-by: Jonas Fonseca <fonseca@diku.dk>

---

 Documentation/Makefile |   14 ++++++++++++--
 1 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 00e9276..d316a14 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -11,6 +11,8 @@ DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_
 DOC_MAN1=$(patsubst %.txt,%,$(MAN1_TXT))
 DOC_MAN7=$(patsubst %.txt,%,$(MAN7_TXT))
 
+DOC_PDF=$(patsubst %.txt,%.pdf,$(MAN1_TXT) $(MAN7_TXT)) introduction.pdf
+
 prefix=$(HOME)
 bin=$(prefix)/bin
 mandir=$(prefix)/man
@@ -35,15 +37,17 @@ all: html man txt
 
 html: $(DOC_HTML)
 
-
 man: man1 man7
 man1: $(DOC_MAN1)
 man7: $(DOC_MAN7)
 
+pdf: $(DOC_PDF)
+
 txt: txt1 txt7
 txt1: $(MAN1_TXT)
 txt7: $(MAN7_TXT)
 
+
 install: man txt
 	$(INSTALL) -m755 -d $(DESTDIR)/$(txtdir)
 	$(INSTALL) $(MAN1_TXT) $(MAN7_TXT) $(DESTDIR)/$(txtdir)
@@ -56,13 +60,16 @@ install-html: html
 	$(INSTALL) $(DOC_HTML) $(DESTDIR)/$(htmldir)
 
 clean:
-	rm -f *.xml *.html *.1 *.7 cg*.[17].txt $(PACKAGE).7.txt
+	rm -f *.xml *.html *.pdf *.1 *.7 cg*.[17].txt $(PACKAGE).7.txt
 
 .PRECIOUS: cg%.txt
 
 introduction.html: ../README
 	asciidoc -b xhtml11 -d article -f asciidoc.conf -o $@ $<
 
+introduction.xml: ../README
+	asciidoc -b docbook -d article -f asciidoc.conf -o $@ $<
+
 %.1.html : %.1.txt
 	asciidoc -b xhtml11 -d manpage -f asciidoc.conf $<
 
@@ -87,6 +94,9 @@ introduction.html: ../README
 %.7 : %.7.xml
 	xmlto man $<
 
+%.pdf : %.xml
+	docbook2pdf $<
+
 $(PACKAGE).7.txt : make-$(PACKAGE)-asciidoc
 	./make-$(PACKAGE)-asciidoc > $@
 
-- 
Jonas Fonseca

[PATCH 4/4] Add quick reference

[Jonas Fonseca]

Signed-off-by: Jonas Fonseca <fonseca@diku.dk>

---

 If someone wants to have a look, I've put it here:
 http://www.diku.dk/hjemmesider/studerende/fonseca/cg-ref.pdf

 Documentation/Makefile             |    9 ++-
 Documentation/asciidoc.conf        |    4 +
 Documentation/make-cg-ref-asciidoc |   61 +++++++++++++++++++
 Documentation/quick-reference.txt  |  114 ++++++++++++++++++++++++++++++++++++
 4 files changed, 185 insertions(+), 3 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index d316a14..439d20f 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -4,14 +4,14 @@ CG_SRC=$(filter-out $(CG_IGNORE), $(wild
 PACKAGE=cogito
 
 MAN1_TXT=$(patsubst ../cg%,cg%.1.txt,$(CG_SRC))
-MAN7_TXT=$(PACKAGE).7.txt
+MAN7_TXT=$(PACKAGE).7.txt cg-ref.7.txt
 
-DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) introduction.html
+DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) quick-reference.html introduction.html
 
 DOC_MAN1=$(patsubst %.txt,%,$(MAN1_TXT))
 DOC_MAN7=$(patsubst %.txt,%,$(MAN7_TXT))
 
-DOC_PDF=$(patsubst %.txt,%.pdf,$(MAN1_TXT) $(MAN7_TXT)) introduction.pdf
+DOC_PDF=$(patsubst %.txt,%.pdf,$(MAN1_TXT) $(MAN7_TXT)) quick-reference.pdf introduction.pdf
 
 prefix=$(HOME)
 bin=$(prefix)/bin
@@ -100,6 +100,9 @@ introduction.xml: ../README
 $(PACKAGE).7.txt : make-$(PACKAGE)-asciidoc
 	./make-$(PACKAGE)-asciidoc > $@
 
+cg-ref.7.txt : quick-reference.txt make-cg-ref-asciidoc
+	CGPACKAGE=$(PACKAGE) ./make-cg-ref-asciidoc $< > $@
+
 # It seems that cg%.txt won't match this so use an explicit rule
 cg.1.txt : ../cg make-cg-asciidoc
 	CGPACKAGE=$(PACKAGE) ./make-cg-asciidoc $< > $@
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index baefb2f..69f1646 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -19,3 +19,7 @@ ifdef::backend-xhtml11[]
 [gitlink-inlinemacro]
 <a href="{target}.html">{target}{0?({0})}</a>
 endif::backend-xhtml11[]
+
+[attributes]
+# Five non breaking spaces used for option indentation in the quick reference
+cg-refopt=&#160;&#160;&#160;&#160;&#160;
diff --git a/Documentation/make-cg-ref-asciidoc b/Documentation/make-cg-ref-asciidoc
new file mode 100755
index 0000000..7fd60ca
--- /dev/null
+++ b/Documentation/make-cg-ref-asciidoc
@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+#
+# Generate asciidoc manpage markup from Cogito quick reference file.
+# Copyright (c) Jonas Fonseca, 2006
+#
+# Takes the path to the reference file. Prints the manpage to stdout.
+
+PACKAGE=${CGPACKAGE:-cogito}
+
+ref=$1
+
+cat <<__END__
+cg-ref(7)
+=========
+
+NAME
+----
+cg-ref - Cogito quick reference
+
+SYNOPSIS
+--------
+A list of frequently used commands grouped with related commands.
+
+DESCRIPTION
+-----------
+
+__END__
+
+sed '0,/^$/d' < "$ref" | \
+sed '/^`/d' | \
+sed 's/--/../g' | \
+sed '/frame="none"/,1d' | \
+sed 's/\\$//' | \
+while read line; do
+	if echo "$line" | grep -q '^.*:$'; then
+		echo "$line"
+		echo "$line" | sed "s/[^~]/~/g"
+		echo
+		echo "[verse]"
+	else
+		entry=$(echo "$line" | sed "s/^\([^	]*\)	/\1/")
+		space=$(echo "$entry" | sed "s/[^*']//g" | sed "s/[*']/ /g")
+
+		echo "$line" | sed "s/^\([^	]*\)	/\1$space	/"
+	fi
+done | \
+sed 's/.*cg-refopt} \(-[^	]*\)/    \1        /' | \
+sed "s/[*]\([^*]*\)[*]/\1/g" | \
+sed "s/[']\([^']*\)[']/\1/g"
+
+cat << __END__
+
+COPYRIGHT
+---------
+Copyright (C) Jonas Fonseca, 2006.
+
+SEE ALSO
+--------
+gitlink:cg-ref[7] is part of gitlink:${PACKAGE}[7],
+a toolkit for managing gitlink:git[7] trees.
+__END__
diff --git a/Documentation/quick-reference.txt b/Documentation/quick-reference.txt
new file mode 100644
index 0000000..11c0a13
--- /dev/null
+++ b/Documentation/quick-reference.txt
@@ -0,0 +1,114 @@
+Cogito Quick Reference
+======================
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+Getting help:
+------------------------------------------------------------------------------
+*cg help* 'command'		Show help for a command
+*cg* 'command' -h		Show usage summary for a command
+------------------------------------------------------------------------------
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+Repository creation:
+------------------------------------------------------------------------------
+*cg init*			Create a repository in the current directory
+*cg clone* 'url'		Clone a remote repository
+------------------------------------------------------------------------------
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+File operations:
+------------------------------------------------------------------------------
+*cg add* 'file'			Add file to the working tree
+*cg add* -r 'directory'		Recursively add files in directory
+*cg rm* 'file'			Remove file or directory from the working tree
+*cg rm* -r 'directory'		Recursively remove files in directory
+{cg-refopt} -f			Delete file from disk
+*cg mv* 'file' 'dest'		Move file or directory to new location
+{cg-refopt} -f			Overwrite existing destination files
+*cg restore* 'file'		Restore file
+{cg-refopt} -r 'rev'		Bring back file from revision (and add it)
+{cg-refopt} -f			Overwrite uncommitted changes
+------------------------------------------------------------------------------
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+Examining History:
+------------------------------------------------------------------------------
+*cg log* '[file]'		View commit log
+{cg-refopt} -r 'rev'		Limit to revision range
+{cg-refopt} -f			List affected files
+{cg-refopt} -s			Summarize commits to one line
+*cg diff* '[file]'		Show diff of changes
+{cg-refopt} -r 'rev'		Diff revision instead of working tree
+{cg-refopt} -p			Diff against parent
+{cg-refopt} -s			Show diff stat
+------------------------------------------------------------------------------
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+Working tree:
+------------------------------------------------------------------------------
+*cg status* '[file]'		Show branches and status of the working tree
+*cg commit*			Commit the working tree
+{cg-refopt} -m 'message'	Append message to commit log
+*cg admin-uncommit*		Undo commit
+*cg reset*			Reset the working treeUndo commit
+*cg seek* 'rev'			Temporarily switch the working tree
+*cg clean*			Remove file not under revision control
+------------------------------------------------------------------------------
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+Remote branches:
+------------------------------------------------------------------------------
+*cg branch-ls*			List remote branches
+*cg branch-add* 'branch' 'url'	Add remote branch
+*cg branch-chg* 'branch' 'url'	Change URL of existing branch
+*cg fetch* 'branch'		Fetch changes from a remote branch
+*cg update* 'branch'		Fetch and merge changes from a remote branch
+*cg push* 'branch'		Push changes to a remote branch
+------------------------------------------------------------------------------
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+Local branches:
+------------------------------------------------------------------------------
+*cg merge* 'branch'		Merge changes from branch
+*cg switch* 'branch'		Switch the working tree to branch
+{cg-refopt} -r 'rev'		Create branch from revision
+{cg-refopt} -f			Overwrite existing branch
+------------------------------------------------------------------------------
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+Exporting and importing:
+------------------------------------------------------------------------------
+*cg patch*			Apply patch
+*cg mkpatch*			Format a patch with log message and diffstat
+{cg-refopt} -r 'rev'		Limit to revision range
+*cg export* 'directory'		Export "snapshot" to directory
+{cg-refopt} -r 'rev'			
+------------------------------------------------------------------------------
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+Tags:
+------------------------------------------------------------------------------
+*cg tag* 'name' 'rev'		Create tag for a given revision
+{cg-refopt} -s			Sign tag with your private key using GPG
+*cg tag-ls*			Show name and revision for all tags
+------------------------------------------------------------------------------
+
+`-------------------------------`---------------------------------------------
+File status flags:
+------------------------------------------------------------------------------
+?				file is unknown
+A				file has been added.
+D				file has been deleted.
+!				file is not in working tree
+M				file has been touched or modified
+m				file has been touched or modified (during merge)
+------------------------------------------------------------------------------

-- 
Jonas Fonseca

[PATCH 4/4] Add quick reference

[Jonas Fonseca]

Signed-off-by: Jonas Fonseca <fonseca@diku.dk>

---

 This renames quick-reference.txt to cg-ref.txt to address the
 cg-ref.pdf issue, makes the script more robust by using printf for
 alignment, and improves the reference itself a bit.

 Documentation/Makefile             |    9 ++-
 Documentation/asciidoc.conf        |    4 +
 Documentation/cg-ref.txt           |  116 ++++++++++++++++++++++++++++++++++++
 Documentation/make-cg-ref-asciidoc |   70 ++++++++++++++++++++++
 4 files changed, 196 insertions(+), 3 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index d316a14..b38fc4d 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -4,14 +4,14 @@ CG_SRC=$(filter-out $(CG_IGNORE), $(wild
 PACKAGE=cogito
 
 MAN1_TXT=$(patsubst ../cg%,cg%.1.txt,$(CG_SRC))
-MAN7_TXT=$(PACKAGE).7.txt
+MAN7_TXT=$(PACKAGE).7.txt cg-ref.7.txt
 
-DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) introduction.html
+DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) cg-ref.html introduction.html
 
 DOC_MAN1=$(patsubst %.txt,%,$(MAN1_TXT))
 DOC_MAN7=$(patsubst %.txt,%,$(MAN7_TXT))
 
-DOC_PDF=$(patsubst %.txt,%.pdf,$(MAN1_TXT) $(MAN7_TXT)) introduction.pdf
+DOC_PDF=$(patsubst %.txt,%.pdf,$(MAN1_TXT) $(MAN7_TXT)) cg-ref.pdf introduction.pdf
 
 prefix=$(HOME)
 bin=$(prefix)/bin
@@ -100,6 +100,9 @@ introduction.xml: ../README
 $(PACKAGE).7.txt : make-$(PACKAGE)-asciidoc
 	./make-$(PACKAGE)-asciidoc > $@
 
+cg-ref.7.txt : cg-ref.txt make-cg-ref-asciidoc
+	CGPACKAGE=$(PACKAGE) ./make-cg-ref-asciidoc $< > $@
+
 # It seems that cg%.txt won't match this so use an explicit rule
 cg.1.txt : ../cg make-cg-asciidoc
 	CGPACKAGE=$(PACKAGE) ./make-cg-asciidoc $< > $@
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index baefb2f..69f1646 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -19,3 +19,7 @@ ifdef::backend-xhtml11[]
 [gitlink-inlinemacro]
 <a href="{target}.html">{target}{0?({0})}</a>
 endif::backend-xhtml11[]
+
+[attributes]
+# Five non breaking spaces used for option indentation in the quick reference
+cg-refopt=&#160;&#160;&#160;&#160;&#160;
diff --git a/Documentation/cg-ref.txt b/Documentation/cg-ref.txt
new file mode 100644
index 0000000..ab2321b
--- /dev/null
+++ b/Documentation/cg-ref.txt
@@ -0,0 +1,116 @@
+Cogito Quick Reference
+======================
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+Getting help:
+------------------------------------------------------------------------------
+*cg help* 'command'		Show help for a command
+*cg* 'command' -h		Show usage summary for a command
+------------------------------------------------------------------------------
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+Repository creation:
+------------------------------------------------------------------------------
+*cg init*			Create a repository in the current directory
+*cg clone* 'url'		Clone a remote repository into a subdirectory
+------------------------------------------------------------------------------
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+File operations:
+------------------------------------------------------------------------------
+*cg add* 'file'			Add file to the working tree
+*cg add* -r 'directory'		Recursively add files in directory
+*cg rm* 'file'			Remove file or directory from the working tree
+*cg rm* -r 'directory'		Recursively remove files in directory
+{cg-refopt} -f			Delete file from disk
+*cg mv* 'file' 'destination'	Move file or directory to new location
+{cg-refopt} -f			Overwrite existing destination files
+*cg restore* 'file'		Restore file
+{cg-refopt} -r 'revision'	Bring back file from revision (and add it)
+{cg-refopt} -f			Overwrite uncommitted changes
+------------------------------------------------------------------------------
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+Working tree:
+------------------------------------------------------------------------------
+*cg status* '[file]'		Show branches and status of the working tree
+*cg reset*			Reset the working tree
+*cg clean*			Clean unknown files from the working tree
+*cg commit* '[file]'		Commit the working tree
+{cg-refopt} -m 'message'	Append message to commit log
+*cg admin-uncommit*		Undo commit
+*cg seek* 'revision'		Temporarily switch the working tree
+------------------------------------------------------------------------------
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+Examining History:
+------------------------------------------------------------------------------
+*cg log* '[file]'		View commit log
+{cg-refopt} -r 'revision'	Limit to revision range
+{cg-refopt} -f			List affected files
+{cg-refopt} -s			Summarize commits to one line
+*cg diff* '[file]'		Show diff of changes
+{cg-refopt} -r 'revision'	Diff revision instead of working tree
+{cg-refopt} -p			Diff against parent
+{cg-refopt} -s			Show diff stat
+------------------------------------------------------------------------------
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+Remote branches:
+------------------------------------------------------------------------------
+*cg fetch* '[branch]'		Fetch changes from a remote branch
+*cg update* '[branch]'		Fetch and merge changes from a remote branch
+*cg push* '[branch]'		Push changes to a remote branch
+*cg branch-ls*			List remote branches
+*cg branch-add* 'branch' 'url'	Add remote branch
+*cg branch-chg* 'branch' 'url'	Change URL of existing branch
+------------------------------------------------------------------------------
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+Local branches:
+------------------------------------------------------------------------------
+*cg merge* 'branch'		Merge changes from branch
+*cg switch* 'branch'		Switch the working tree to branch
+{cg-refopt} -r 'revision'	Create branch from revision
+{cg-refopt} -f			Overwrite existing branch
+------------------------------------------------------------------------------
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+Exporting and importing:
+------------------------------------------------------------------------------
+*cg patch* < 'file'		Apply patch from stdin
+*cg mkpatch*			Format a patch with log message and diffstat
+{cg-refopt} -r 'revision'	Limit to revision range
+*cg export* 'directory'		Export snapshot to directory
+*cg export* 'file.tar.gz'	Export snapshot to tar file
+{cg-refopt} -r 'revision'	Base snapshot on revision	
+------------------------------------------------------------------------------
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+Tags:
+------------------------------------------------------------------------------
+*cg tag* 'name' 'revision'	Create tag for a given revision
+{cg-refopt} -s			Sign tag with your private key using GPG
+*cg tag-ls*			Show name and revision for all tags
+------------------------------------------------------------------------------
+
+[frame="none"]
+`-------------------------------`---------------------------------------------
+File status flags:
+------------------------------------------------------------------------------
+`?` unknown			File is not under revision control
+`A` added			File has been added
+`D` deleted			File has been deleted
+`!` disappeared			File is not in the working tree
+`M` modified			File has been touched or modified
+`m` modified (while merging)	File was modified prior to the merge
+------------------------------------------------------------------------------
diff --git a/Documentation/make-cg-ref-asciidoc b/Documentation/make-cg-ref-asciidoc
new file mode 100755
index 0000000..960e711
--- /dev/null
+++ b/Documentation/make-cg-ref-asciidoc
@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+#
+# Generate asciidoc manpage markup from Cogito quick reference file.
+# Copyright (c) Jonas Fonseca, 2006
+#
+# Takes the path to the reference file. Prints the manpage to stdout.
+
+PACKAGE=${CGPACKAGE:-cogito}
+
+ref=$1
+
+cat <<__END__
+cg-ref(7)
+=========
+
+NAME
+----
+cg-ref - Cogito quick reference
+
+SYNOPSIS
+--------
+A list of frequently used commands grouped with related commands.
+
+DESCRIPTION
+-----------
+
+__END__
+
+sed '
+	0,/^$/d
+	/^`---/d
+	/frame="none"/,1d
+	s/\\$//
+	s/[*]\([^*]*\)[*]/\1/g
+	s/[`]\([^`]*\)[`]/\1/g
+	s/['\'']\([^'\'']*\)['\'']/\1/g
+' < "$ref" | \
+while read line; do
+	col1=$(echo "$line" | cut -f 1)
+	case "$line" in
+	*":")
+		echo "$line"
+		echo "$line" | sed "s/[^~]/~/g"
+		echo
+		echo "[verse]"
+		continue
+		;;
+	"-----"*|"")
+		echo "$line" | sed 's/-/./g'
+		continue
+		;;
+	"{cg-refopt}"*)
+		col1=$(echo "$col1" | sed 's/.*cg-refopt}/   /')
+		;;
+	esac
+	col2=$(echo "$line" | sed 's/.*[	]\+//')
+	printf "%-30s  %s\n" "$col1" "$col2"
+done
+
+cat << __END__
+
+COPYRIGHT
+---------
+Copyright (C) Jonas Fonseca, 2006.
+
+SEE ALSO
+--------
+gitlink:cg-ref[7] is part of gitlink:${PACKAGE}[7],
+a toolkit for managing gitlink:git[7] trees.
+__END__

-- 
Jonas Fonseca