1// Copyright 2014-2022 The Khronos Group Inc. 2// SPDX-License-Identifier: CC-BY-4.0 3 4= Vulkan^(R)^ Specification Repository Scripts 5 6This directory contains scripts used in building the Vulkan API 7specification and related artifacts. For the most part, these scripts are 8invoked from the top-level directory or from the API Registry in 9../xml to build generated components of the specification. 10 11Scripts in this directory include: 12 13 * `genvk.py` - Python script to generate Vulkan headers and some other 14 targets, using the generators described below. 15 * `reg.py` - Python tools to read a registry XML file and call into 16 generators to create headers and other types of output. 17 * `conventions.py`, `vkconventions.py`, `apiconventions.py` - API-specific 18 parameters and formatting / style conventions used by generators. 19 * `generator.py` - output generator base class. 20 ** `cgenerator.py` - C header output generator. 21 ** `docgenerator.py` - Asciidoc interface language include generator. 22 ** `extensionmetadocgenerator.py` - Generator for Asciidoc extension 23 descriptions in spec appendices. 24 ** `hostsyncgenerator.py` - Asciidoc host sync table generator. 25 ** `interfacedocgenerator.py` - Asciidoc extension appendix interface 26 generator. 27 ** `pygenerator.py, `rubygenerator.py`, `scriptgenerator.py` - generate 28 Python and Ruby encodings of parts of the API description for use in 29 other scripts and asciidoctor extensions. 30 ** `spirvcapgenerator.py` - Asciidoc generator for SPIR-V capability 31 tables. 32 ** `validitygenerator.py` - Asciidoc validity language generator. 33 34 * `check_spec_links.py` - validates a variety of markup and content in the 35 Asciidoctor specification source. 36 * `conventions.py`, `vkconventions.py` - API-specific options used by 37 scripts shared with OpenXR and other APIs. 38 * `extdependency.py` - generate extension dependencies for use when 39 building the specification. 40 * `genanchorlinks.py` - add HTML `href` attributes to asciidoctor output 41 to improve UI for VUID anchors. 42 * `genRelease`, `genspec.py` - build HTML and PDF Specifications with a 43 variety of options to control target directories, extensions included 44 while building, etc. 45 * `genRef.py`, `reflib.py`, `makemanaliases.py` - extract API reference 46 pages from specification source into single-page source documents, and 47 create symbolic links in the generated refpage HTML for API aliases. 48 * `indexExt.py` - generate HTML index of all extensions for inclusion into 49 the Vulkan registry index page. 50 * `reflow.py`, `reflow_count.py` - reflow specification source text to 51 follow style guidelines, and insert Valid Usage statements where they 52 are needed. 53 * `test_check_spec_links.py`, `test_check_spec_links_api_specific.py`, 54 `test_entity_db.py` - these are from another Khronos WG repository and 55 are unused by Vulkan at present. 56 * `xml_consistency.py` - perform some internal consistency checks on 57 `vk.xml`. 58 59 * `compImages.sh` - compare images in two branches. 60 * `htmldiff/htmldiff` - HTML diff script (see below). 61 * `Retired/` - contains obsolete, unused, or single-purpose scripts. Not 62 maintained. 63 64== HTML Diff Script for Vulkan 65 66This is a first cut at a script to compare Vulkan HTML specifications. Usage 67is simply 'htmldiff file1.html file2.html > diff.html'. The script does not 68copy CSS and images required by the input specs, so it is best to generate 69the output in the same directory as one of the inputs. However, the script 70must be invoked from the directory it is located within. 71 72The scripts used require Python and Perl. Additionally, the python 73'utidylib' module and the underlying libtidy C library are required. 74On Debian Linux, it may be necessary to install the 'python-utidylib' and 75'libtidy' packages if they are not already present. 76 77The scripts are taken from the code backing the 78 79 http://services.w3.org/htmldiff 80 81website. `htmldiff` is the Python driver script. `htmldiff.pl` is the 82Perl script which generates the diff after preprocessing of the input 83HTML by `htmldiff`. `htmldiff.orig` is the original Python script from 84the website, modified to run at the command line instead of as a CGI 85script. 86