Use README.md for manual intro (initial working version)

README.md

@@ -2,23 +2,52 @@
 
 * Website: code.studioinfinity.org/RAQ/wiki
 * Repository: code.studioinfinity.org/RAQ
-
+* Authors/maintainers of RAQ: Glen Whitney <glen@studioinfinity.org>
-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.
 
 <!--
-#! @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 -->