Split out documentation

Move the documentation from a giant comment at the start of the file
into a separate asciidoc document. Among other revisions an
'EXAMPLE SESSION' section is added to give a sense of the normal
workflow.

Add a Makefile and asciidoc.conf for converting the asciidoc into HTML
or a man page.

5 files changed, 396 insertions, 201 deletions

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..f5323c0
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,2 @@
+git-bz.1
+git-bz.html
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..45576f6
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,14 @@
+%.xml: %.txt
+	asciidoc -f asciidoc.conf -d manpage -b docbook $<
+
+%.html: %.txt
+	asciidoc -f asciidoc.conf -d manpage $<
+
+%.1: %.xml
+	xmlto man $<
+
+upload-html: git-bz.html
+	DEST=`git config local.upload-html-dest` ; \
+	if [ $$? = 0 ] ; then : ; else echo "upload location not configured" ; exit 1 ; fi ; \
+	scp $< $$DEST
+
diff --git a/asciidoc.conf b/asciidoc.conf
new file mode 100644
index 0000000..258607e
--- /dev/null
+++ b/asciidoc.conf
@@ -0,0 +1,18 @@
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">Git Bz</refmiscinfo>
+<refmiscinfo class="version"></refmiscinfo>
+<refmiscinfo class="manual">Git Bz Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+  <refname>{manname}</refname>
+  <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
diff --git a/git-bz b/git-bz
index 6a9315d..c76757d 100755
--- a/git-bz
+++ b/git-bz
@@ -26,207 +26,10 @@
 # ============
 # Copy or symlink somewhere in your path.
 #
-# Usage
-# =====
-#
-#  git bz add-url [options] <bug reference> [<commit> | <revision range>]
-#
-#    For each specified commit, rewrite the commit message to add a reference
-#    to the given bug. You should only do this if you haven't already pushed
-#    the commit publically. You won't need this very often, since
-#    'git bz file' and 'git bz attach' do this automaticlaly.
-#
-#    If the bug number is already found in the commit message, then does nothing.
-#
-#    Example:
-#
-#       # Add a bug URL to the last commit
-#       git bz attach 1234 HEAD
-#
-#    The default behavior is to append the bug URL to the commit body. See the
-#    section 'Add URL Method' below for how to change this.
-#
-#  git bz apply [options] <bug reference>
-#
-#    For each patch attachment (except for obsolete patches) of the specified
-#    bug, prompts whether to apply. If prompt is agreed to runs 'git am' on
-#    the patch to apply it to the current branch. Aborts if 'git am' fails to
-#    allow cleaning up conflicts.
-#
-#    Examples:
-#
-#       # Apply patches from the given bug
-#       git bz apply bugzillla.gnome.org:1234
-#
-#       # Same, but add the bug URL to the commit messages
-#       git bz apply -u bugzillla.gnome.org:1234
-#
-#  git bz attach [options] <bug reference> [<commit> | <revision range>]
-#
-#    For each specified commit, formats as a patch and attaches to the
-#    specified bug, with the subject of the commit as the description and
-#    the body of the commit as the comment. The patch formatting is as
-#    for 'git format-patch'. Unlike 'git format-patch', specifying a single
-#    commit means just that commit, not everything after that commit.
-#
-#    Prompts before actually doing anything to avoid mistakes.
-#
-#    If -e/--edit is specified, then the user can edit the description and
-#    comment for each patch, and (by uncommenting lines) obsolete old patches.
-#
-#    The commit message will automatically be rewritten to include a reference
-#    to the bug (see 'git bz add-url'). This can be suppressed with the
-#    -n/--no-add-url option.
-#
-#    Examples:
-#
-#       # Attach the last commit
-#       git bz attach bugzilla.gnome.org:1234 HEAD
-#
-#       # Attach everything starting at an old commit
-#       git bz attach bugzilla.gnome.org:1234 b50ea9bd^..
-#
-#  git bz edit [<bug reference> | <commit> | <revision range>]
-#
-#     Allows doing common operations on a Bugzilla bug without going to
-#     your web browser. An editable buffer is brought up in a git-like
-#     fashion, where you can add comments, resolve a bug, and change
-#     the status of patches.
-#
-#     If the argument identifies a commit or commits rather than a bug
-#     then each bug referred to in the commits is edited in turn.
-#
-#     If -p/--pushed is specified, then git-bz will attempt to automatically
-#     determine the correct comments, attachment changes, and resolution
-#     for the bug from applying the specified commits to the project's
-#     official repository. You'll have a chance to edit these changes and
-#     add additional comments. See 'git bz push' for a convenient interface
-#     to push commits and do this at the same time.
-#
-#  git bz file [options] [[<product>]/<component>] [<commit> | <revision range>]
-#
-#     Like 'attach', but files a new bug. Opens an editor for the user to
-#     enter the summary and description for the bug. If only a single commit
-#     is named, the summary defaults to the subject of the commit. The product and
-#     component must be specified unless you have configured defaults.
-#
-#    The commit message will automatically be rewritten to include a reference to
-#    the newly filed bug (see 'git bz add-url') before attaching the patch. This
-#    can be suppressed with the -n/--no-add-url option.
-#
-#     Examples:
-#
-#       # File the last commit as a new bug on the default tracker
-#       git bz file my-product/some-component HEAD
-#
-#       # File a bug with a series of patches starting from an old commit
-#       # on a different bug tracker
-#       git bz -b bugs.freedesktop.org file my-product/some-component b50ea9bd^..
-#
-#  git bz push [options] [<repository> <refspec>...]
-#
-#     Exactly like 'git push', but 'git bz edit --pushed' is done for each
-#     bug referenced in the newly pushed commits.
-#
-#     Note that "newly pushed commits" are commits that were added to any
-#     existing branch by the push. Commits don't have to be pushed to master
-#     to be considered newly pushed. However, commits pushed to on newly
-#     created branches will be ignored.
-#
-# Authentication
-# ==============
-# In order to use git-bz you need to already be logged into the bug tracker
-# in your web browser, and git-bz reads your browser cookie. Currently only
-# Firefox 3 and Epiphany are supported, and only on Linux. Patches to
-# add more support and to allow configuring username/password directly
-# per bug tracker accepted.
-#
-# Bug references
-# ==============
-# Ways to refer to a bug:
-#  <id>         : bug # on the default bug tracker
-#  <host>:<id>  : bug # on the given host
-#  <alias>:<id> : bug # on the given bug tracker alias (see below)
-#  <url>        : An URL of the form http://<hostname>/show_bug.cgi?id=<id>
-#
-# Add URL Method
-# ==============
-# You can configure 'git bz add-url', and the --add-url option of 'git
-# bz [apply|attach|file]' to add the URL different ways or to add a
-# non-URL bug reference, using the git config variable
-# 'bz.add-url-method'.
-#
-# It has the form
-#
-#  <method>:<format>
-#
-# Method is:
-#   subject-prepend - prepend to the subject (separated with a space)
-#   subject-append  - apend to the subject (separated with a space)
-#   body-prepend    - prepend to the body (separated with a blank line)
-#   body-append     - append to the body (separated with a blank line)
-#
-# Format supports the following escapes:
-#   %u - the bug URL
-#   %d - the bug #
-#   %n - a newline
-#   %% - a percent
-#
-# Examples:
-#   # The default
-#   git config bz.add-url-method body-append:%u
-#   # 'Bug 34323 - Speed up frobnification'
-#   git config bz.add-url-method subject-prepend:Bug %d -
-#
-# Aliases
-# =======
-# You can create short aliases for different bug trackers as follows
-#
-#   git config --global bz-tracker.gnome.host bugzilla.gnome.org
-#
-# And you can set the default bug tracker with:
-#
-#   git config --global bz.default-tracker gnome
-#
-# Per-Repository configuration
-# ============================
-# Setting the default tracker, product and component in the local
-# config for a repository is useful. Assuming that a global
-# 'gnome' alias has been set up as above:
-#
-#   git config bz.default-tracker gnome
-#   git config bz.default-product gnome-shell
-#   git config bz.default-component general
-#
-# Note the absence of --global; configuring a default product and component
-# globally is seldom useful.
-#
-# Per-Tracker Configuration
-# =========================
-# git-bz needs some configuration specific to the bugzilla instance (tracker),
-# in particular it needs to know initial field values to use when submitting
-# bugs; legal values for some fields depend on the instance.
-#
-# You can also set whether to use http or https by setting the 'https' variabe
-# For https, *certificates are not checked* so you are completely vulnerable
-# to DNS spoofing and man-in-the-middle attacks. Blame httplib.
-#
-# Configuration comes from 4 sources, in descending order of priority
-#
-# 1) git configuration variables specified for the alias.
-#
-#    git config --global bz-tracker.gnome.default-severity trivial
-#
-# 2) git configuration variables specified for the host
-#
-#    git config --global bz-tracker.bugzilla.gnome.org.default-severity trivial
-#
-# 3) Host specific configuration in this file, see the CONFIG variable below
-#
-# 4) Default configuration in this file, see the DEFAULT_CONFIG variable below
-#
-# In general, settings that are necessary to make a popular bugzilla instance
-# work should be submitted back to me and go in the CONFIG variable.
+# Documentation
+# =============
+# See http://git.fishsoup.net/man/git-bz.html
+# (generated from git-bz.txt in this directory.)
 #
 DEFAULT_CONFIG = \
 """
diff --git a/git-bz.txt b/git-bz.txt
new file mode 100644
index 0000000..3db24e8
--- /dev/null
+++ b/git-bz.txt
@@ -0,0 +1,358 @@
+git-bz(1)
+=========
+
+NAME
+----
+git-bz - Command line integration of git with Bugzilla
+
+SYNOPSIS
+--------
+[verse]
+'git bz add-url' <bug reference> (<commit> | <revision range>)
+'git bz apply' [-n | --no-add-url] <bug reference>
+'git bz attach' [-n | --no-add-url] [-e |--edit] [<bug reference>] (<commit> | <revision range>)
+'git bz edit' (<bug reference> | <commit> | <revision range>)
+'git bz edit' --pushed (<commit> | <revision range>)
+'git bz file' [-n | --no-add-url] [[<product>]/<component>] (<commit> | <revision range>)
+'git bz push' [<repository> <refspec>...]
+
+DESCRIPTION
+------------
+
+git-bz is a tool for integrating the Git command line with the
+Bugzilla bug-tracking system. Operations such as attaching patches to bugs,
+applying patches in bugs to your current tree, and closing bugs once
+you've pushed the fixes publically can be done completely from the
+command line without having to go to your web browser.
+
+Authentication for git-bz is done by reading the cookies for the
+Bugzilla host from your web browser. In order to do this, git-bz needs
+to know how to access the cookies for your web browser; git-bz
+currently is able to do this for Firefox, Epiphany, and Chromium on
+Linux.
+
+EXAMPLE SESSION
+---------------
+
+Before getting started, you configure the default Bugzilla instance, product and
+component for your repository:
+
+----------------------------------------
+git config bz.default-tracker bugzilla.example.com
+git config bz.default-product TiddlyWinks
+git config bz.default-component AI-Engine
+----------------------------------------
+
+Someone has found a bug in your code, and filed bug 43215 in
+bugzilla.example.com. You've come up with a fix for that patch
+locally, but you want the bug reporter to test it, so you attach the change
+you made locally to the bug report as a patch:
+
+----------------------------------------
+git bz attach 43215 HEAD
+----------------------------------------
+
+This automatically rewrites the commit to add the URL of the bug to the commit for
+future reference. The reporter finds some problems in testing, so you come up
+with a new up with a new version of the change and modify your commit using
+'git command --amend'. To attach the new version, you run:
+
+----------------------------------------
+git bz attach -e HEAD
+----------------------------------------
+
+You don't have to specify the bug number this time since git-bz will
+find it it in the bug. The -e option (short for --edit) allows you to
+edit the comment for the bug to say what you've changed and pick
+patches to obsolete. Now everybody's happy with the change. To push
+your changes and close the bug, you run:
+
+----------------------------------------
+git bz push
+----------------------------------------
+
+This does 'git bz push', adds a comment that the commits were pushed and
+marks the patches committed. The changes it is making to the bug will be
+shown in your editor to give you a chance to confirm them and add
+extra comments if desired.
+
+Other useful commands are 'git bz file' to file a new bug rather than
+attaching patches to an existing one, 'git bz apply' to apply patches from
+a bug to the current tree, and 'git bz edit' to add comments to or
+close bug reports.
+
+COMMON OPTIONS
+--------------
+
+-b;;
+--bugzilla;;
+	Bug tracker to use. Used for 'git bz file' and to resolve bug references.
+	Generally, it's more useful to configure this with 'git config' instead.
+	See the section <<per-repository-configuration, ``Per-Repository Configuration''>>.
+
+-u;;
+--add-url;;
+	Rewrite commits to add the bug URL. (This is the default and will not normally
+	need to be specified.)
+
+-n;;
+--no-add-url;;
+	Don't rewrite commits to add the bug URL
+
+COMMANDS
+--------
+
+add-url
+~~~~~~~
+
+'git bz add-url' <bug reference> (<commit> | <revision range>)
+
+For each specified commit, rewrite the commit message to add a
+reference to the given bug. You should only do this if you haven't
+already pushed the commit publically. You won't need this very often,
+since 'git bz file' and 'git bz attach' do this automatically. It
+might be useful if you want to record the bug information but don't
+want to attach it immediately.
+
+If the bug number is already found in the commit message, then does nothing.
+
+Example:
+
+----------------------------------------
+# Add a bug URL to the last commit
+git bz attach 1234 HEAD
+----------------------------------------
+
+The default behavior is to append the bug URL to the commit body. See the
+section <<add-url-method, ``Add URL Method''>> below for how to change this.
+
+apply
+~~~~~
+
+'git bz apply' [-n | --no-add-url] <bug reference>
+
+For each patch attachment (except for obsolete patches) of the specified
+bug, prompts whether to apply. If prompt is agreed to runs 'git am' on
+the patch to apply it to the current branch. Aborts if 'git am' fails to
+allow cleaning up conflicts.
+
+Examples:
+
+----------------------------------------
+# Apply patches from the given bug
+git bz apply bugzillla.gnome.org:1234
+----------------------------------------
+
+The commit messages will automatically be rewritten to include a
+reference to the bug (see 'git bz add-url'). This can be suppressed
+with the -n/--no-add-url option.
+
+attach
+~~~~~~
+
+'git bz attach' [-n | --no-add-url] [-e |--edit] <bug reference> [<commit> | <revision range>]
+
+For each specified commit, formats as a patch and attaches to the
+specified bug, with the subject of the commit as the description and
+the body of the commit as the comment. The patch formatting is as
+for 'git format-patch'. Unlike 'git format-patch', specifying a single
+commit means just that commit, not everything after that commit.
+
+Prompts before actually doing anything to avoid mistakes.
+
+The commit message will automatically be rewritten to include a reference
+to the bug (see 'git bz add-url'). This can be suppressed with the
+-n/--no-add-url option.
+
+-e;;
+--edit;;
+	allow the user to edit the description and comment for each patch,
+	and (by uncommenting lines) obsolete old patches.
+
+Examples:
+----------------------------------------
+# Attach the last commit
+git bz attach bugzilla.gnome.org:1234 HEAD
+
+# Attach everything starting at an old commit
+git bz attach bugzilla.gnome.org:1234 b50ea9bd^..
+----------------------------------------
+
+edit
+~~~~
+
+'git bz edit' (<bug reference> | <commit> | <revision range>)
+'git bz edit' --pushed (<commit> | <revision range>)
+
+Allows doing common operations on a Bugzilla bug without going to
+your web browser. An editable buffer is brought up in a git-like
+fashion, where you can add comments, resolve a bug, and change
+the status of patches.
+
+If the argument identifies a commit or commits rather than a bug
+then each bug referred to in the commits is edited in turn.
+
+-p;;
+--pushed;;
+	Attempt to automatically determine the correct comments, attachment
+	changes, and resolution for the bug from applying the specified commits
+	to the project's official repository. You'll have a chance to edit these
+	changes and add additional comments. See 'git bz push' for a convenient
+	interface to push commits and do this at the same time.
+
+file
+~~~~
+
+'git bz file' [-n | --no-add-url] [[<product>]/<component>] (<commit> | <revision range>)
+
+Like 'attach', but files a new bug. Opens an editor for the user to
+enter the summary and description for the bug. If only a single commit
+is named, the summary defaults to the subject of the commit. The product and
+component must be specified unless you have configured defaults.
+
+The commit message will automatically be rewritten to include a reference to
+the newly filed bug (see 'git bz add-url') before attaching the patch. This
+can be suppressed with the -n/--no-add-url option.
+
+Examples:
+
+----------------------------------------
+# File the last commit as a new bug on the default tracker
+git bz file my-product/some-component HEAD
+
+# File a bug with a series of patches starting from an old commit
+# on a different bug tracker
+git bz -b bugs.freedesktop.org file my-product/some-component b50ea9bd^..
+----------------------------------------
+
+push
+~~~~
+
+'git bz push' [<repository> <refspec>...]
+
+Exactly like 'git push', but 'git bz edit --pushed' is done for each
+bug referenced in the newly pushed commits.
+
+Note that ``newly pushed commit'' are commits that were added to any
+existing branch by the push. Commits don't have to be pushed to master
+to be considered newly pushed. However, commits pushed to on newly
+created branches will be ignored.
+
+AUTHENTICATION
+--------------
+In order to use git-bz you need to already be logged into the bug tracker
+in your web browser, and git-bz reads your browser cookie. Currently only
+Firefox 3 and Epiphany are supported, and only on Linux. Patches to
+add more support and to allow configuring username/password directly
+per bug tracker accepted.
+
+BUG REFERENCES
+--------------
+Ways to refer to a bug:
+
+<id>:: bug # on the default bug tracker
+
+<host>:<id>:: bug # on the given host
+
+<alias>:<id>:: bug # on the given bug tracker alias (see below)
+
+<url>:: An URL of the form http://<hostname>/show_bug.cgi?id-<id>
+
+[[add-url-method]]
+ADD URL METHOD
+--------------
+You can configure 'git bz add-url', and the --add-url option of 'git
+bz [apply|attach|file]' to add the URL different ways or to add a
+non-URL bug reference, using the git config variable
++bz.add-url-method+.
+
+It has the form
+
+ <method>:<format>
+
+Method is:
+
+subject-prepend:: prepend to the subject (separated with a space)
+subject-append::  append to the subject (separated with a space)
+body-prepend::    prepend to the body (separated with a blank line)
+body-append::     append to the body (separated with a blank line)
+
+Format supports the following escapes:
+
+%u:: the bug URL
+%d:: the bug #
+%n:: a newline
+%%:: a percent
+
+----------------------------------------
+# The default
+git config bz.add-url-method body-append:%u
+# 'Bug 34323 - Speed up frobnification'
+git config bz.add-url-method subject-prepend:Bug %d -
+----------------------------------------
+
+ALIASES
+-------
+You can create short aliases for different bug trackers as follows
+
+----------------------------------------
+git config --global bz-tracker.gnome.host bugzilla.gnome.org
+----------------------------------------
+
+And you can set the default bug tracker with:
+
+----------------------------------------
+git config --global bz.default-tracker gnome
+----------------------------------------
+
+[[per-repository-configuration]]
+PER-REPOSITORY CONFIGURATION
+----------------------------
+Setting the default tracker, product and component in the local
+config for a repository is useful. Assuming that a global
+'gnome' alias has been set up as above:
+
+----------------------------------------
+git config bz.default-tracker gnome
+git config bz.default-product gnome-shell
+git config bz.default-component general
+----------------------------------------
+
+Note the absence of --global; configuring a default product and component
+globally is seldom useful.
+
+PER-TRACKER CONFIGURATION
+-------------------------
+git-bz needs some configuration specific to the bugzilla instance (tracker),
+in particular it needs to know initial field values to use when submitting
+bugs; legal values for some fields depend on the instance.
+
+You can also set whether to use http or https by setting the 'https' variabe
+For https, *certificates are not checked* so you are completely vulnerable
+to DNS spoofing and man-in-the-middle attacks. Blame httplib.
+
+Configuration comes from 4 sources, in descending order of priority
+
+1. git configuration variables specified for the alias.
++
+----------------------------------------
+git config --global bz-tracker.gnome.default-severity trivial
+----------------------------------------
++
+2. git configuration variables specified for the host
++
+----------------------------------------
+git config --global bz-tracker.bugzilla.gnome.org.default-severity trivial
+----------------------------------------
++
+3. Host specific configuration in the git-bz script, see the CONFIG variable.
++
+4. Default configuration in the git-bz script, see the DEFAULT_CONFIG variable.
+
+In general, settings that are necessary to make a popular bugzilla instance
+work should be submitted back to me and go in the CONFIG variable.
+
+Author
+------
+Written by Owen Taylor <otaylor@fishsoup.net>.
+