1// Copyright 2015-2023 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