doc: outline usage

2 files changed, 13 insertions, 1 deletions

diff --git a/readme.rst b/readme.rst
index a51b7e9..1337387 100644
--- a/readme.rst
+++ b/readme.rst
@@ -5,6 +5,13 @@ format.
 
 Includes a utility ``sidparse`` for dissecting SIDs on the command line.
 
+entry points
+------------
+
+Convert to and from the string format using the *to_string* and *of_string*
+functions. The binary representations can be encoded and decoded using the
+corresponding *to_bytes* and *of_bytes* methods.
+
 building
 --------
 The main build system is Oasis_, but there is a wrapper for OPAM to simplify
diff --git a/sid.mli b/sid.mli
index a21c5ec..de9d6ea 100644
--- a/sid.mli
+++ b/sid.mli
@@ -4,7 +4,12 @@
 
     {e Sid} implements the “Security Identifier” data type commonly used
     on the Microsoft Windows platform. When processing input, it tries to
-    adhere as closely to the specification as possible.
+    adhere as closely to the specification as possible. Optionally, a
+    special mode for the text representation is available as the
+    {e MSStringFmt} module which aims to be bug-for-bug compatible with
+    the official implementation. There is no such mode for the two identical
+    binary representations due to the fact that they don’t leave room for
+    ambiguity.
 
     @see <https://msdn.microsoft.com/en-us/library/cc230371.aspx> the relevant
     section in the {e [MS-DTYP]} compilation of types. *)