| // 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. |