| // Copyright 2015-2021 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.txt[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. |
| |
| == 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 |
| * `tilde_open_block.rb` - allow '~~~~' as an open block delimiter |
| * `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 |
