1// Copyright 2015-2022 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== Asciidoctor Extensions 33 34We use a number of Asciidoctor customizations written in Ruby, described 35briefly below. 36 37* `asciidoctor-mathematical-ext.rb` - make latexmath: blocks work in table cells 38* `extension-highlighter.rb` - one way of constructing a diff HTML document 39* `katex_replace.rb` - substitute KaTeX for MathJax in output HTML 40* `loadable_html.rb` - add some status messages for slow-loading documents 41* `rouge-extend-css.rb` - override parts of the 'rouge' highlighter CSS 42* `spec-macros.rb` - custom asciidoctor macros used in spec markup 43* `tilde_open_block.rb` - allow '~~~~' as an open block delimiter 44* `vuid-expander.rb` - add anchors to valid usage ID tags 45* `vu-to-json.rb` - extract valid usage statements to JSON as part of a dummy spec build 46 47== CI support files 48 49These files are auxiliary data supplied to CI scripts 50 51* CI/contractions - disallowed contractions 52* CI/contractions-allowed - regular expressions matching filenames allowed 53 to have contractions 54