docs: Work and tidying

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/docs/advanced.md b/docs/advanced.md
index fedd6f646389c909a8dbe9032d60168f5eecd6ca..43c66c771df3d925b09cd57f32a2803f3cf88841 100644 (file)
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -1,62 +1,3 @@
 Advanced usage
 ==============
 
-Adding pieces to a game in progress
------------------------------------
-
-Using the `otter library-list` and `otter library-add` commands, you can
-add pieces to a game while it is in progress.
-
-You may want to refer to the shape library preview ("Shapelib" link in
-the game UI).
-
-
-Defining your own game
-----------------------
-
-If you want to use existing piece shapes that Otter already knows
-about, you can do this by providing a `<something>.game.toml` file.
-
-The format of these files is a TOML document representing a `GameSpec`
-as found in `src/spec.rs` in the Otter source code.  Unfortunately
-this is not yet documented.
-
-xxx cross ref or delete
-
-
-Adding shapes (pieces, cards, etc.)
------------------------------------
-
-Otter uses SVGs.  The sources for the SVGs are all in the otter source
-tree, in the `library/` directory.
-
-Each shape is listed in one of the `library/*.toml` files, in a
-`files` entry.  (Most of) the syntax and semantics of this file are
-documented in the Rustdoc documentation for the module
-`otter::shapelib_toml`.  If you run `make -j8 shapelib` it will print
-out a `file://` url for these docs.
-
-You can preview the shapes, including any changes you make, without a
-whole game server, by running `make -j8 shapelib`, and looking at
-`templates/shapelib.html`.  As above, this make rune will print the
-`file://` url for you.
-
-See the build instructions for information about how to install the
-tools you will need.
-
-Some of these SVGs were scraped from Wikimedia.  The scraper machinery
-can perhaps be adapted to scrape SVGs from elsewhere.
-
-You can also add your own SVGs in the `library/edited/` directory.  If
-you do that, please make sure to include the actual source code there
-too.  If you copied or adapted an SVG from somewhere, note the details
-of where you got it (eg, in a git commit message).
-
-Contributions should be via git branch, eg a merge request on Salsa:
-[https://salsa.debian.org/iwj/otter](https://salsa.debian.org/iwj/otter)
-
-NB that shapes must come with a licence compatible with CC-BY-SA 4.0
-or GNU AGPLv3+.  See `LICENCE` for more information about copyright status.
-
-
-xxx cross ref or delete

diff --git a/docs/bundles.rst b/docs/bundles.rst
index 67a632f2c422a8ed97fd7c09e6eab7db60cc5ede..36825059282001effd57116367b44b4bf2b6ab41 100644 (file)
--- a/docs/bundles.rst
+++ b/docs/bundles.rst
@@ -12,9 +12,9 @@ on the ``otter reset`` command line:
 
 ::
 
-  otter--game unix:myself:: reset stoat-fest stoaty-games.zip
-             /^^^^^^^^^^^^^      /^^^^^^^^^^ ^^^^^^^^^^^^^^^^\
-    game (instance) name     game spec name       bundle file'
+  otter --game unix:myself:: reset stoat-fest stoaty-games.zip
+              /^^^^^^^^^^^^^      /^^^^^^^^^^ ^^^^^^^^^^^^^^^^\
+     game (instance) name     game spec name       bundle file'
 
 The zipfile will be uploaded the server, and then Otter will look for
 the game spec ``stoat-fest`` amongst its builtin games and also in the

diff --git a/docs/dev.md b/docs/dev.md
index f8112e77ba9143cd0c40f71f9fe672e1017751f2..c9d73d6e1b13dd494b2b7b25a22a6567f97be2d3 100644 (file)
--- a/docs/dev.md
+++ b/docs/dev.md
@@ -69,6 +69,43 @@ Deleting the stamp files is not needed if you simply edit Rust source
 files.
 
 
+Adding shapes (pieces, cards, etc.) to the builtin library
+----------------------------------------------------------
+
+(Consider defining an uploadable game bundle instead.)
+
+Otter's builtin shape libraries use SVGs.  The sources for the SVGs
+are all in the otter source tree, in the `library/` directory.
+
+Each shape is listed in one of the ``library/*.toml`` files, in a
+`files` entry.  (Most of) the syntax and semantics of this file are
+documented in the Rustdoc documentation for the module
+`otter::shapelib_toml`.  If you run `make -j8 shapelib` it will print
+out a `file://` url for these docs.
+
+You can preview the shapes, including any changes you make, without a
+whole game server, by running `make -j8 shapelib`, and looking at
+`templates/shapelib.html`.  As above, this make rune will print the
+`file://` url for you.
+
+See the build instructions for information about how to install the
+tools you will need.
+
+Some of these SVGs were scraped from Wikimedia.  The scraper machinery
+can perhaps be adapted to scrape SVGs from elsewhere.
+
+You can also add your own SVGs in the `library/edited/` directory.  If
+you do that, please make sure to include the actual source code there
+too.  If you copied or adapted an SVG from somewhere, note the details
+of where you got it (eg, in a git commit message).
+
+Contributions should be via git branch, eg a merge request on Salsa:
+[https://salsa.debian.org/iwj/otter](https://salsa.debian.org/iwj/otter)
+
+NB that shapes must come with a licence compatible with CC-BY-SA 4.0
+or GNU AGPLv3+.  See `LICENCE` for more information about copyright status.
+
+
 Navigating the otter source code
 --------------------------------
 

diff --git a/docs/user.rst b/docs/user.rst
index 0b56b6d321103c98e3951f4baa00a53bcd75c91a..2004966138b6e74174927b8fccb680fe05b217ff 100644 (file)
--- a/docs/user.rst
+++ b/docs/user.rst
@@ -145,6 +145,19 @@ trouble with your network or web browser.  The state is all on the
 server, so you can reload or reconnect whenever you like.
 
 
+Adding pieces to a game in progress
+-----------------------------------
+
+Using the `otter library-list` and `otter library-add` commands, you can
+add pieces to a game while it is in progress.
+
+Currently only shape library pieces (builtin, or from bundles) can be
+added this way.
+
+You may want to refer to the builtin shape library preview ("Shapelib"
+link in the game UI).
+
+
 Game administration
 -------------------
 
@@ -183,3 +196,14 @@ for a different game) with something like this:
 The ``otter`` command line tool has further subcommands for
 adding/removing players, for ad-hoc addition of pieces from the
 library to an existing game, and so on.
+
+
+Defining your own game
+``````````````````````
+
+If you want to use existing piece shapes that Otter already knows
+about, you can do this by providing a ``GAME.game.toml`` file,
+in :doc:`Game Spec <gamespec>` format.
+
+You can also define your own shapes by providing a :doc:`bundle
+<bundles>`.