Add high-level documentation

1 files changed, 48 insertions, 0 deletions

diff --git a/doc/world.rst b/doc/world.rst
new file mode 100644
index 00000000..31cbe16b
--- /dev/null
+++ b/doc/world.rst
@@ -0,0 +1,48 @@
+World
+=====
+
+.. default-domain:: c
+.. highlight:: c
+
+So far, we have only used nodes and statements,
+which are simple independent objects.
+Higher-level facilities in Serd require a :struct:`SerdWorld`,
+which represents the global library state.
+
+A program typically uses just one world,
+which can be constructed using :func:`serd_world_new`:
+
+.. literalinclude:: overview_code.c
+   :start-after: begin world-new
+   :end-before: end world-new
+   :dedent: 2
+
+All "global" library state is handled explicitly via the world.
+Serd does not contain any static mutable data,
+allowing it to be used concurrently in several parts of a program,
+for example in plugins.
+
+If multiple worlds *are* used in a single program,
+they must never be mixed:
+objects "inside" one world can not be used with objects inside another.
+
+Note that the world is not a database,
+it only manages a small amount of library state for things like configuration and logging.
+
+Generating Blanks
+-----------------
+
+Blank nodes, or simply "blanks",
+are used for resources that do not have URIs.
+Unlike URIs, they are not global identifiers,
+and only have meaning within their local context (for example, a document).
+The world provides a method for automatically generating unique blank identifiers:
+
+.. literalinclude:: overview_code.c
+   :start-after: begin get-blank
+   :end-before: end get-blank
+   :dedent: 2
+
+Note that the returned pointer is to a node that will be updated on the next call to :func:`serd_world_get_blank`,
+so it is usually best to copy the node,
+like in the example above.