[RFC] Embedding asciidoc manpages in the cg scripts

[RFC] Embedding asciidoc manpages in the cg scripts

[Jonas Fonseca]

Hi Pasky,

I am still a bit unsure how you want to embed asciidoc in the cg scripts
so I hope you will comment on this patch probe.

The Makefile stuff is pretty much ripped off from the recent Makefile by
David Greaves. I don't know if it should also live in
Documentation/Makefile.

You mentioned that you wanted the usage info in the USAGE variable. The
variable is initialized so that the usage info can be sed'ed out and
become part of the manpage. I assume the reason for this is to add a
usage function to cg-Xlib and use it as I have done in cg-add. This
should of course be done in a separate patch.

Finally, the embedded asciidoc markup. I still don't understand why you
dislike the cg-CMD strings in the NAME section. Asciidoc expects them
there and it will be so much harder to add them to the output of
$(cg-help cg-CMD).

---

 Makefile  |   28 +++++++++++++++++++++++++
 cg-Xlib   |    7 +++++-
 cg-add    |   28 ++++++++++++++++++++++---
 cg-commit |    4 +--
 cg-log    |   68 ++++++++++++++++++++++++++++++++++++++++++++------------------
 5 files changed, 110 insertions(+), 25 deletions(-)

Index: Makefile
===================================================================
--- 1cfa9d5a4f751f8ddd8b9a40758b8d6d0141264e/Makefile  (mode:100644)
+++ uncommitted/Makefile  (mode:100644)
@@ -29,6 +29,7 @@
 
 bindir?=$(prefix)/bin
 libdir?=$(prefix)/lib/cogito
+mandir?=$(prefix)/man/man1
 
 CC?=gcc
 AR?=ar
@@ -136,6 +137,8 @@
 	$(INSTALL) $(PROG) $(SCRIPTS) $(SCRIPT) $(GEN_SCRIPT) $(DESTDIR)$(bindir)
 	$(INSTALL) -m755 -d $(DESTDIR)$(libdir)
 	$(INSTALL) $(LIB_SCRIPT) $(DESTDIR)$(libdir)
+	$(INSTALL) -m755 -d $(DESTDIR)$(mandir)
+	$(INSTALL) $(MANDOC) $(DESTDIR)$(mandir)
 	cd $(DESTDIR)$(bindir); \
 	for file in $(SCRIPT); do \
 		sed -e 's/\$${COGITO_LIB}/\$${COGITO_LIB:-$(sedlibdir)\/}/g' $$file > $$file.new; \
@@ -157,3 +160,31 @@
 
 backup: clean
 	cd .. ; tar czvf dircache.tar.gz dir-cache
+
+
+DOCSRC	= cg-log cg-add
+HTMLDIR	= Documentation/html
+MANDIR	= Documentation/man/man1
+HTMLDOC	= $(patsubst %,$(HTMLDIR)/%.html,$(DOCSRC))
+MANDOC	= $(patsubst %,$(MANDIR)/%.1,$(DOCSRC))
+
+doc-clean:
+	$(RM) $(HTMLDOC) $(MANDOC)
+
+html: $(HTMLDOC)
+man: $(MANDOC)
+
+$(HTMLDIR):
+	$(INSTALL) -m755 -d $@
+
+$(MANDIR)/%.1: %.xml
+	xmlto man $< -o $(@D)
+
+%.xml: %.txt
+	asciidoc -b docbook -d manpage -o $@ $<
+
+$(HTMLDIR)/%.html: %.txt $(HTMLDIR)
+	asciidoc -b css-embedded -d manpage -o $@ $<
+
+%.txt: %
+	cg-help $< > $@
Index: cg-Xlib
===================================================================
--- 1cfa9d5a4f751f8ddd8b9a40758b8d6d0141264e/cg-Xlib  (mode:100755)
+++ uncommitted/cg-Xlib  (mode:100755)
@@ -17,6 +17,11 @@
 	exit 1
 }
 
+usage () {
+	echo "usage: $USAGE" >&2
+	exit 1
+}
+
 
 mktemp () {
 	if [ ! "$BROKEN_MKTEMP" ]; then
@@ -52,7 +57,7 @@
 
 print_help () {
 	which "cg-$1" >/dev/null 2>&1 || exit 1
-	cat $(which cg-$1) | sed -n '3,/^$/s/^# *//p'
+	cat $(which cg-$1) | sed 's/^USAGE="\(.*\)"/# \1/' | sed -n '3,/^$/s/^# *//p'
 	exit
 }
 
Index: cg-add
===================================================================
--- 1cfa9d5a4f751f8ddd8b9a40758b8d6d0141264e/cg-add  (mode:100755)
+++ uncommitted/cg-add  (mode:100755)
@@ -1,14 +1,36 @@
 #!/usr/bin/env bash
 #
-# Add new file to a GIT repository.
-# Copyright (c) Petr Baudis, 2005
+# CG-ADD(1)
+# =========
 #
+# NAME
+# ----
+# cg-add - add files to a GIT repository
+#
+# SYNOPSIS
+# --------
+USAGE="cg-add FILE..."
+#
+# DESCRIPTION
+# -----------
 # Takes a list of file names at the command line, and schedules them
 # for addition to the GIT repository at the next commit.
+#
+# The command will fail if one of the given files does not exist.
+#
+# cg-add is part of Cogito, an SCM-like toolkit for managing GIT trees.
+#
+# OPTIONS
+# -------
+# No options.
+#
+# COPYING
+# -------
+# Copyright (c) Petr Baudis, 2005.
 
 . ${COGITO_LIB}cg-Xlib
 
-[ "$1" ] || die "usage: cg-add FILE..."
+[ "$1" ] || usage
 
 for file in "$@"; do
 	if [ -f "$file" ]; then
Index: cg-log
===================================================================
--- 1cfa9d5a4f751f8ddd8b9a40758b8d6d0141264e/cg-log  (mode:100755)
+++ uncommitted/cg-log  (mode:100755)
@@ -1,26 +1,56 @@
 #!/usr/bin/env bash
 #
-# Make a log of changes in a GIT branch.
-# Copyright (c) Petr Baudis, 2005.
-# Copyright (c) David Woodhouse, 2005.
-#
-# Takes a -c option to add color to the output.
-# Currently, the colors are:
+# CG-LOG(1)
+# =========
 #
-#	header		Green	
-#	author 		Cyan
-#	committer	Magenta
-#	files		Blue
-#	signoff		Yellow
-#
-# Takes an -f option to list which files was changed.
-#
-# Takes an -r followed with id resolving to a commit to start from
-# (HEAD by default), or id1:id2 representing an (id1;id2] range
-# of commits to show.
+# NAME
+# ----
+# cg-log - show log information for files or a range of commits
+#
+# SYNOPSIS
+# --------
+USAGE="cg-log [ -c ] [ -f ] [ --help | -h ] [-r FROM_ID[:TO_ID]]... [FILE]..."
+#
+# DESCRIPTION
+# -----------
+# Display log information for files or a range of commits. The output
+# will automatically be displayed in pager unless it is piped.
+#
+# cg-log is part of Cogito, an SCM-like toolkit for managing GIT trees.
+#
+# OPTIONS
+# -------
+# Arguments not interpreted as options will be interpreted as filenames;
+# cg-log then displays only changes in those files.
+#
+# --help, -h::
+#	Print this documentation
+#
+# -c::
+#	Add color to the output. Currently, the colors are:
+#
+#		header		Green
+#		author		Cyan
+#		committer	Magenta
+#		files		Blue
+#		signoff		Yellow
+#
+# -f::
+#	List which files were changed.
+#
+# -r FROM_ID[:TO_ID]::
+#	Limit the log information to a range of commits. The range of
+#	included commits can be specified either as -r FROM_ID[:TO_ID]
+#	or as -r FROM_ID -r TO_ID. In both situations the -r option
+#	expects ID arguments which resolve to commits. For ranges, the
+#	log for both the specified IDs will be included. If TO_ID is
+#	left out all commits older than FROM_ID will not be shown. If no
+#	-r option is given commits starting from HEAD will be shown.
 #
-# The rest of arguments are took as filenames; cg-log then displays
-# only changes in those files.
+# COPYING
+# -------
+# Copyright (c) Petr Baudis, 2005.
+# Copyright (c) David Woodhouse, 2005.
 
 . ${COGITO_LIB}cg-Xlib
 # Try to fix the annoying "Broken pipe" output. May not help, but apparently
-- 
Jonas Fonseca

Re: [RFC] Embedding asciidoc manpages in the cg scripts

[Petr Baudis]

Dear diary, on Wed, May 11, 2005 at 03:44:45AM CEST, I got a letter
where Jonas Fonseca <fonseca@diku.dk> told me that...
> Index: cg-add
> ===================================================================
> --- 1cfa9d5a4f751f8ddd8b9a40758b8d6d0141264e/cg-add  (mode:100755)
> +++ uncommitted/cg-add  (mode:100755)
> @@ -1,14 +1,36 @@
>  #!/usr/bin/env bash
>  #
> -# Add new file to a GIT repository.
> -# Copyright (c) Petr Baudis, 2005
> +# CG-ADD(1)
> +# =========

This is really awful - it carries no interesting information whatsoever
since that is pretty obvious from the fact that it is in file called
cg-add.

>  #
> +# NAME
> +# ----
> +# cg-add - add files to a GIT repository

Half of this is useless, too.

I think you should just keep the first paragraph of the files as it is
now. Don't touch it, just parse it.

> +#
> +# SYNOPSIS
> +# --------

No need for this heading either.

> +USAGE="cg-add FILE..."
> +#
> +# DESCRIPTION
> +# -----------
>  # Takes a list of file names at the command line, and schedules them
>  # for addition to the GIT repository at the next commit.
> +#
> +# The command will fail if one of the given files does not exist.
> +#
> +# cg-add is part of Cogito, an SCM-like toolkit for managing GIT trees.

Useless.

> +#
> +# OPTIONS
> +# -------
> +# No options.

The rest of DESCRIPTION and OPTIONS looks fine.

I'd just expect you to be much less intrusive in the in-file comments
and do more work when processing the stuff. I'm commenting on how it
looks inside of the sources - do whatever is necessary when processing
it to generate a proper-looking manpage from it.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
C++: an octopus made by nailing extra legs onto a dog. -- Steve Taylor

Re: [RFC] Embedding asciidoc manpages in the cg scripts

[David Greaves]

Petr Baudis wrote:

>> #
>>+# NAME
>>+# ----
>>+# cg-add - add files to a GIT repository
>>    
>>
>
>Half of this is useless, too.
>
>I think you should just keep the first paragraph of the files as it is
>now. Don't touch it, just parse it.
>  
>
A bit harsh Petr.

Isn't the idea of using an already written tool that you don't _have_ to
parse it?
Where, consistently, do the cg-files have a 1 line summary.

>>+#
>>+# SYNOPSIS
>>+# --------
>>    
>>
>No need for this heading either.
>  
>
Actually there is :)
asciidoc won't produce a manpage without it.

>>+USAGE="cg-add FILE..."
>>+#
>>+# DESCRIPTION
>>+# -----------
>> # Takes a list of file names at the command line, and schedules them
>> # for addition to the GIT repository at the next commit.
>>+#
>>+# The command will fail if one of the given files does not exist.
>>+#
>>+# cg-add is part of Cogito, an SCM-like toolkit for managing GIT trees.
>>    
>>
>
>Useless.
>  
>
Yes - if you happen to have written and breathed the code - not so
useless if you're a normal user.

It cogito is ever installed as part of a distro (maybe even by default)
then it would be nice if "man cg-add" actually mentioned it was part of
cogito and git...

>>+#
>>+# OPTIONS
>>+# -------
>>+# No options.
>>    
>>
>
>The rest of DESCRIPTION and OPTIONS looks fine.
>
>I'd just expect you to be much less intrusive in the in-file comments
>and do more work when processing the stuff. I'm commenting on how it
>looks inside of the sources - do whatever is necessary when processing
>it to generate a proper-looking manpage from it.
>  
>
Having worked hard on being consistent throughout the git docs I'd say
that a little excess verbiage in the comments is a worthwhile price. I
don't think you can worry about performance or anything - these _are_
shell scripts!


Maybe you'd be happier if they were moved to the bottom of the file and
preceded with:

#asciidoc follows

Or if you don't like that then maybe keep them external.

David

-- 

Re: [RFC] Embedding asciidoc manpages in the cg scripts

[Petr Baudis]

Dear diary, on Thu, May 12, 2005 at 12:20:10AM CEST, I got a letter
where David Greaves <david@dgreaves.com> told me that...
> Petr Baudis wrote:
> 
> >> #
> >>+# NAME
> >>+# ----
> >>+# cg-add - add files to a GIT repository
> >>    
> >>
> >
> >Half of this is useless, too.
> >
> >I think you should just keep the first paragraph of the files as it is
> >now. Don't touch it, just parse it.
> >  
> >
> A bit harsh Petr.

Sorry, I didn't mean to sound (too) harsh. ;-)

> Isn't the idea of using an already written tool that you don't _have_ to
> parse it?

No, the idea is to get nice output while keeping the input easily human
readable. I'm only stretching that further, since we know more than
asciidoc itself does about the file. :-)

> Where, consistently, do the cg-files have a 1 line summary.

I can't parse this sentence, I fear. All the cg-files have a 1 line
summary, then one or more copyright lines, then the description 'n
stuff. That's fixed format, much like the git commit format.

> >>+#
> >>+# SYNOPSIS
> >>+# --------
> >>    
> >>
> >No need for this heading either.
> >  
> >
> Actually there is :)
> asciidoc won't produce a manpage without it.

So the script piping this to asciidoc can add this at the proper point.

> >>+USAGE="cg-add FILE..."
> >>+#
> >>+# DESCRIPTION
> >>+# -----------
> >> # Takes a list of file names at the command line, and schedules them
> >> # for addition to the GIT repository at the next commit.
> >>+#
> >>+# The command will fail if one of the given files does not exist.
> >>+#
> >>+# cg-add is part of Cogito, an SCM-like toolkit for managing GIT trees.
> >>    
> >>
> >
> >Useless.
> >  
> >
> Yes - if you happen to have written and breathed the code - not so
> useless if you're a normal user.

Sorry, I've meant only the "cg-add is part of Cogito, an SCM-like
toolkit for managing GIT trees" part is useless.

> It cogito is ever installed as part of a distro (maybe even by default)
> then it would be nice if "man cg-add" actually mentioned it was part of
> cogito and git...

Yes. I'm fine with it being in the manpage. I just don't want it in the
code since again, it is obvious there. And code (be it program code or
documentation code) duplication is wrong, if you have a non-trivial
chunk repeated over and over everywhere, you probably want to move it to
a single place. That'd be the conversion script here.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
C++: an octopus made by nailing extra legs onto a dog. -- Steve Taylor

Re: [RFC] Embedding asciidoc manpages in the cg scripts

[Jonas Fonseca]

[-- Attachment #1: Type: text/plain, Size: 1156 bytes --]

Petr Baudis <pasky@ucw.cz> wrote Thu, May 12, 2005:
> Dear diary, on Thu, May 12, 2005 at 12:20:10AM CEST, I got a letter
> where David Greaves <david@dgreaves.com> told me that...
> > Petr Baudis wrote:
> > 
> > >>+# NAME
> > >>+# ----
> > >>+# cg-add - add files to a GIT repository
> > >
> > >Half of this is useless, too.
> > >
> > >I think you should just keep the first paragraph of the files as it is
> > >now. Don't touch it, just parse it.
> > >  
> > A bit harsh Petr.
> 
> Sorry, I didn't mean to sound (too) harsh. ;-)

Don't mind that you are harsh if it makes sense and I must agree that
having a helper script really paid off reducing the added markup to
almost a half (in my initial patches). Plus, it is now easy to enhance
the manpages with links to referenced commands without having stuff like
'link:' markup in the script headers.

I ended up actually adding two scripts. One for lifting cg-* manpages
and one for generating a cogito manpage with an overview of commands and
information about command identifiers.

The generated manpages can be previewed at:

	http://www.nitro.dk/~jonas/cogito/manpages/cogito.html

-- 
Jonas Fonseca

[-- Attachment #2: cogito-manpages.patch --]
[-- Type: text/plain, Size: 43608 bytes --]

[PATCH] Cogito manpages

Add asciidoc markup to Cogito script headers. Add a script to generate
asciidoc manpages from the cg-* command headers and a script for
generating a cogito(1) manpage. Finally, add build rules for making
Cogito manpages.

Notes:

* USAGE variables are added which can later be used by cg-help or die().

* The command identifiers are name wrapped in '<'/'>' like in the GIT
  manpages and are not similar to those in cg-help.

* The top-level Makefile is changed to add a script header to cg-version
  so it could also have a man pages. Don't know if that belongs there or
  in Documentation/cg-version.txt. Anyway, in order to minimize the
  patch I cleaned up the checking of .git/HEAD.

* I had trouble getting asciidoc to accept the line

	git+ssh://[user@]host/path

  I couldn't figure out how to escape it so I changed it to

	git+ssh://host/path or git+ssh://user@host/path

  Finally the example with referencing branches via #fragments I shortened
  the rsync URL so the line breaking '\' was not needed.

* The description of -r options should be carefully reviewed. I changed
  them to be more alike across cg-{diff,log,mkpatch} and some of the
  original ones looked wrong.

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

---
 Documentation/Makefile            |   11 ++
 Documentation/make-cg-manpage     |   65 ++++++++++++++++
 Documentation/make-cogito-manpage |  149 ++++++++++++++++++++++++++++++++++++++
 Makefile                          |   33 +++++---
 cg-add                            |   18 ++++
 cg-admin-lsobj                    |   35 +++++++-
 cg-admin-uncommit                 |   28 ++++---
 cg-branch-add                     |   44 ++++++-----
 cg-branch-ls                      |   19 ++++
 cg-cancel                         |   19 +++-
 cg-clone                          |   17 +++-
 cg-commit                         |   95 +++++++++++++++++++-----
 cg-diff                           |   29 +++++--
 cg-export                         |   15 +++
 cg-help                           |   17 ++++
 cg-init                           |   15 +++
 cg-log                            |   71 +++++++++++++-----
 cg-ls                             |   35 ++++++++
 cg-merge                          |   25 ++++--
 cg-mkpatch                        |   39 ++++++++-
 cg-patch                          |   11 ++
 cg-pull                           |   15 +++
 cg-restore                        |   24 ++++--
 cg-rm                             |   11 ++
 cg-seek                           |   26 ++++--
 cg-status                         |   30 +++++++
 cg-tag                            |   15 +++
 cg-tag-ls                         |    9 ++
 cg-update                         |   16 +++-
 29 files changed, 785 insertions(+), 151 deletions(-)

Index: Documentation/Makefile
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/Documentation/Makefile  (mode:100644)
+++ uncommitted/Documentation/Makefile  (mode:100644)
@@ -1,4 +1,7 @@
-DOC_SRC=$(wildcard git*.txt)
+CG_IGNORE=$(wildcard ../cg-X*)
+CG_SRC=$(filter-out $(CG_IGNORE), $(wildcard ../cg-*))
+CG_TXT=cogito.txt $(patsubst ../cg-%,cg-%.txt,$(CG_SRC))
+DOC_SRC=$(wildcard git*.txt) $(CG_TXT)
 DOC_HTML=$(patsubst %.txt,%.html,$(DOC_SRC))
 DOC_MAN=$(patsubst %.txt,%.1,$(DOC_SRC))
 
@@ -22,3 +25,9 @@
 
 %.xml : %.txt
 	asciidoc -b docbook -d manpage $<
+
+cogito.txt : make-cogito-manpage
+	./make-cogito-manpage > $@
+
+cg-%.txt : ../cg-% make-cg-manpage
+	./make-cg-manpage $< > $@
Index: Documentation/make-cg-manpage
===================================================================
--- /dev/null  (tree:de641904363cd3759f132ee7c0dfaf8a2ee58388)
+++ uncommitted/Documentation/make-cg-manpage  (mode:100755)
@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+#
+# Generate asciidoc manpage markup from Cogito script header.
+# Copyright (c) Jonas Fonseca, 2005
+#
+# Takes a path to a Cogito script. Prints the manpage to stdout.
+
+. ${COGITO_LIB}cg-Xlib
+
+command=$1
+
+[ -e "$command" ] || die "$command does not exist"
+
+COMMAND=$(basename $command)
+
+# FIXME: Show the SHA1 of the command below the TITLELINE.
+
+# Generate the 'CG-COMMAND(1)' title from cg-command
+TITLE="$COMMAND(1)"
+# Asciidocs wants the title line ('====') to be as wide as the title.
+TITLELINE=$(echo "$TITLE" | sed 's/[0-9a-zA-Z-()]/=/g')
+
+# Get `USAGE="cg-command args..."` line and make it `cg-command args...`
+SYNOPSIS=$(grep 'USAGE=' $command | sed 's/^USAGE="\(.*\)"/\1/')
+
+# Extract the script header.
+HEADER=$(cat $command | sed -n '3,/^$/s/^# *//p')
+
+# Some scripts have copyright lines followed by 'Based on script by ...' lines.
+# Include them so they are also put in the COPYRIGHT section.
+COPYRIGHT=$(cat $command | sed -n '3,/^$/s/^# *//p' \
+			 | sed -n '/^Copyright (c)/,/^$/p' \
+			 | sed 's/(c)/(C)/')
+
+# First line of the header contains the caption. Normalize it by lowercasing the
+# start and stripping any punctuation.
+CAPTION=$(echo "$HEADER" | head -n 1 | tr '[A-Z]' '[a-z]' | sed 's/\.$//')
+
+# Get remaining sections and carefully insert links to cogito commands when they
+# were referenced as "`cg-command`". Note, we can't just do it for any cg-*
+# combo because code listings will ignore any asciidoc markup...."
+BODY=$(echo "$HEADER" | sed -n '/^DESCRIPTION$/,$p' \
+		      | sed 's/`\(cg-[a-z-]\+\)`/link:\1.html[`\1(1)`]/')
+
+echo "$TITLE"
+echo "$TITLELINE"
+echo
+echo "NAME"
+echo "----"
+echo "$COMMAND - $CAPTION"
+echo
+echo "SYNOPSIS"
+echo "--------"
+echo "$SYNOPSIS"
+echo
+echo "$BODY"
+echo
+echo "COPYRIGHT"
+echo "---------"
+echo "$COPYRIGHT"
+echo
+echo "SEE ALSO"
+echo "--------"
+echo "$COMMAND command is part of link:cogito.html[cogito(1)],"
+echo "a toolkit for managing link:git.html[git(1)] trees."
Index: Documentation/make-cogito-manpage
===================================================================
--- /dev/null  (tree:de641904363cd3759f132ee7c0dfaf8a2ee58388)
+++ uncommitted/Documentation/make-cogito-manpage  (mode:100755)
@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+#
+# Generate a quick reference asciidoc manpage for the Cogito.
+# Copyright (c) Jonas Fonseca, 2005
+
+# Shorthand for the link markup.
+link()
+{
+	command="$1"
+	echo "link:$command.html[\`$command(1)\`]"
+}
+
+# Print description list entry.
+print_command_info()
+{
+	command="$1"
+	caption=$(cat "$command" | head -n 3 | tail -n 1 | sed 's/# //')
+	usage=$(grep 'USAGE=' "$command" | sed 's/^USAGE="\(.*\)"/\1/')
+	cmdname=$(basename $command)
+
+	echo
+	case "$cmdname" in
+	cg-*)
+		link "$cmdname"
+		;;
+	*-id)
+		echo "$cmdname::"
+		;;
+	esac
+	echo "	$caption"
+	echo
+	echo "	$usage"
+}
+
+cat <<__END__
+cogito(1)
+=========
+
+NAME
+----
+cogito - SCM-like GIT layer
+
+SYNOPSIS
+--------
+cg-<command> <arg>...
+
+DESCRIPTION
+-----------
+
+Cogito is a revision control system for tracking changes to content in a
+highly distributed development environment. Amongst some of the noteworthy
+features, Cogito has support for branching, tagging and multiple backends for
+distributing repositories (local files, rsync, HTTP, ssh).
+
+Cogito is implemented as a series of \`bash(1)\` scripts on top of $(link git)
+(a stupid content tracker) with the goal of providing an interface for working
+with the GIT database in a manner similar to other SCM tools (like CVS,
+BitKeeper or Monotone).
+
+Commands Overview
+-----------------
+
+The Cogito commands can be split into regular commands and advanced commands.
+The regular commands are those used for normal interacting with the
+repository, while the advanced commands can be used for administrating the
+repository and should to some degree be regarded as low-level and in some
+cases dangerous.
+
+Below an overview of the available commands are listed. For details on
+individual commands, do e.g. \`cg-help cg-log\` or \`cg-log --help\`.
+
+Regular commands
+~~~~~~~~~~~~~~~~
+__END__
+
+for command in $(ls ../cg-* | grep -v cg-admin- | grep -v cg-X); do
+	print_command_info "$command"
+done
+
+cat <<__END__
+
+Advanced commands
+~~~~~~~~~~~~~~~~~
+__END__
+
+for command in $(ls ../cg-admin-*); do
+	print_command_info "$command"
+done
+
+cat <<__END__
+
+Helper commands
+~~~~~~~~~~~~~~~
+
+Cogito also provides various helper commands for resolving IDs for symbolic
+names etc. The commands are:
+__END__
+
+for command in $(ls ../*-id | grep -v git-); do
+	print_command_info "$command"
+done
+
+cat <<__END__
+
+Command Identifiers
+-------------------
+<branch>::
+	Indicates a branch name added with the $(link cg-branch-add) name.
+
+<command>::
+	Indicates a Cogito command. The \`cg-\` prefix is optional.
+
+<location>::
+	Indicates a local file path or a URI. See $(link cg-branch-add) for a
+	list of supported URI schemes.
+
+<revision>::
+	Indicates an ID resolving to a commit. The following expressions can
+	be used interchangably as IDs:
+	- empty string, 'this' or 'HEAD' (current HEAD)
+	- branch name (as registered with $(link cg-branch-add))
+	- tag name (as registered with $(link cg-tag))
+	- shortcut object hash (shorted unambiguous hash lead)
+	- commit object hash (as returned by \`commit-id\`)
+	- tree object hash (as returned by \`tree-id\`)
+
+<tag>::
+	Indicates a free form tag name.
+
+<type>::
+	Indicates a git object type i.e.: \`blob\`, \`commit\`, \`tree\` or
+	\`tag\`.
+
+<username>::
+	Indicates a free form user name.
+
+<file>::
+	Indicates a filename - always relative to the root of the repository.
+
+AUTHORS
+-------
+Cogito was written by Petr Baudis <pasky@ucw.cz>.
+This manpage was written by Jonas Fonseca <fonseca@diku.dk>.
+
+COPYRIGHT
+---------
+Copyright (C) Petr Baudis, 2005.
+Copyright (C) Jonas Fonseca, 2005.
+__END__
Index: Makefile
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/Makefile  (mode:100644)
+++ uncommitted/Makefile  (mode:100644)
@@ -114,20 +114,33 @@
 
 
 ifneq (,$(wildcard .git))
-cg-version: $(VERSION) .git/HEAD
-	@echo Generating cg-version...
-	@rm -f $@
-	@echo "#!/bin/sh" > $@
-	@echo "echo \"$(shell cat $(VERSION)) ($(shell cat .git/HEAD))\"" >> $@
-	@chmod +x $@
-else
-cg-version: $(VERSION)
+GIT_HEAD=.git/HEAD
+GIT_HEAD_ID=" $(shell cat $(GIT_HEAD))"
+endif
+cg-version: $(VERSION) $(GITHEAD) Makefile
 	@echo Generating cg-version...
 	@rm -f $@
 	@echo "#!/bin/sh" > $@
-	@echo "echo \"$(shell cat $(VERSION))\"" >> $@
+	@echo "#" >> $@
+	@echo "# Show the version of the Cogito toolkit." >> $@
+	@echo "# Copyright (c) Petr Baudis, 2005" >> $@
+	@echo "#" >> $@
+	@echo "# DESCRIPTION" >> $@
+	@echo "# -----------" >> $@
+	@echo "# Show which version of Cogito is installed." >> $@
+	@echo "# Additionally, the 'HEAD' of the installed Cogito" >> $@
+	@echo "# is also shown if this information was available" >> $@
+	@echo "# at the build time." >> $@
+	@echo "#" >> $@
+	@echo "# OPTIONS" >> $@
+	@echo "# -------" >> $@
+	@echo "# -h, --help::" >> $@
+	@echo "#	Print usage help." >> $@
+	@echo >> $@
+	@echo "USAGE=\"cg-version\"" >> $@
+	@echo >> $@
+	@echo "echo \"$(shell cat $(VERSION))$(GIT_HEAD_ID)\"" >> $@
 	@chmod +x $@
-endif
 
 git.spec: git.spec.in $(VERSION)
 	sed -e 's/@@VERSION@@/$(shell cat $(VERSION) | cut -d"-" -f2)/g' < $< > $@
Index: cg-add
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-add  (mode:100755)
+++ uncommitted/cg-add  (mode:100755)
@@ -1,10 +1,26 @@
 #!/usr/bin/env bash
 #
-# Add new file to a GIT repository.
+# Add files to the GIT repository.
 # Copyright (c) Petr Baudis, 2005
 #
+# DESCRIPTION
+# -----------
 # Takes a list of file names at the command line, and schedules them
 # for addition to the GIT repository at the next commit.
+#
+# The command will fail if one of the given files does not exist.
+#
+# Note that cogito manage content. Which means it doesn't make sense
+# to `cg-add` stand-alone directories since directories have no content.
+# Instead add a file within the new directory and `cg-add` will create
+# a tree for managing the directory as needed.
+#
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-add <file>..."
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-admin-lsobj
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-admin-lsobj  (mode:100755)
+++ uncommitted/cg-admin-lsobj  (mode:100755)
@@ -4,17 +4,44 @@
 # Copyright (c) Randy Dunlap, 2005
 # Copyright (c) Petr Baudis, 2005
 #
-# Lists IDs of all the objects of a given type (blob, tree, commit) found
-# in the dircache.
+# DESCRIPTION
+# -----------
+# Lists IDs of all the objects of a given type found in the dircache.
+# Takes the object type as the first parameter, defaults to all objects.
+#
+# The possible object types are:
+# `blob`::
+#	This object is a pure storage object containing some user data.
+#
+# `commit`::
+#	This object ties directory hierarchies together into a DAG
+#	of revisions.
+#
+# `tree`::
+#	This object is an object that ties one or more `blob` objects
+#	into a directory structure.
+#
+# `tag`::
+#	This object ties a symbolic release tag to an object in the
+#	database.
 #
-# Example usage:
+# See the git README for more information about the object types.
+#
+# EXAMPLE USAGE
+# -------------
 # Oh, I was messing with my HEADs and lost few commits, where on the earth
 # could they be...?
+#
 #	for i in `cg-admin-lsobj commit | cut -f 1`; do
 #		echo -e "\n==================\nme $i"; cat-file commit $i;
 #	done
 #
-# Takes the object type as the first parameter, defaults to all objects.
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-admin-lsobj [<type>]"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-admin-uncommit
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-admin-uncommit  (mode:100755)
+++ uncommitted/cg-admin-uncommit  (mode:100755)
@@ -1,18 +1,28 @@
 #!/usr/bin/env bash
 #
-# Undo a commit or a series of commits
+# Undo a commit or a series of commits.
 # Copyright (c) Matt Porter, 2005
 # Copyright (c) Petr Baudis, 2005
 #
-# Optional -t parameter makes cg-admin-uncommit to roll back the tree
-# as well to the previous commit. Without this option (by default)
-# Cogito keeps the tree in its current state, therefore generating
-# tree with local changes against the target commit, consisting of the
-# changes in the rolled back commits.
+# DESCRIPTION
+# -----------
+# Takes a commit ID which is the earliest commit to be removed from
+# the repository. If no parameter is passed, it uncommits the latest
+# commit ('HEAD').
 #
-# Takes a commit ID which is the earliest commit to be
-# removed from the repository. If no parameter is passed,
-# it uncommits the latest commit (HEAD).
+# OPTIONS
+# -------
+# -t::
+#	This optional parameter makes `cg-admin-uncommit` to roll back
+#	the tree as well to the previous commit. Without this option
+#	(by default) Cogito keeps the tree in its current state,
+#	therefore generating tree with local changes against the target
+#	commit, consisting of the changes in the rolled back commits.
+#
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-admin-uncommit [-t] [<commit>]"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-branch-add
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-branch-add  (mode:100755)
+++ uncommitted/cg-branch-add  (mode:100755)
@@ -3,35 +3,41 @@
 # Add new branch to the GIT repository.
 # Copyright (c) Petr Baudis, 2005
 #
-# After you add a branch, you can cg-pull it whenever you want
-# and it will keep your objects database in sync with it. Its latest
-# commit is accessible as .git/refs/heads/branchname (or - more conveniently
-# - as $(commit-id branchname)). For example, to make a diff between
-# Linus (after you added him) and your current tree, do
-#
-#	cg-pull linus
-#	cg-diff linus
+# DESCRIPTION
+# -----------
+# Takes the branch name and source location as parameters.
+# After you add a branch, you can `cg-pull` it whenever you want and
+# it will keep your objects database in sync with it. Its latest
+# commit is accessible as `.git/refs/heads/branchname` (or - more
+# conveniently - as `$(commit-id branchname)`). For example, to make a
+# diff between Linus (after you added him) and your current tree, do:
 #
+#	$ cg-pull linus
+#	$ cg-diff linus
 #
 # The possible location specifiers are:
 #
-# (1) Local path - note that pulling will hardlink the objects, not copy them.
-# (2) rsync - either rsync://host/path or host:/path (the latter can change)
-# (3) HTTP - http://host/path
-# (4) SSH - git+ssh://[user@]host/absolute/path
+# 1. Local path - note that pulling will hardlink the objects, not copy them.
+# 2. rsync - either `rsync://host/path` or `host:/path` (the latter can change)
+# 3. HTTP - `http://host/path`
+# 4. SSH - `git+ssh://host/path` or `git+ssh://user@host/path` - note that
+#    the path must be absolute.
 #
 # The URL can have a fragment part, which identifies a branch inside of
 # the repository. Therefore, if you have a repository
-# rsync://kernel.org/pub/scm/linux/kernel/mj/linux.git and you are interested
-# in its 'testing' branch, you can e.g.
-#
-#	cg-branch-add mj-testing \
-#		rsync://kernel.org/pub/scm/linux/kernel/mj/linux.git#testing
+# `rsync://host/path/repo.git` and you are interested in its 'testing'
+# branch, you can e.g.:
 #
-# and refer to it as 'mj-testing' anytime later.
+#	$ cg-branch-add repo-testing rsync://host/path/repo.git#testing
 #
+# and refer to it as 'repo-testing' anytime later.
 #
-# Takes the branch' name and location as parameters.
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-admin-uncommit <branch> <location>"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-branch-ls
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-branch-ls  (mode:100755)
+++ uncommitted/cg-branch-ls  (mode:100755)
@@ -3,7 +3,24 @@
 # List configured GIT branches.
 # Copyright (c) Steven Cole 2005
 #
-# Takes no parameters.
+# DESCRIPTION
+# -----------
+# Print a listing of all known branches.
+#
+# The output has the following format:
+#
+#	<branch> <location>
+# 
+# For example
+#
+#	origin  rsync://rsync.kernel.org/pub/scm/cogito/cogito.git
+#
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-branch-ls"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-cancel
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-cancel  (mode:100755)
+++ uncommitted/cg-cancel  (mode:100755)
@@ -3,16 +3,23 @@
 # Cancels current edits in the working tree.
 # Copyright (c) Petr Baudis, 2005
 #
-# This script reverts the working tree to a consistent state before
-# any changes to it (including merges etc) were done.
+# DESCRIPTION
+# -----------
+# Reverts the working tree to a consistent state before any changes to it
+# (including merges etc.) were done.
 #
-# Basically, this is the opposite of cg-commit in some sense.
+# Basically, this is the opposite of `cg-commit` in some sense.
 #
-# Takes no arguments and the evil changes from the tree.
-#
-# This command is complementary to cg-restore, which only brings
+# This command is complementary to `cg-restore`, which only brings
 # individual files in sync with their state at the time of the
 # last commit.
+#
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help
+
+USAGE="cg-cancel"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-clone
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-clone  (mode:100755)
+++ uncommitted/cg-clone  (mode:100755)
@@ -3,16 +3,25 @@
 # Clone a remote GIT repository.
 # Copyright (c) Petr Baudis, 2005
 #
+# DESCRIPTION
+# -----------
 # This is like cg-init, but it will create a new directory where it will do
 # the checkout.
 #
-# If you pass it an optional -s parameter, it does the clone in the current
-# directory instead of creating a new one.
-#
 # Takes a parameter specifying the location of the source repository and an
-# optional second parameter specifying the destination.  If the second
+# optional second parameter specifying the destination. If the second
 # parameter is omitted, the basename of the source repository is used as the
 # destination.
+#
+# OPTIONS
+# -------
+# -s::
+#	Clone in the current directory instead of creating a new one.
+#
+# -h, --help::
+#	Print usage help
+
+USAGE="cg-clone [-s] <location> [<directory>]"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-commit
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-commit  (mode:100755)
+++ uncommitted/cg-commit  (mode:100755)
@@ -4,26 +4,81 @@
 # Copyright (c) Petr Baudis, 2005
 # Based on an example script fragment sent to LKML by Linus Torvalds.
 #
-# Ignores any parameters for now, excepts changelog entry on stdin.
-# -C makes cg-commit ignore cache and just commit the thing as-is;
-# this is for internal purposes (merging).
-# -m"log message" specifies the commit message, which is used instead
-# of starting up an editor (if the input is not stdin, the input is
-# appended after all the -m messages). Multiple -m parameters are
-# appended to a single commit message, each as separate paragraph.
-# -e forces the editor to be brought up even when -m parameters were
-# passed to cg-commit.
-# -E forces the editor to be brought up and it will do the commit
-# even if the default commit message is not changed.
-#
-# These git environment variables are used in case values other than
-# that returned by getpwuid(getuid()) are desired when performing a commit:
-#
-# GIT_AUTHOR_NAME       Author's name
-# GIT_AUTHOR_EMAIL      Author's e-mail address
-# GIT_AUTHOR_DATE       Date, perhaps from a patch e-mail
-# GIT_COMMITTER_NAME    Committer's name
-# GIT_COMMITTER_EMAIL   Committer's e-mail address
+#
+# DESCRIPTION
+# -----------
+# Commits changes to a GIT repository. Accepts the commit message from
+# `stdin`. If the commit message is not modified the commit will be
+# aborted.
+#
+# The `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_AUTHOR_DATE`,
+# `GIT_COMMITTER_NAME` and `GIT_COMMITTER_EMAIL` environment variables
+# are used in case values other than that returned by `getpwuid(getuid())`
+# are desired when performing a commit.
+#
+# OPTIONS
+# -------
+# -C::
+#	Make `cg-commit` ignore the cache and just commit the thing as-is.
+#	Note, this is used internally by Cogito when merging. This option
+#	does not make sense when files are given on the command line.
+#
+# -m<message>::
+#	Specify the commit message, which is used instead of starting
+#	up an editor (if the input is not `stdin`, the input is appended
+#	after all the '-m' messages). Multiple '-m' parameters are appended
+#	to a single commit message, each as separate paragraph.
+#
+# -e::
+#	Force the editor to be brought up even when '-m' parameters were
+#	passed to `cg-commit`.
+#
+# -E::
+#	Force the editor to be brought up and do the commit even if
+#	the default commit message is not changed.
+#
+# -h, --help::
+#	Print usage help.
+#
+# FILES
+# -----
+# $GIT_DIR/commit-template::
+#	If the file exists it will be used as a template when creating
+#	the commit message. The template file makes it possible to
+#	automatically add `Signed-off-by` line to the log message.
+#
+# $GIT_DIR/hooks/commit-post::
+#	If the file exists and is executable it will be executed upon
+#	completion of the commit. The script is passed two arguments.
+#	The first argument is the commit ID and the second is the
+#	branchname. A sample `commit-post` script might look like:
+#
+#	#!/bin/sh
+#	id=$1
+#	branch=$2
+#	echo "Committed $id in $branch" | mail user@host
+#
+# ENVIRONMENT VARIABLES
+# ---------------------
+# GIT_AUTHOR_NAME::
+#	Author's name
+#
+# GIT_AUTHOR_EMAIL::
+#	Author's e-mail address
+#
+# GIT_AUTHOR_DATE::
+#	Date, useful when applying patches an e-mail
+#
+# GIT_COMMITTER_NAME::
+#	Committer's name
+#
+# GIT_COMMITTER_EMAIL::
+#	Committer's e-mail address
+#
+# EDITOR::
+#	The editor used for entering revision log information.
+
+USAGE="cg-commit [-m<message>]... [-e | -E] [<file>]..."
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-diff
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-diff  (mode:100755)
+++ uncommitted/cg-diff  (mode:100755)
@@ -3,18 +3,29 @@
 # Make a diff between two GIT trees.
 # Copyright (c) Petr Baudis, 2005
 #
+# DESCRIPTION
+# -----------
+# Outputs a diff for converting the first tree to the second one.
 # By default compares the current working tree to the state at the
-# last commit. You can specify -r rev1:rev2 or -r rev1 -r rev2 to
-# tell it to make a diff between the specified revisions. If you
-# do not specify a revision, the current working tree is implied
-# (note that no revision is different from empty revision - -r rev:
-# compares between rev and HEAD, while -r rev compares between rev
-# and working tree).
+# last commit.
 #
-# -p instead of one ID denotes a parent commit to the specified ID
-# (which must not be a tree, obviously).
+# OPTIONS
+# -------
+# -p::
+#	Instead of one ID denotes a parent commit to the specified ID
+#	(which must not be a tree, obviously).
 #
-# Outputs a diff converting the first tree to the second one.
+# -r <commit>[:<commit>]::
+#	Specify the revisions to diff using either '-r rev1:rev2' or
+#	'-r rev1 -r rev2'. If no revision is specified, the current
+#	working tree is implied. Note that no revision is different from
+#	empty revision which means '-r rev:' compares between 'rev' and
+#	'HEAD', while '-r rev' compares between 'rev' and working tree.
+#
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-diff [-p] [-r <commit>[:<commit>]] [<file>]..."
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-export
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-export  (mode:100755)
+++ uncommitted/cg-export  (mode:100755)
@@ -3,12 +3,21 @@
 # Exports a particular revision from a GIT repository.
 # Copyright (c) Johannes E. Schindelin, 2005
 #
-# Takes a destination and optionally an id as a parameter,
-# defaulting to HEAD.
+# DESCRIPTION
+# -----------
+# Takes a destination and optionally a tree ID as a parameter,
+# defaulting to 'HEAD'.
 #
-# The destination can be either a .tar, .tar.gz, .tar.bz2 or .tgz
+# The destination can be either a `.tar`, `.tar.gz`, `.tar.bz2` or `.tgz`
 # for generating a tarball. Other destination specifiers are assumed
 # to be directory names, and the tree is exported to the given directory.
+#
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-export <destination> [<tree>]"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-help
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-help  (mode:100755)
+++ uncommitted/cg-help  (mode:100755)
@@ -1,9 +1,24 @@
 #!/usr/bin/env bash
 #
-# The help for the Cogito toolkit.
+# Show help for Cogito commands.
 # Copyright (c) Petr Baudis, 2005
 #
+# DESCRIPTION
+# -----------
 # Takes an optional argument describing the command to show the help for.
+# The command can be specified either as '<command>' or 'cg-<command>'.
+# If the argument is left out an overview of all the Cogito commands will
+# be shown.
+#
+# Note help for a command is also available by passing `--help` or `-h`
+# to the command.
+#
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help
+
+USAGE="cg-help [<command>]"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-init
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-init  (mode:100755)
+++ uncommitted/cg-init  (mode:100755)
@@ -3,10 +3,19 @@
 # Initialize a GIT repository.
 # Copyright (c) Petr Baudis, 2005
 #
+# DESCRIPTION
+# -----------
 # Takes an optional parameter which will make it "clone" a specified
-# remote repository. Note that this usage is DEPRECATED - use cg-clone
-# (possibly with the -s parameter) for doing this. This functionality
-# will go away from cg-init soon.
+# remote repository. Note that this usage is 'DEPRECATED'. Instead use
+# `cg-clone` (possibly with the `-s` parameter) for doing this. This
+# functionality will go away from `cg-init` soon.
+#
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-init"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-log
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-log  (mode:100755)
+++ uncommitted/cg-log  (mode:100755)
@@ -4,26 +4,59 @@
 # Copyright (c) Petr Baudis, 2005.
 # Copyright (c) David Woodhouse, 2005.
 #
-# Takes a -c option to add color to the output.
-# Currently, the colors are:
+# DESCRIPTION
+# -----------
+# Display log information for files or a range of commits. The output
+# will automatically be displayed in a pager unless it is piped to
+# a program.
+#
+# OPTIONS
+# -------
+# Arguments not interpreted as options will be interpreted as filenames;
+# cg-log then displays only changes in those files.
+#
+# -c::
+#	Add color to the output. Currently, the colors are:
+#	- `author`:	'cyan'
+#	- `committer`:	'magenta'
+#	- `header`:	'green'
+#	- `files`:	'blue'
+#	- `signoff`:	'yellow'
+#
+# -f::
+#	List which files changed.
+#
+# -r <commit>[:<commit>]::
+#	Limit the log information to a set of revisions using either
+#	'-r FROM_ID[:TO_ID]' or '-r FROM_ID -r TO_ID'. In both cases the
+#	option expects IDs which resolve to commits and will include the
+#	specified IDs. If 'TO_ID' is omitted all commits from 'FROM_ID'
+#	to the initial commit is shown. If no revisions is specified,
+#	the log information starting from 'HEAD' will be shown.
+#
+# -u<username>::
+#	List only commits where author or committer contains '<username>'.
+#	The search for '<username>' is case-insensitive.
+#
+# -h, --help::
+#	Print usage help.
+#
+# EXAMPLE USAGE
+# -------------
+# To show a log of changes between two releases tagged as 'releasetag-0.9'
+# and 'releasetag-0.10' do:
+#
+#	$ cg-log -r releasetag-0.9:releasetag-0.10
+#
+# ENVIRONMENT VARIABLES
+# ---------------------
+# PAGER::
+#	The pager to display log information in, defaults to `less`.
 #
-#	header		Green	
-#	author 		Cyan
-#	committer	Magenta
-#	files		Blue
-#	signoff		Yellow
-#
-# Takes an -f option to list which files was changed.
-#
-# Takes -u"username" to list only commits where author or
-# committer contains username.
-#
-# Takes an -r followed with id resolving to a commit to start from
-# (HEAD by default), or id1:id2 representing an (id1;id2] range
-# of commits to show.
-#
-# The rest of arguments are took as filenames; cg-log then displays
-# only changes in those files.
+# PAGER_FLAGS::
+#	Flags to pass to the pager, defaults to `--R`
+
+USAGE="cg-log [-c] [-f] [-u<username>] [-r <commit>[:<commit>]] <file>..."
 
 . ${COGITO_LIB}cg-Xlib
 # Try to fix the annoying "Broken pipe" output. May not help, but apparently
Index: cg-ls
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-ls  (mode:100755)
+++ uncommitted/cg-ls  (mode:100755)
@@ -3,7 +3,40 @@
 # List contents of a particular tree in a GIT repository.
 # Copyright (c) Petr Baudis, 2005
 #
-# Optionally takes commit or tree id as a parameter, defaulting to HEAD.
+# DESCRIPTION
+# -----------
+# Optionally takes a commit or tree ID as a parameter, defaulting to
+# 'HEAD'.
+#
+# Each line in the output has the following format:
+#
+#	<mode>	<type>	<sha1>	<name>
+#
+# where
+#
+# '<mode>'::
+#	The file permission information in octal format.
+#
+# '<type>'::
+#	The type can be the following: `blob` refers to files
+#	and `tree` refers to directories.
+#
+# '<sha1>'::
+#	The object ID.
+#
+# '<name>'::
+#	The file or directory name.
+#
+# An example line might look like:
+#
+#	100644  blob    c7dacd0ea28994e3c754ca4eadb2e08c011ee3d3        README
+#
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-ls [<tree>]"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-merge
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-merge  (mode:100755)
+++ uncommitted/cg-merge  (mode:100755)
@@ -3,15 +3,28 @@
 # Merge a branch to the current tree.
 # Copyright (c) Petr Baudis, 2005
 #
+# DESCRIPTION
+# -----------
 # Takes a parameter identifying the branch to be merged.
-# Optional "-b base_commit" parameter specifies the base for the merge.
-# Optional "-c" parameter specifies that you want to have tree merge
-# never autocomitted, but want to review and commit it manually.
 #
-# You have to examine the tree after the merge and then do cg-commit.
+# You have to examine the tree after the merge and then do `cg-commit`.
 #
-# Alternatively, it will just bring the HEAD forward, if your current
-# HEAD is also the merge base.
+# Alternatively, it will just bring the 'HEAD' forward, if your current
+# 'HEAD' is also the merge base.
+#
+# OPTIONS
+# -------
+# -b <commit>::
+#	Parameter specifies the base commit for the merge.
+#
+# -c::
+#	Parameter specifies that you want to have tree merge never
+#	autocomitted, but want to review and commit it manually.
+#
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-merge [-c] [-b <commit>] <branch>"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-mkpatch
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-mkpatch  (mode:100755)
+++ uncommitted/cg-mkpatch  (mode:100755)
@@ -1,14 +1,41 @@
 #!/usr/bin/env bash
 #
-# Make a patch from a given commit.
+# Make a patch from one or several commits.
 # Copyright (c) Petr Baudis, 2005
 #
-# Takes an -s option which specifies whether to print a short
-# version of the patch without a patch header with meta info such
-# as author and committer.
+# DESCRIPTION
+# -----------
+# Generate a patch with diff statistics and meta info about each commit.
 #
-# Takes an -r followed with ID defaulting to HEAD, or id1:id2, forming
-# a range (id1;id2]. (Use "id1:" to take just everything from id1 to HEAD.)
+# OPTIONS
+# -------
+# -s::
+#	Specify whether to print a short version of the patch without
+#	a patch header with meta info such as author and committer.
+#
+# -r <commit>[:<commit>]::
+#	Specify a set of commits to make patches from using either
+#	'-r FROM_ID[:TO_ID]' or '-r FROM_ID -r TO_ID'. In both cases the
+#	option expects IDs which resolve to commits and will include the
+#	specified IDs. If 'TO_ID' is omitted patches for all commits
+#	from 'FROM_ID' to the initial commit will be generated. If no
+#	`-r` option is given the commit ID defaults to 'HEAD'.
+#
+# -h, --help::
+#	Print usage help.
+#
+# EXAMPLE USAGE
+# -------------
+# To make patches for all commits between two releases tagged as
+# 'releasetag-0.9' and 'releasetag-0.10' do:
+#
+#	$ cg-mkpatch -r releasetag-0.9:releasetag-0.10
+#
+# The output will be a contionuos dump of patches each separated by
+# the line
+# `!-------------------------------------------------------------flip-`
+
+USAGE="cg-mkpatch [-s] [-r <commit>[:<commit>]]"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-patch
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-patch  (mode:100755)
+++ uncommitted/cg-patch  (mode:100755)
@@ -1,12 +1,21 @@
 #!/usr/bin/env bash
 #
-# Apply a diff generated by git diff.
+# Apply a diff generated by cg-diff.
 # Copyright (c) Petr Baudis, 2005
 #
+# DESCRIPTION
+# -----------
 # This is basically just a smart patch wrapper. It handles stuff like
 # mode changes, removal of files vs. zero-size files etc.
 #
 # Takes the diff on stdin.
+#
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-patch < patch on stdin"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-pull
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-pull  (mode:100755)
+++ uncommitted/cg-pull  (mode:100755)
@@ -1,11 +1,20 @@
 #!/usr/bin/env bash
 #
-# Pulls changes from remote branch to the local GIT repository.
-# Copyright (c) Petr Baudis, 2005
+# Pull changes from a remote branch to the local GIT repository.
+# Copyright (c) Petr Baudis, 2005.
+#
+# DESCRIPTION
+# -----------
+# Takes the branch name as an argument, defaulting to "origin".
 #
 # See cg-branch-add for some description.
 #
-# Takes the branch' name, defaulting to "origin".
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-pull [<branch>]"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-restore
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-restore  (mode:100755)
+++ uncommitted/cg-restore  (mode:100755)
@@ -1,21 +1,29 @@
 #!/usr/bin/env bash
 #
-# Restores files removed/changed in the working tree.
+# Restore removed/changed files in the working tree.
 # Copyright (c) Petr Baudis, 2005
 #
-# This script restores given files to their original state.
-#
-# Without any parameters, it recovers any files removed locally
-# whose removal was not recorded by cg-rm.
+# DESCRIPTION
+# -----------
+# Restore given files to their original state. Without any parameters,
+# it recovers any files removed locally whose removal was not recorded
+# by `cg-rm`.
 #
 # If passed a set of file names, it restores those files to their
-# state as of the last commit (including bringing cg-rm'd files
-# back to life; FIXME: does not do that part yet).
+# state as of the last commit (including bringing files removed with
+# `cg-rm` back to life; FIXME: does not do that part yet).
 #
-# This command is complementary to the cg-cancel command, which
+# This command is complementary to the `cg-cancel` command, which
 # forcefully abandons all the changes in the working tree and
 # restores everything to a proper state (including unseeking,
 # cancelling merge in progress and rebuilding indexes).
+#
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-restore [<file>]..."
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-rm
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-rm  (mode:100755)
+++ uncommitted/cg-rm  (mode:100755)
@@ -1,10 +1,19 @@
 #!/usr/bin/env bash
 #
-# Remove a file from a GIT repository.
+# Remove files from a GIT repository.
 # Copyright (c) Petr Baudis, 2005
 #
+# DESCRIPTION
+# -----------
 # Takes a list of file names at the command line, and schedules them
 # for removal from the GIT repository at the next commit.
+#
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-rm <file>..."
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-seek
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-seek  (mode:100755)
+++ uncommitted/cg-seek  (mode:100755)
@@ -3,22 +3,30 @@
 # Seek the working tree to a given commit.
 # Copyright (c) Petr Baudis, 2005
 #
-# This will bring the working tree from its current HEAD to a given
-# commit. Note that it changes just the HEAD of the working tree, not
-# the branch it is corresponding to. It will return to the HEAD of
+# DESCRIPTION
+# -----------
+# Takes the target commit ID to seek to as an argument.
+# Seeking will bring the working tree from its current 'HEAD' to a given
+# commit. Note that it changes just the 'HEAD' of the working tree, not
+# the branch it is corresponding to. It will return to the 'HEAD' of
 # the appropriate branch if passed no arguments.
 #
 # Therefore, for a quick excurse to the past of the 'master' branch:
 #
-#	cg-seek git-pasky-0.1
-#	cg-diff this master # will do the correct thing
-#	cg-seek # will restore what we had before
+#	$ cg-seek git-pasky-0.1
+#	$ cg-diff this master	# will do the correct thing
+#	$ cg-seek		# will restore what we had before
 #
-# For intuitiveness, specifying the branch name (cg-seek master) will do
+# For intuitiveness, specifying the branch name (`cg-seek master`) will do
 # the right thing too. If you want to migrate your working tree to another
-# branch, use cg-fork.
+# branch, use `cg-fork`.
 #
-# Takes the target commit ID.
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-seek <commit>"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-status
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-status  (mode:100755)
+++ uncommitted/cg-status  (mode:100755)
@@ -3,7 +3,35 @@
 # Show status of entries in your working tree.
 # Copyright (c) Petr Baudis, 2005
 #
-# Takes no arguments.
+# DESCRIPTION
+# -----------
+# Print of files in the working tree.
+#
+# The output has the following format:
+#
+#	<status flag> <file>
+#
+# where '<status flag>' can be one of the following:
+#
+# `?`::
+#	'<file>' is unknown.
+# `M`::
+#	'<file>' has been touched or modified.
+#
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help.
+#
+# FILES
+# -----
+# $GIT_DIR/exclude::
+#	If the file exists it will be used to prune which files to
+#	show status for. The format is similar to the `dontdiff` file;
+#	each line contains a pattern for a file or group of files
+#	to exclude.
+
+USAGE="cg-status"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-tag
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-tag  (mode:100755)
+++ uncommitted/cg-tag  (mode:100755)
@@ -3,10 +3,19 @@
 # Mark certain commit by a tag.
 # Copyright (c) Petr Baudis, 2005
 #
-# Creates a tag referencing the given commit (or HEAD). You can then
-# use the tag anywhere you specify a commit/tree ID.
+# DESCRIPTION
+# -----------
+# Creates a tag referencing the given commit (or 'HEAD'). You can then
+# use the tag anywhere you specify a commit or tree ID.
 #
-# Takes the tag's name and optionally the associated ID.
+# Takes the tag name and optionally the associated ID as arguments.
+#
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-tag <tag> [<commit>]"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-tag-ls
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-tag-ls  (mode:100755)
+++ uncommitted/cg-tag-ls  (mode:100755)
@@ -3,7 +3,16 @@
 # List stored GIT tags.
 # Copyright (c) Steve Hoelzer 2005
 #
+# DESCRIPTION
+# -----------
 # Takes no parameters.
+#
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-tag-ls"
 
 . ${COGITO_LIB}cg-Xlib
 
Index: cg-update
===================================================================
--- de641904363cd3759f132ee7c0dfaf8a2ee58388/cg-update  (mode:100755)
+++ uncommitted/cg-update  (mode:100755)
@@ -1,9 +1,21 @@
 #!/usr/bin/env bash
 #
-# Pulls changes from another branch to the local repository and merge changes.
+# Pull and merge changes from a branch to the local repository.
 # Copyright (c) Petr Baudis, 2005
 #
-# Takes the branch' name, defaulting to "origin".
+# DESCRIPTION
+# -----------
+# Takes the branch name as an argument, defaulting to 'origin'.
+#
+# If local changes conflict with those of the branch updated from the
+# merge will be blocked.
+#
+# OPTIONS
+# -------
+# -h, --help::
+#	Print usage help.
+
+USAGE="cg-update [<branch>]"
 
 . ${COGITO_LIB}cg-Xlib