From 46045a71dfdfcbac1607b114cedf4cb26c36f28b Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Thu, 8 Apr 2021 20:32:59 +0100 Subject: [PATCH] docs: much work Signed-off-by: Ian Jackson --- README.md | 13 +++++----- docs/advanced.md | 13 ++++++---- docs/build.rst | 6 +++++ docs/dev.md | 37 ++++++++-------------------- docs/index.rst | 1 + docs/install.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/user.md | 10 ++++---- 7 files changed, 101 insertions(+), 43 deletions(-) create mode 100644 docs/install.md diff --git a/README.md b/README.md index e7fe5c47..01e42392 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ does it need to know) the rules of the game you are playing. Instead, it lets you and your friends play with common tabletop/boardgame elements such as hands of cards, boards, and so on. -So it's something like a "tabletop simulater" (but it does not have +So it's something like a "tabletop simulator" (but it does not have any 3D, or a physics engine, or anything like that). This means that with Otter: @@ -20,7 +20,7 @@ This means that with Otter: * If Otter already has the necessarily game elements (cards, say) all you need to do is write a spec file saying what should be on the table at the start of the game. For example, most Whist variants - that start with a standard pack of 52 cards are already playble. + that start with a standard pack of 52 cards are already playable. * You can play games where the rules change as the game goes along, or are made up by the players, or are too complicated to write as a @@ -109,11 +109,12 @@ tyranny of programmers `:-)`. I would love contributions, particularly to address the limitations I mention above, and to improve the user experience. -I am also working to make it possible to let you define your own games -(including your own pieces, cards, boards, and so on) without having -to install them on the server. +I am also working to make it possible to let users define their own +games (including thier own pieces, cards, boards, and so on) without +having to install them on the server. The Otter software project is hosted on Debian's GitLab, at - https://salsa.debian.org/iwj/otter +. + Merge requests (accompanied by a `Signed-off-by` indicating sign-off of the Developer Certificate of Origin) would be very welcome. diff --git a/docs/advanced.md b/docs/advanced.md index c5d0dcfc..4517c383 100644 --- a/docs/advanced.md +++ b/docs/advanced.md @@ -16,8 +16,10 @@ 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. +as found in `src/spec.rs` in the Otter source code. Unfortunately +this is not yet documented. Adding shapes (pieces, cards, etc.) @@ -37,15 +39,16 @@ 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 BUILDING AND TESTING for information about how to install the +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. -If you copied or adapted an SVG from somewhere, provide details. +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) diff --git a/docs/build.rst b/docs/build.rst index f9dc61b8..1d5cca80 100644 --- a/docs/build.rst +++ b/docs/build.rst @@ -5,6 +5,12 @@ Otter is mostly written in Rust. The web UI frontend is written in Typescript. The shape libraries are SVGs and need SVG manipulation libraries. The main documentation is done with Sphinx. +You will need at least 6000 megabytes of disk space, or more, and a +good internet connection. Your computer will be compiling a lot of +code. + +These instructions were once tested on Debian buster. + Setup ----- diff --git a/docs/dev.md b/docs/dev.md index dbfd251a..09e64039 100644 --- a/docs/dev.md +++ b/docs/dev.md @@ -1,21 +1,17 @@ -BUILDING AND TESTING OTTER -========================== +Developing +========== Otter is mostly written in Rust. The web UI frontend is written in Typescript, with a small amount of Rust support code delivered via WebAssembly. +The HTML and SVG skeleton is in a templating language called Tera, +which is a jinja-like but from the Rust community. -You will need at least 6000 megabytes of disk space, or more, and a -good internet connection. Your computer will be compiling a lot of -code. -These instructions have been tested on Debian buster. - - -Ad-hoc tests ------------- +Ad-hoc testing, playing about, etc. +----------------------------------- In one shell: @@ -195,24 +191,11 @@ rune like this: ``` target/debug/daemon-otter tmp/wdt-simple/server-config.toml ``` -and then play with it at this url: +and then play with it at these urls: ``` http://localhost:8000/?kmqAKPwK4TfReFjMor8MJhdRPBcwIBpe + http://localhost:8000/?ccg9kzoTh758QrVE1xMY7BQWB36dNJTx ``` - -Final weirdness ---------------- - - * The `Makefile` `deploy` target is very specific to my setup. - - * For running on chiark I build with the Rust target - `x86_64-unknown-linux-musl` which on my system is configured to - produce a completely statically linked bionary. I have this in my - `~/.cargo/config` (in the lesser privsep account): - -``` -[target.x86_64-unknown-linux-musl] -rustflags = ["-C", "target-feature=+crt-static"] -# ^ from https://stackoverflow.com/questions/31770604/how-to-generate-statically-linked-executables -``` +(Yes, those are a fixed game access links, hardcoded by the tests. +You can bookmark them.) diff --git a/docs/index.rst b/docs/index.rst index 04cda1e8..ccb8b1bd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,6 +14,7 @@ Otter - Online Table Top Environment Renderer user advanced build + install dev diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 00000000..cfdee203 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,64 @@ +Installing +========== + +This is not very polished or well-documented yet. + +The `Makefile` has a `deploy` target which shows how things work on +chiark. + +You will need to write a `server-config.toml`. There is not currently +any documentation for that. But there are some examples. Consider +looking at `server-test.toml` in the toplevel, or one of the config +files made by the tests, in `tmp/*/server-config.toml`. + +The config is a TOML file, which is read using Rust Serde. You can +get at least a list of fields by looking at the Rustdoc-generated "API +doc" for the type `otter::config::ServerConfigSpec`, which is probably +in `target/doc/otter/config/struct.ServerConfigSpec.html`. + +Here a copy of the config file from chiark. As you can see I am +running Otter as an "application server". My usual Apache +configuration handles the TLS. (Rocket's TLS is not advertised as +being suitable for production use.) + +``` +http_port = 1323 +public_url = "https://otter.chiark.net" +sse_wildcard_url = "https://*.sse.otter.chiark.net" + +base_dir = "/volatile/Otter" + +save_dir = "/home/Otter/save" +command_socket = "/volatile/Otter/var/command.socket" + +[log] +global_level = 'debug' + +[log.modules] +'hyper::server' = 'info' +rocket = 'error' +_ = "error" # rocket +"game::debugreader" = 'info' +``` + +The `*.sse` wildcard domain is to work around a bug in the web +facility "server-sent events". You will probably want one of those +too. The SSE bug is documented on MDN + +(as referenced by the docs for `rocket::response::Stream::chunked` +which is the underlying facility used by Otter). + + +Final weirdness +--------------- + +For running on chiark I build with the Rust target +`x86_64-unknown-linux-musl` which on my system is configured to +produce a completely statically linked binary. I have this in my +`~/.cargo/config` (in the lesser privsep account): + +``` +[target.x86_64-unknown-linux-musl] +rustflags = ["-C", "target-feature=+crt-static"] +# ^ from https://stackoverflow.com/questions/31770604/how-to-generate-statically-linked-executables +``` diff --git a/docs/user.md b/docs/user.md index f65259f0..38543ce4 100644 --- a/docs/user.md +++ b/docs/user.md @@ -89,7 +89,7 @@ itself is meant as prompts and hints rather than full documentation. Notable features you might otherwise overlook include these: Pressuing "h" repeatedly cycles through various amounts of history -view (the overliad yellow arrows showing what recently happened). +view (the overlaid yellow arrows showing what recently happened). Typing numbers will get you into a multiple selection mode, which you can use (for example) to draw yourself a hand of multiple cards. @@ -104,8 +104,8 @@ and `O` keyboard commands. There is a Wresting mode for making exceptional changes to the game state, such as forcibly grasping a piece out of another player's -grasp. Don't forget to exit Wresting mode when you're finished with -it. +grasp, or moving the chessboard. Don't forget to exit Wresting mode +when you're finished with it. Bugs and errors @@ -120,11 +120,11 @@ Typically this will improve matters. Hopefully the game state on the server side is not too badly affected. If you can reproduce a bug, please file a bug report; - https://salsa.debian.org/iwj/otter/-/issues/new +. Of course you might want to reload the Otter game page if you have trouble with your network or web browser. The state is all on the -server, so you can reload when you want to. +server, so you can reload or reconnect whenever you like. Game administration -- 2.30.2