From 3f70c7a256ab8dc3d99daae1483ba29a218337d2 Mon Sep 17 00:00:00 2001
From: Tony Garnock-Jones <tonyg@leastfixedpoint.com>
Date: Sat, 14 May 2022 15:31:13 +0200
Subject: [PATCH] More

---
 src/SUMMARY.md                   | 64 +++++++++++++++++---------------
 src/libraries/python-support.md  | 11 ++++++
 src/libraries/shell-scripting.md | 12 ++++++
 src/tools/preserves-tools.md     | 18 +++++++++
 4 files changed, 76 insertions(+), 29 deletions(-)
 create mode 100644 src/libraries/python-support.md
 create mode 100644 src/libraries/shell-scripting.md
 create mode 100644 src/tools/preserves-tools.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index 62e1d71..3ee0ecd 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -28,35 +28,10 @@
   - [Manage user settings](./operation/howto/manage-user-settings.md)
   - [Reboot and power off the machine](./operation/howto/reboot-and-power-off.md)
   - [Suspend the machine](./operation/howto/suspend.md)
-- [Standard tools]()
-  - [preserves-tools]()
-- [Standard libraries]()
-  - [Python support libraries]()
-  - [Shell-scripting libraries]()
-- [Standard protocols and schema definitions]()
-  - [Preserves schemas]()
-    - [Preserves Schema metaschema]()
-    - [Preserves Path schema]()
-  - [Syndicated Actor Model schemas]()
-    - ["Observe" assertions]()
-    - [Patterns over assertions]()
-    - [Gatekeeper and Sturdy-references]()
-    - [Wire-protocol]()
-    - [Service dependencies]()
-    - [Tracing]()
-    - [Transport addresses]()
-  - [Synit schemas]()
-    - [Audio control]()
-    - [Telephony (call and SMS) support]()
-    - [Modem support]()
-      - [Hayes]()
-      - [Samsung Galaxy S7]()
-    - [MIME type support]()
-    - [Network core status and configuration]()
-    - [Sound effects]()
-    - [Time stamps]()
-    - [User interface definitions and interaction]()
-    - [User settings]()
+
+# Tools
+
+- [The `preserves-tools` package](./tools/preserves-tools.md)
 
 # Programming Guide and Reference
 
@@ -64,6 +39,37 @@
 - [Working with schemas](./guide/working-with-schemas.md)
 - [Capturing and rendering interaction traces](./guide/tracing.md)
 
+# Programming Libraries
+
+- [Python support libraries](./libraries/python-support.md)
+- [Shell-scripting libraries](./libraries/shell-scripting.md)
+
+# Protocols and Schema Definitions
+
+- [Preserves schemas]()
+  - [Preserves Schema metaschema]()
+  - [Preserves Path schema]()
+- [Syndicated Actor Model schemas]()
+  - ["Observe" assertions]()
+  - [Patterns over assertions]()
+  - [Gatekeeper and Sturdy-references]()
+  - [Wire-protocol]()
+  - [Service dependencies]()
+  - [Tracing]()
+  - [Transport addresses]()
+- [Synit schemas]()
+  - [Audio control]()
+  - [Telephony (call and SMS) support]()
+  - [Modem support]()
+    - [Hayes]()
+    - [Samsung Galaxy S7]()
+  - [MIME type support]()
+  - [Network core status and configuration]()
+  - [Sound effects]()
+  - [Time stamps]()
+  - [User interface definitions and interaction]()
+  - [User settings]()
+
 # Specifications and Theory
 
 - [Syndicated Actor Model](./syndicated-actor-model.md)
diff --git a/src/libraries/python-support.md b/src/libraries/python-support.md
new file mode 100644
index 0000000..588dc73
--- /dev/null
+++ b/src/libraries/python-support.md
@@ -0,0 +1,11 @@
+# Python support libraries
+
+The `py3-preserves` and `py3-syndicate` packages include the Python implementations of
+Preserves ([`preserves` on PyPI](https://pypi.org/project/preserves/);
+[git](https://gitlab.com/preserves/preserves/tree/main/implementations/python/)) and the
+[Syndicated Actor Model](../glossary.md#syndicated-actor-model) and [Syndicate
+Protocol](../protocol.md) ([`syndicate-py` on PyPI](https://pypi.org/project/syndicate-py/);
+[git](https://git.syndicate-lang.org/syndicate-lang/syndicate-py)), respectively.
+
+When installed, the libraries are available in the standard location for system-wide Python
+packages.
diff --git a/src/libraries/shell-scripting.md b/src/libraries/shell-scripting.md
new file mode 100644
index 0000000..14ed39c
--- /dev/null
+++ b/src/libraries/shell-scripting.md
@@ -0,0 +1,12 @@
+# Shell-scripting libraries
+
+The `syndicate-sh` package includes `/usr/lib/syndicate/syndicate.sh`, an implementation of the
+[Syndicate Protocol](../protocol.md) for Bash. Scripts may take advantage of the library to
+interact with peers via system dataspaces, either as [supervised
+services](../operation/builtin/daemon.md) or as external programs making use of the [gatekeeper
+service](../operation/builtin/gatekeeper.md).
+
+Examples of both kinds of script are included in the [`syndicate-sh` git
+repository](https://git.syndicate-lang.org/syndicate-lang/syndicate-sh) (see the
+[examples](https://git.syndicate-lang.org/syndicate-lang/syndicate-sh/src/branch/main/examples)
+directory).
diff --git a/src/tools/preserves-tools.md b/src/tools/preserves-tools.md
new file mode 100644
index 0000000..28662b6
--- /dev/null
+++ b/src/tools/preserves-tools.md
@@ -0,0 +1,18 @@
+# The `preserves-tools` package
+
+The `preserves-tools` package includes useful command-line utilities for working with
+[Preserves](../guide/preserves.md) values and schemas.
+
+At present, it includes the [`preserves-tool` Swiss-army-knife
+utility][preserves-tool], which is useful for
+
+ - converting between text and binary Preserves syntaxes;
+ - pretty-printing (indenting) text Preserves syntax;
+ - manipulating Preserves annotations;
+ - breaking down and filtering Preserves documents using [preserves
+   path](https://preserves.gitlab.io/preserves/preserves-path.html) selectors;
+ - and so on.
+
+See also the [`preserves-tool` documentation][preserves-tool].
+
+[preserves-tool]: https://preserves.gitlab.io/preserves/doc/preserves-tool.html