1  = Vulkan^(R)^ Specification Repository Scripts
 2  
 3  This directory contains scripts used in building the Vulkan API
 4  specification and related artifacts. For the most part, these scripts are
 5  invoked from the top-level directory or from the API Registry in
 6  ../xml to build generated components of the specification.
 7  
 8  Scripts in this directory include:
 9  
10    * genvk.py - Python script to generate Vulkan headers and some other
11      targets, using the generators described below.
12    * reg.py - Python tools to read a registry XML file and call into
13      generators to create headers and other types of output.
14    * conventions.py, vkconventions.py - API-specific parameters and
15      formatting / style conventions used by generators.
16    * generator.py - output generator base class.
17    ** cgenerator.py - C header output generator.
18    ** docgenerator.py - Asciidoc interface language include generator.
19    ** extensionmetadocgenerator.py - Generator for Asciidoc extension
20       descriptions in spec appendices.
21    ** hostsyncgenerator.py - Asciidoc host sync table generator.
22    ** pygenerator.py - Generates python encoding of the API description.
23    ** validitygenerator.py - Asciidoc validity language generator.
24  
25    * checkXrefs - shell script to look for broken internal links in a
26      generated HTML specification.
27    * check_spec_links.py - validates a variety of markup and content in the
28      Asciidoctor specification source.
29    * make_ext_dependency.py - generate extension dependencies in Bash and
30      Python form for use when building the specification.
31    * genRelease, genspec.py - build HTML and PDF Specifications with a
32      variety of options to control target directories, extensions included
33      while building, etc.
34    * genRef.py, reflib.py - extract API reference pages from specification
35      source into single-page source documents.
36    * indexExt.py - generate HTML index of all extensions for inclusion into
37      the Vulkan registry index page.
38    * reflow.py, reflow_count.py - reflow specification source text to follow
39      style guidelines, and insert Valid Usage statements where they're
40      needed.
41    * test_check_spec_links.py, test_check_spec_links_api_specific.py,
42      test_entity_db.py - these are from another Khronos WG repository and are
43      unused by Vulkan at present.
44    * htmldiff/htmldiff - HTML diff script (see below).
45  
46    * Retired/ - contains obsolete, unused, or single-purpose scripts. Not
47      maintained.
48  
49  HTML Diff Script for Vulkan
50  ===========================
51  
52  This is a first cut at a script to compare Vulkan HTML specifications. Usage
53  is simply 'htmldiff file1.html file2.html > diff.html'. The script does not
54  copy CSS and images required by the input specs, so it's best to generate
55  the output in the same directory as one of the inputs. However, the script
56  must be invoked from the directory it is located within.
57  
58  The scripts used require Python and Perl. Additionally, the python
59  'utidylib' module and the underlying libtidy C library are required,
60  which may make it challenging to run the scripts on non-Linux platforms
61  - I haven't checked and those requirements cannot be easily removed. On
62  Debian Linux, it may be necessary to install the 'python-utidylib' and
63  'libtidy' packages if they are not already present. I haven't checked
64  dependencies for other Linux distributions but they are probably
65  similar.
66  
67  The scripts are taken from the code backing the
68  
69      http://services.w3.org/htmldiff
70  
71  website. 'htmldiff' is the Python driver script. 'htmldiff.pl' is the
72  Perl script which generates the diff after preprocessing of the input
73  HTML by 'htmldiff'. 'htmldiff.orig' is the original Python script from
74  the website, modified to run at the command line instead of as a CGI
75  script.