| // Copyright 2015-2023 The Khronos Group Inc. |
| // |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| = Vulkan Asciidoc Configuration Files |
| |
| == Macros |
| |
| The macros in `spec-macros.rb` and `spec-macros/extension.rb` are described |
| in the "`Vulkan Documentation and Extensions: Procedures and Conventions`" |
| document (see the link:../styleguide.adoc[style guide]. |
| |
| == Support for Math |
| |
| Asciidoctor is customized to insert KaTeX `<script>` tags from |
| `math.js` for HTML5, and properly pass through math which has |
| `\begin{}\/end{}` delimiters instead of $$\[\]\(\). |
| |
| For PDF builds, asciidoctor-mathematical is used to generate |
| images. |
| |
| == Stylesheets |
| |
| `khronos.css` is the stylesheet used for HTML output. |
| It is a slightly tweaked version of the Asciidoctor 'Colony' theme. |
| |
| == Chunked Spec Index |
| |
| `chunkindex` contains scripts for building and using a search index for the |
| Vulkan chunked HTML specification. |
| |
| == Title Page Images |
| |
| Asciidoctor requires use of `docinfo` files to get logos onto the title |
| page, and has very restrictive naming conventions forcing the |
| subdirectories: |
| |
| * `vulkan/docinfo-header.html` - Vulkan logo in docinfo HTML form |
| * `vulkansc/docinfo-header.html` - Vulkan SC logo in docinfo HTML form |
| * `makedocinfologo` - script to convert SVG file to docinfo HTML file |
| |
| == Asciidoctor Extensions |
| |
| We use a number of Asciidoctor customizations written in Ruby, described |
| briefly below. |
| |
| * `asciidoctor-mathematical-ext.rb` - make latexmath: blocks work in table cells |
| * `extension-highlighter.rb` - one way of constructing a diff HTML document |
| * `katex_replace.rb` - substitute KaTeX for MathJax in output HTML |
| * `loadable_html.rb` - add some status messages for slow-loading documents |
| * `rouge-extend-css.rb` - override parts of the 'rouge' highlighter CSS |
| * `spec-macros.rb` - custom asciidoctor macros used in spec markup |
| * `open_listing_block.rb` - allow '----' as a nested open block delimiter when tagged by '[open]' |
| * `vuid-expander.rb` - add anchors to valid usage ID tags |
| * `vu-to-json.rb` - extract valid usage statements to JSON as part of a dummy spec build |
| |
| == CI support files |
| |
| These files are auxiliary data supplied to CI scripts |
| |
| * CI/contractions - disallowed contractions |
| * CI/contractions-allowed - regular expressions matching filenames allowed |
| to have contractions |
