# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1634414958 -7200
# Node ID 1f0dc9161667ffd093d5ed22ff6bba93d0157f1d
# Parent  16fba513c761425cefa0f096ad44effd22edb82b
Updated the documentation to reflect directory-related changes.

diff -r 16fba513c761 -r 1f0dc9161667 docs/wiki/Components
--- a/docs/wiki/Components	Sat Oct 16 00:22:38 2021 +0200
+++ b/docs/wiki/Components	Sat Oct 16 22:09:18 2021 +0200
@@ -15,8 +15,8 @@
 
 == Overview ==
 
-An overview of the component interactions involved in opening a file is
-provided by the diagram below.
+An overview of the component interactions involved in opening a file or
+directory is provided by the diagram below.
 
 ######## A graph showing the interactions between components
 
@@ -29,7 +29,7 @@
   rankdir=LR;
 
   subgraph {
-    node [label="Client",style=solid,color="#000000",fontcolor="#000000"];
+    node [label="Client"];
     rank=min;
 
     Client1; Client2; Client3; Client4; Client5; Client6; Client7;
@@ -37,11 +37,13 @@
 
   subgraph {
     rank=same;
+
     Memory [label="filename",shape=note];
   }
 
   subgraph {
-    rank=same;
+    rank=max;
+
     Filesystem;
 
     subgraph {
@@ -54,7 +56,7 @@
       OpenerContext1; OpenerContext2; OpenerContext3;
     }
 
-    MappedFile;
+    Object [label="MappedFile\nor\nDirectory"];
   }
 
   Client1 -> Client2 -> Client3 -> Client4 -> Client5 -> Client6 -> Client7 [arrowhead=none,style=dotted];
@@ -72,8 +74,8 @@
   Client5 -> Memory -> OpenerContext2;
 
   Client6 -> OpenerContext3 [label="open(flags, ...)"];
-  OpenerContext3 -> MappedFile;
-  MappedFile -> Client7;
+  OpenerContext3 -> Object;
+  Object -> Client7;
 }
 }}}
 
@@ -89,6 +91,67 @@
 file = context.open(flags, ...)
 }}}
 
+Reading from an opened directory is achieved as shown in the following
+diagram.
+
+######## A graph showing the interactions between components
+
+{{{#!graphviz
+#format svg
+#transform notugly
+digraph components {
+  node [fontsize="12.0",fontname="sans-serif",shape=box];
+  edge [fontsize="12.0",fontname="sans-serif"];
+  rankdir=LR;
+
+  subgraph {
+    node [label="Client"];
+    rank=min;
+
+    Client1; Client2; Client3; Client4;
+  }
+
+  subgraph {
+    rank=same;
+
+    Memory [label="entries",shape=note];
+  }
+
+  subgraph {
+    rank=max;
+
+    Directory;
+
+    subgraph {
+      node [label="Reader"];
+
+      Reader1; Reader2; Reader3;
+    }
+  }
+
+  Client1 -> Client2 -> Client3 -> Client4 [arrowhead=none,style=dotted];
+  Reader1 -> Reader2 -> Reader3 [arrowhead=none,style=dotted];
+
+  Client1 -> Directory [label="opendir()"];
+  Directory -> Reader1;
+  Reader1 -> Client2;
+
+  Client3 -> Reader2 [label="current_region()"];
+  Reader3 -> Memory -> Client4;
+}
+}}}
+
+########
+
+In pseudocode, the operations as conducted by the client program are as
+follows:
+
+{{{
+reader = directory.opendir()
+reader.current_region()
+entries = reader.read() # this being a memory access operation
+}}}
+
 == Filesystems ==
 
 Filesystems implement the `Filesystem` interface which provides the
@@ -165,7 +228,17 @@
 
 == Directories ==
 
-Directories are also meant to be accessed like files, meaning that it should
+Directories are obtained, like files, using the `open` operation. They
+implement the `Directory` interface.
+
+To read directory listings, the `opendir` operation is used to obtain a
+directory reader:
+
+{{{
+opendir(out offset_t size, out cap file, out object_flags_t object_flags)
+}}}
+
+Directory readers are meant to be accessed like files, meaning that it should
 be possible to attach them to a task using a region manager and access the
 provided content, this being a listing of directory entries, via the mapped
 region.
@@ -175,9 +248,6 @@
 supporting precisely the same navigation mechanisms as those supported by
 files.
 
-'''Note''' that directories may well be redefined to support multiple
-operations, one of which supporting the file-like access described above.
-
 == Pipe Openers ==
 
 Distinct from filesystems but potentially used by them, pipe openers provide a