This gives an overview of the configuration files in this directory
(doc/specs/vulkan/config/).

--------------- Config File Macros ----------------

The macros in vkspec.conf and manpages.conf are described in the Vulkan
Documentation and Extensions: Procedures and Conventions document (see
../styleguide.txt). There's a parsing issue with comments in vkspec.conf,
so they are pulled out here for now.

----------------- PDF Generation ------------------

vkspec-dblatex.xsl

    is XSL specific to a2x->dblatex->PDF spec generation. It is a very
    slightly modified version of /etc/asciidoc/dblatex/asciidoc-dblatex.xsl,
    as follows:

>   <xsl:param name="latex.hyperparam">colorlinks,linkcolor=black,pdfstartview=FitH</xsl:param>
>   <xsl:param name="doc.publisher.show">0</xsl:param>
>   <xsl:param name="latex.output.revhistory">0</xsl:param>

    and has been simplified to just those parameters. Additional templates
    replacing those under /usr/share/xml/docbook/stylesheet/dblatex/xsl/*
    can be added here.

---------------- XHTML Generation -----------------

vkspec-xhtml.css

    is CSS for the xhtml and chunked targets. It is pulled in from
    docbook-xsl/common.xsl. This gives us direct control over the CSS for
    the document, including support for markup styles.

-------------- Asciibook Stylesheets --------------

docbook-xsl/chunked.xsl
docbook-xsl/common.xsl
docbook-xsl/xhtml.xsl
docbook-xsl/manpage.xsl

    replace parts of the asciibook stylesheets normally found under
    /etc/asciidoc/docbook-xsl , in order to generate consistent IDs on
    sections and to insert MathJax <script> tags into HTML headers. More
    will be required for other output types.

---------------- Support for Math -----------------

mathjax-asciidoc.conf
mathjax-docbook.conf
mathjax.js

    customize asciidoc macros for HTML and Docbook output to insert MathJax
    <script> tags from mathjax.js, and properly pass through math which has
    \begin{}\/end{} delimiters instead of $$\[\]\(\), using the <?texmath
    delimiters="user"?> processing instruction.

    mathjax-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 HTML stylesheets.