Name Date Size

..25-Oct-20244 KiB

asciidoctor-mathematical-ext.rbH A D25-Oct-2024686

attribs.adocH A D25-Oct-20243 KiB

attribs.txtH A D25-Oct-20242.3 KiB

chunkindex/H25-Oct-20244 KiB

CI/H25-Oct-20244 KiB

copyright-ccby.adocH A D25-Oct-202479

copyright-ccby.txtH A D25-Oct-202479

copyright-spec.adocH A D25-Oct-20246.8 KiB

docinfo-header.htmlH A D25-Oct-20248.8 KiB

extension-highlighter/H25-Oct-20244 KiB

extension-highlighter.rbH A D25-Oct-2024319

fonts/H25-Oct-20244 KiB

genanchorlinks.rbH A D25-Oct-2024655

ifdef-mismatch/H25-Oct-20244 KiB

ifdef-mismatch.rbH A D25-Oct-2024264

katex_replace/H25-Oct-20244 KiB

katex_replace.rbH A D25-Oct-2024371

khronos.cssH A D25-Oct-202437.2 KiB

loadable_html/H25-Oct-20244 KiB

loadable_html.rbH A D25-Oct-2024364

makedocinfologoH A D25-Oct-2024721

makeSubmit.pyH A D25-Oct-20245.8 KiB

mathtest.adocH A D25-Oct-202425.6 KiB

mathtest.txtH A D25-Oct-202425.6 KiB

open_listing_block.rbH A D25-Oct-2024651

optimize-pdfH A D25-Oct-20243.2 KiB

quiet-include-failure.rbH A D25-Oct-2024769

README.adocH A D25-Oct-20242.2 KiB

rouge-extend-css.rbH A D25-Oct-20241.8 KiB

spec-macros/H25-Oct-20244 KiB

spec-macros.rbH A D25-Oct-20241.3 KiB

themes/H25-Oct-20244 KiB

tilde_open_block.rbH A D25-Oct-20242.3 KiB

vu-to-json/H25-Oct-20244 KiB

vu-to-json.rbH A D25-Oct-2024261

vuid-expander.rbH A D25-Oct-20241 KiB

vulkan/H25-Oct-20244 KiB

vulkansc/H25-Oct-20244 KiB

README.adoc

1// Copyright 2015-2024 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5= Vulkan Asciidoc Configuration Files
6
7== Macros
8
9The macros in `spec-macros.rb` and `spec-macros/extension.rb` are described
10in the "`Vulkan Documentation and Extensions: Procedures and Conventions`"
11document (see the link:../styleguide.adoc[style guide].
12
13== Support for Math
14
15Asciidoctor is customized to insert KaTeX `<script>` tags from
16`math.js` for HTML5, and properly pass through math which has
17`\begin{}\/end{}` delimiters instead of $$\[\]\(\).
18
19For PDF builds, asciidoctor-mathematical is used to generate
20images.
21
22== Stylesheets
23
24`khronos.css` is the stylesheet used for HTML output.
25It is a slightly tweaked version of the Asciidoctor 'Colony' theme.
26
27== Chunked Spec Index
28
29`chunkindex` contains scripts for building and using a search index for the
30Vulkan chunked HTML specification.
31
32== Title Page Images
33
34Asciidoctor requires use of `docinfo` files to get logos onto the title
35page, and has very restrictive naming conventions forcing the
36subdirectories:
37
38* `vulkan/docinfo-header.html` - Vulkan logo in docinfo HTML form
39* `vulkansc/docinfo-header.html` - Vulkan SC logo in docinfo HTML form
40* `makedocinfologo` - script to convert SVG file to docinfo HTML file
41
42== Asciidoctor Extensions
43
44We use a number of Asciidoctor customizations written in Ruby, described
45briefly below.
46
47* `asciidoctor-mathematical-ext.rb` - make latexmath: blocks work in table cells
48* `extension-highlighter.rb` - one way of constructing a diff HTML document
49* `katex_replace.rb` - substitute KaTeX for MathJax in output HTML
50* `loadable_html.rb` - add some status messages for slow-loading documents
51* `rouge-extend-css.rb` - override parts of the 'rouge' highlighter CSS
52* `spec-macros.rb` - custom asciidoctor macros used in spec markup
53* `open_listing_block.rb` - allow '----' as a nested open block delimiter when tagged by '[open]'
54* `vuid-expander.rb` - add anchors to valid usage ID tags
55* `vu-to-json.rb` - extract valid usage statements to JSON as part of a dummy spec build
56
57== CI support files
58
59These files are auxiliary data supplied to CI scripts
60
61* CI/contractions - disallowed contractions
62* CI/contractions-allowed - regular expressions matching filenames allowed
63  to have contractions
64