1 files changed, 74 insertions, 0 deletions
diff --git a/codegen/vulkan/scripts/README.adoc b/codegen/vulkan/scripts/README.adoc
new file mode 100644
index 00000000..0a60629a
--- /dev/null
+++ b/codegen/vulkan/scripts/README.adoc
@@ -0,0 +1,74 @@
+// Copyright 2014-2021 The Khronos Group Inc.
+//
+// SPDX-License-Identifier: CC-BY-4.0
+
+= Vulkan^(R)^ Specification Repository Scripts
+
+This directory contains scripts used in building the Vulkan API
+specification and related artifacts. For the most part, these scripts are
+invoked from the top-level directory or from the API Registry in
+../xml to build generated components of the specification.
+
+Scripts in this directory include:
+
+  * `genvk.py` - Python script to generate Vulkan headers and some other
+    targets, using the generators described below.
+  * `reg.py` - Python tools to read a registry XML file and call into
+    generators to create headers and other types of output.
+  * `conventions.py`, `vkconventions.py` - API-specific parameters and
+    formatting / style conventions used by generators.
+  * `generator.py` - output generator base class.
+  ** `cgenerator.py` - C header output generator.
+  ** `docgenerator.py` - Asciidoc interface language include generator.
+  ** `extensionmetadocgenerator.py` - Generator for Asciidoc extension
+     descriptions in spec appendices.
+  ** `hostsyncgenerator.py` - Asciidoc host sync table generator.
+  ** `pygenerator.py` - Generates python encoding of the API description.
+  ** `validitygenerator.py` - Asciidoc validity language generator.
+
+  * `check_spec_links.py` - validates a variety of markup and content in the
+    Asciidoctor specification source.
+  * `make_ext_dependency.py` - generate extension dependencies in Bash and
+    Python form for use when building the specification.
+  * `genRelease`, `genspec.py` - build HTML and PDF Specifications with a
+    variety of options to control target directories, extensions included
+    while building, etc.
+  * `genRef.py`, `reflib.py` - extract API reference pages from specification
+    source into single-page source documents.
+  * `indexExt.py` - generate HTML index of all extensions for inclusion into
+    the Vulkan registry index page.
+  * `reflow.py`, `reflow_count.py` - reflow specification source text to follow
+    style guidelines, and insert Valid Usage statements where they're
+    needed.
+  * `test_check_spec_links.py`, `test_check_spec_links_api_specific.py`,
+    `test_entity_db.py` - these are from another Khronos WG repository and
+    are unused by Vulkan at present.
+
+  * `compImages.sh` - compare images in two branches.
+  * `htmldiff/htmldiff` - HTML diff script (see below).
+  * `Retired/` - contains obsolete, unused, or single-purpose scripts. Not
+    maintained.
+
+HTML Diff Script for Vulkan
+===========================
+
+This is a first cut at a script to compare Vulkan HTML specifications. Usage
+is simply 'htmldiff file1.html file2.html > diff.html'. The script does not
+copy CSS and images required by the input specs, so it's best to generate
+the output in the same directory as one of the inputs. However, the script
+must be invoked from the directory it is located within.
+
+The scripts used require Python and Perl. Additionally, the python
+'utidylib' module and the underlying libtidy C library are required.
+On Debian Linux, it may be necessary to install the 'python-utidylib' and
+'libtidy' packages if they are not already present.
+
+The scripts are taken from the code backing the
+
+    http://services.w3.org/htmldiff
+
+website. `htmldiff` is the Python driver script. `htmldiff.pl` is the
+Perl script which generates the diff after preprocessing of the input
+HTML by `htmldiff`. `htmldiff.orig` is the original Python script from
+the website, modified to run at the command line instead of as a CGI
+script.