From 44c71ef05fdcbc3c392073cb19fd3f2c3063eddb Mon Sep 17 00:00:00 2001
From: Glen Whitney <gwhitney@post.harvard.edu>
Date: Sat, 18 Aug 2018 23:48:21 -0700
Subject: [PATCH] Use README.md for manual intro (initial working version)

---
 README.md | 51 ++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 40 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 1c10f38..afffa83 100644
--- a/README.md
+++ b/README.md
@@ -2,23 +2,52 @@
 
 * Website: code.studioinfinity.org/RAQ/wiki
 * Repository: code.studioinfinity.org/RAQ
-
-This package provides a variety of facilities for computing with one-sided
-quasigroups, racks, and quandles in GAP.
-
-It uses no external binaries, so installation consists only of placing the RAQ
-file tree in a directory in your package search path, e.g. the pkg directory of
-your GAP installation, or perhaps the .gap/pkg subdirectory of your home
-directory.
+* Authors/maintainers of RAQ: Glen Whitney <glen@studioinfinity.org>
 
 <!--
-#! @Acknowledgements
+#! @Chapter Introduction
 #! @AutoDocPlainText -->
+The RAQ package provides a variety of facilities for constructing and
+computing with one-sided quasigroups, racks, and quandles in GAP.
+
+<!--@Section Installation
+@AutoDocPlainText -->
+RAQ uses no external binaries, so installation consists only of placing its
+unpacked file tree in a directory in your package search path, e.g. the pkg
+directory of your GAP installation, or perhaps the .gap/pkg subdirectory of
+your home directory.
+
+<!--@Acknowledgements
+@AutoDocPlainText -->
 The authors of RAQ would like to acknowledge their debt to the creators of
 RIG, an earlier package for Racks in GAP; chief among them is Leandro
 Vendramin.  RIG was an inspiration for the creation of RAQ, and using and
 reading that package suggested many features needed in the development of
 RAQ.
-<!--@EndAutoDocPlainText -->
 
-Authors/maintainers of RAQ: Glen Whitney <glen@studioinfinity.org>
+<--@Chapter Introduction
+@Section A first spin
+@AutoDocPlainText -->
+Perhaps the following GAP interactive session, which constructs the
+conjugation quandle of the symmetric group on three elements and then performs
+a few simple computations on that quandle, will give the flavor of RAQ. (It is
+presumed that the RAQ package has already been loaded with
+`LoadPackage("RAQ");` prior to these example commands being executed.)
+
+<--@BeginExampleSession -->```
+gap> S3 := SymmetricGroup(3);
+Sym( [ 1 .. 3 ] )
+gap> Elements(S3);
+[ (), (2,3), (1,2), (1,2,3), (1,3,2), (1,3) ]
+gap> Q3 := ConjugationQuandle(S3);
+<left quandle with 6 generators>
+gap> elt := Elements(Q3); # the element ^p: below means conjugation by p in S3 
+[ ^():, ^(2,3):, ^(1,2):, ^(1,2,3):, ^(1,3,2):, ^(1,3): ]
+gap> elt[4]*elt[3]; # So this will produce (1,2,3)^{-1}(1,2)(1,2,3)
+^(2,3):
+```<!--@EndExampleSession -->
+Note in particular that RAQ generally, unless otherwise specifically
+requested, produces __left__ quandles and racks. (That is to say, quandles in
+which for any fixed element $l$, the "left-multiplication by $l$" operation
+$x\mapsto l*x$ is a permutation of the quandle.)
+<--@EndAutoDocPlainText -->