From: Ian Jackson Date: Sun, 23 May 2021 14:36:30 +0000 (+0100) Subject: docs: Work and tidying X-Git-Tag: otter-0.6.0~12 X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=9904134a57be6cff718d8a0a677389d18d22bbb7;p=otter.git docs: Work and tidying Signed-off-by: Ian Jackson --- diff --git a/docs/advanced.md b/docs/advanced.md index fedd6f64..43c66c77 100644 --- 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 `.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 67a632f2..36825059 100644 --- 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 f8112e77..c9d73d6e 100644 --- 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 0b56b6d3..20049661 100644 --- 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 ` format. + +You can also define your own shapes by providing a :doc:`bundle +`.