Flesh out the tutorial a bit

1 files changed, 103 insertions, 0 deletions

diff --git a/TUTORIAL b/TUTORIAL
index 2d5f0da..1fea069 100644
--- a/TUTORIAL
+++ b/TUTORIAL
@@ -4,6 +4,7 @@ distix tutorial
 distix is a distributed ticketing system. This is a tutorial for the
 command line interface.
 
+
 Initialise a new ticket repository: `distix init`
 -------------------------------------------------
 
@@ -32,3 +33,105 @@ computers.
 `repo.yaml` contains some metadata about the repository itself. Most
 importantly, it contains the description of the repository you gave
 `init`.
+
+
+Create a new ticket: `distix new`
+---------------------------------
+
+To create a new ticket, run a command like this:
+
+    distix new "This is the title of my new ticket"
+
+If all goes well, distix will create a new ticket. The ticket will
+have a universally unique identifier (UUID), which is a random 128-bit
+number. The ticket will be stored in the directory
+`tickets/0234e10813ca44438510c37a7b61abb2`, where
+`0234e10813ca44438510c37a7b61abb2` is the hexadecimal representation
+of the UUID.
+
+You can use the following command to list all tickets:
+
+    distix list
+
+This will produce output like the following:
+
+    24e885d6e463441baf0fcd76626afa1a distix doesn't invoke editor
+    468a9c8545604ce18f1e381fae5e8bac bottle templates are embedded in code
+    49001e5d68c649b9886e35513eb24b55 distix lacks a manual page
+    8268e49d83ea43a6a362281603d8a7f3 distix show doesn't show the headers of messages
+    0234e10813ca44438510c37a7b61abb2 distix home page is useless
+
+Each line shows the UUID of the ticket and its title.
+
+Writing long UUIDs is somewhat tedious. Remembering them is also not
+always easy for humans. distix will, later, allow easier ways to refer
+to tickets.
+
+
+Looking at tickets: `distix show`
+---------------------------------
+
+To look at a specific ticket, give a command like this:
+
+    $ distix show 0234e10813ca44438510c37a7b61abb2
+    0234e10813ca44438510c37a7b61abb2: distix home page is useless
+
+    * ticket-id: 0234e10813ca44438510c37a7b61abb2
+    * title: distix home page is useless
+
+    $ 
+
+This shows the ticket id, and title, and all the key/value metadata
+for the ticket. The ticket id and title are stored as key/value pairs,
+so the get repeated. (This repetition is not there to make it easier
+to learn the id by heart. Honest.)
+
+
+Setting ticket metadata: `distix set`
+-------------------------------------
+
+Each ticket has some key/value pairs. These allow distix to manage
+ticket metadata. You can add any pairs you like.
+
+    $ distix set 0234e10813ca44438510c37a7b61abb2 status=triaged
+    $ distix show 0234e10813ca44438510c37a7b61abb2
+    0234e10813ca44438510c37a7b61abb2: distix home page is useless
+
+    * status: triaged
+    * ticket-id: 0234e10813ca44438510c37a7b61abb2
+    * title: distix home page is useless
+
+    $ 
+
+Here we added a key `status` with the value `triaged` to the ticket.
+
+distix will interpret some keys in its own way, but ignores all other
+keys. The keys it cares about are, at this time:
+
+* `ticket-id`: the UUID of the ticket; you should not change this
+* `title`: the ticket title; you may change this if you like
+
+
+Replying to a ticket: `distix reply`
+------------------------------------
+
+To add a reply to a ticket:
+
+    distix reply 0234e10813ca44438510c37a7b61abb2 --message="Yay!"
+    
+distix will create a new e-mail and put it in the `Maildir` folder
+in the ticket's directory. `distix show` will show the message, and
+you can look at the folder directly with any e-mail program you like
+that can handle Maildir folders (mutt recommended). However, if you
+change anything in the folder, you should either undo the changes or
+commit them with git. (distix will later make this easier. It's very
+early days in the life of the program.)
+
+
+More?
+-----
+
+That's all distix can do right now. This tutorial should, however,
+cover more things, such as using git to synchronise, share, and merge
+ticket repositories between computers and people. That will be added
+once someone figures out a good way to do that.