1// Copyright 2014-2022 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[introduction]] 6= Introduction 7 8This document contains required procedures and conventions when writing 9specifications for new Vulkan APIs, extensions and layers, or related 10Khronos^{reg}^ documentation such as white papers and tutorials; or 11contributing to existing Vulkan specifications. 12These are collectively referred to as _Vulkan Documentation_ or just 13_documentation_ below. 14The primary focus is the API Specification and API extensions, although all 15of the markup and most of the writing style is equally applicable to other 16documentation. 17 18The primary purpose is to achieve consistency across the API, as well as 19across all of our source and output documents. 20Consistency makes it easier for developers, editors, reviewers, and users of 21our documentation to understand and modify it. 22 23This document is now formally voted on and approved by the Vulkan Working 24Group. 25This means that unless explicitly stated otherwise, the procedures and 26conventions must be followed. 27If you have a strong desire to modify the procedures and conventions, such 28changes must be made through the normal Vulkan Working Group processes. 29 30 31[[introduction-terminology]] 32== Terminology 33 34The key words *must*, *required*, *should*, *recommend*, *may*, and 35*optional* in this document are to be interpreted as described in RFC 2119 36and by the Vulkan Specification in the "`Terminology`" section. 37 38 39[[introduction-structure]] 40== Document Structure 41 42The style guide is broken into four sections: 43 44 * <<naming,API Naming Conventions>> - the required rules for choosing 45 names of Vulkan identifiers of all types. 46 * <<extensions,Extensions and Layers>> - the required procedures for 47 creating formal Vulkan extensions and layers. 48 * <<markup,Markup Style>> - the required and recommended markup style for 49 writing asciidoctor and XML source that follows consistent formatting 50 and layout guidelines, tags special terms and phrases for proper 51 processing by the spec generation tools, etc. 52 * <<writing,Writing Style>> - the required and recommended writing style 53 for overall and fine-grained structure and conventions, normative 54 language use, API naming conventions, common words and phrases to use 55 and to avoid, linking and cross-referencing, etc. 56 57 58[[introduction-asciidoc]] 59== Asciidoctor Markup 60 61Vulkan Documentation is primarily written in Asciidoctor, a text markup 62language. 63We use the command-line asciidoctor client that is actively maintained by 64asciidoctor, which is documented on its website at https://asciidoctor.org. 65 66References to the Asciidoctor User Manual are to sections in the document at 67https://asciidoctor.org/docs/user-manual/. 68 69Asciidoctor is implemented in Ruby (https://www.ruby-lang.org/), which is 70available for Linux, MacOS, and Microsoft Windows. 71 72[NOTE] 73.Note 74==== 75There are other implementations of asciidoctor, such as AsciidoctorJ 76(https://github.com/asciidoctor/asciidoctorj) and asciidoctor.js 77(https://github.com/asciidoctor/asciidoctor.js). 78In particular, GitHub and GitLab both have preview renderers for .adoc or 79.asciidoc files in repositories, and live preview extensions exist for 80Chrome and Firefox. 81 82However, because of the use of custom Ruby macros in the Vulkan 83Specification toolchain, and the high complexity of the documents and 84toolchain used to generate it, these web tools cannot currently render the 85Specification from source. 86Instead, we generate HTML and PDF versions of the Specification and publish 87them on the Khronos website. 88 89The Asciidoctor toolchain and build process are not addressed by this 90document, which concentrates solely on source documents. 91==== 92 93 94[[introduction-normative]] 95== Normative References 96 97Normative references are references to external documents or resources to 98which documentation authors must comply. 99 100[[acm-references]] 101Association for Computing Machinery. 102_Citation Style and Reference Formats_. 103Retrieved July 27, 2019. 104https://www.acm.org/publications/authors/reference-formatting . 105 106[[iso-8601]] 107International Organization for Standardization. 108_Data elements and interchange formats -- Information interchange -- 109Representation of dates and times_ (2004-12-01). 110https://www.iso.org/standard/40874.html . 111Also see https://www.w3.org/QA/Tips/iso-date for colloquial examples. 112 113[[vulkan-docs]] 114Khronos Vulkan Working Group. 115`KhronosGroup/Vulkan-Docs` project on GitHub (July 5, 2016). 116https://github.com/KhronosGroup/Vulkan-Docs . 117 118[[vulkan-spec]] 119Khronos Vulkan Working Group. 120_Vulkan 1.1.116 - A Specification_ (July 20, 2019). 121https://registry.khronos.org/vulkan/ . 122 123Version 1.1.116 is the latest patch release of the Vulkan API Specification 124as of the time this reference was created, but that Specification is 125frequently updated with minor bugfixes and clarifications. 126When a more recent patch release is made, it becomes the normative reference 127for the API. 128