// 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

# Vulkan Asciidoc Configuration Files

## Macros

The macros in `vulkan-macros.rb` and `vulkan-macros/extension.rb` are
described in the "Vulkan Documentation and Extensions: Procedures and
Conventions" document (see the [styleguide](../styleguide.txt)).

## 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

`math-docbook.conf` is heavily conditionalized depending on whether the
final output format (which should be described in the a2x-format variable)
is `pdf` or not, since Docbook passes through math differently to dblatex
vs. the XHTML stylesheets. This could be simplified now that we're only
using Docbook for PDFs.

## Stylesheets

`khronos.css` is the stylesheet used for HTML output.