docs: wip document specs etc.

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

diff --git a/docs/bundles.rst b/docs/bundles.rst
index 5ad6526b41dd97f78466cf9a7d8e440ecefcc9f4..40ccf9abddb92888938f56ad15d1fbea5eacaf62 100644 (file)
--- a/docs/bundles.rst
+++ b/docs/bundles.rst
@@ -41,6 +41,9 @@ These files are all in TOML format.  TOML ia an INI-file-like format
 designed for human editing and flexibility.  See the `TOML
 documentation <https://toml.io/en/>`_ for information about the syntax.
 
+Any other files which might be present in the zipfile are ignored.
+(Future versions of Otter might define a meaning for them.)
+
 Character set and case-sensitivity
 ``````````````````````````````````
 

diff --git a/docs/shapelibs.rst b/docs/shapelibs.rst
index f80baf9e96f41314089a8707d13c002f7d371f79..c2aaf6dbab391c5256d364a16af574984e4af07f 100644 (file)
--- a/docs/shapelibs.rst
+++ b/docs/shapelibs.rst
@@ -44,6 +44,26 @@ the catalogue is ``libraries/LIB.toml`` and the image files are in a
 directory ``libraries/LIB.toml``.  The layout of Otter's builtin
 libraries is similar.
 
+Image files
+-----------
+
+Otter supports uploading of SVG and PNG files.  They should be in the
+directory ``library/LIB``, named after the item.  (See `Files entry`_
+for details of how to specify the file names.)
+
+Image files should be small --- ideally a handful of kilobytes, or
+less.  SVG images should be of modest complexity.
+
+Large image files don't just upload slowly; they also make the game
+perform poorly when playing.  This is because the image files are
+frequently (re)transmitted by the server to each client.
+
+It is not normally necessary to specify images in great detail: they
+take only a small space on the players' screens, so the resolution
+does not need to be awesome.  As an example, the playing cards in the
+builtin ``cards-oxymoron`` library are image files of just 73x97
+pixels.
+
 Catalogue
 ---------