From 11c7ff672a217db6439306877ba9588c253ca0ae Mon Sep 17 00:00:00 2001
From: Carl Gay <carlgay@gmail.com>
Date: Fri, 14 Jun 2024 16:39:56 -0400
Subject: [PATCH] doc: Add Platforms: keyword to LID File Format document

---
 .../getting-started-cli/platform-specific.rst |  8 +++--
 .../source/library-reference/lid.rst          | 32 +++++++++++++++++++
 2 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/documentation/source/getting-started-cli/platform-specific.rst b/documentation/source/getting-started-cli/platform-specific.rst
index 9cd8bf132..e2b4fd00b 100644
--- a/documentation/source/getting-started-cli/platform-specific.rst
+++ b/documentation/source/getting-started-cli/platform-specific.rst
@@ -66,9 +66,11 @@ For further details of the LID file format, see :doc:`../library-reference/lid`.
 4) The ``Platforms`` keyword
 
    Platform-specific LID files should use the ``Platforms`` keyword to indicate
-   which platforms they apply to. This tells the `deft update
-   <https://package.opendylan.org/deft/index.html#deft-update>`_ command which
-   registry files to create.
+   which platforms they apply to. This helps the `deft update
+   <https://package.opendylan.org/deft/index.html#deft-update>`_ command decide
+   which registry files to create. If there is no ``Platforms`` keyword
+   ``deft`` assumes the LID file applies to the current platform and creates a
+   registry file for its library.
 
    =============== ========================= =========================
    Keyword         unix-io.lid               win32-io.lid
diff --git a/documentation/source/library-reference/lid.rst b/documentation/source/library-reference/lid.rst
index a44b01bbe..3b84a11f8 100644
--- a/documentation/source/library-reference/lid.rst
+++ b/documentation/source/library-reference/lid.rst
@@ -168,6 +168,38 @@ Open Dylan's LID extensions
 
 This section contains extensions to LID that Open Dylan supports.
 
+Tooling Support
+---------------
+
+Platforms
+^^^^^^^^^
+
+Platform-specific LID files should use the ``Platforms`` keyword to indicate
+which platforms they apply to. This helps the `deft update
+<https://package.opendylan.org/deft/index.html#deft-update>`_ command decide
+which registry files to create. If there is no ``Platforms`` keyword ``deft``
+assumes the LID file applies to the current platform and creates a registry
+file for its library.
+
+For example, if you have a library with separate LID files for Windows and Unix
+platforms add this to the Windows LID file::
+
+  Platforms: win32
+
+and add this to the Unix LID file::
+
+  Platforms: x86_64-linux
+             x86_64-darwin
+             x86_64-freebsd
+             x86_64-netbsd
+             x86-freebsd
+             x86-linux
+             x86-netbsd
+
+.. note:: We `plan <https://github.com/dylan-lang/deft/issues/3>`_ to add
+          platform aliases such as "unix" so that it isn't necessary to list
+          all supported Unix platforms.
+
 Specifying foreign files and resource files
 -------------------------------------------