193 lines
7.2 KiB
Plaintext
193 lines
7.2 KiB
Plaintext
// Copyright (c) 2014-2016 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
Vulkan Documentation and Extensions: Procedures and Conventions
|
|
===============================================================
|
|
Jon Leech, Tobias Hector
|
|
include::specversion.txt[]
|
|
:toc2:
|
|
:toclevels: 3
|
|
:max-width: 100
|
|
:numbered:
|
|
:doctype: book
|
|
:imagewidth: 800
|
|
:fullimagewidth: {svgpdf@pdf:scaledwidth="75%":width="800"}
|
|
:cl: :
|
|
|
|
:leveloffset: 1
|
|
|
|
// :icons:
|
|
// :toc-placement: manual
|
|
|
|
<<<<
|
|
|
|
include::copyright-ccby.txt[]
|
|
|
|
<<<<
|
|
|
|
[[introduction]]
|
|
= Introduction
|
|
|
|
This document contains required procedures and conventions when writing specifications for
|
|
new Vulkan APIs, extensions and layers, or related Khronos documentation
|
|
such as white papers and tutorials; or contributing to existing Vulkan
|
|
specifications. These are collectively referred to as _Vulkan Documentation_
|
|
or just _documentation_ below. The primary focus is the API Specification
|
|
and API extensions, although all of the markup and most of the writing style
|
|
is equally applicable to other documentation.
|
|
|
|
The primary purpose is to achieve consistency across the
|
|
API, as well as across all of our source and output documents. Consistency
|
|
makes it easier for developers, editors, reviewers, and users
|
|
of our documentation to understand and modify it.
|
|
|
|
This document is now formally voted on and approved
|
|
by the Vulkan Working Group. This means that unless explicitly stated
|
|
otherwise, the procedures and conventions must be followed
|
|
If you have a strong desire to modify the procedures and conventions,
|
|
such changes must be made through the normal
|
|
Vulkan Working Group processes.
|
|
|
|
|
|
[[introduction-terminology]]
|
|
== Terminology
|
|
|
|
The key words *must*, *must not*, *required*, *shall*, *shall not*,
|
|
*should*, *should not*, *recommend*, *may*, and *optional* in this document
|
|
are to be interpreted as described in RFC 2119 and by the
|
|
Vulkan 1.0 Specification in the ``Terminology'' section.
|
|
|
|
|
|
[[introduction-structure]]
|
|
== Document Structure
|
|
|
|
The style guide is broken into four sections:
|
|
|
|
* <<naming,API Naming Conventions>> - the required rules for choosing names
|
|
of Vulkan identifiers of all types.
|
|
* <<extensions,Extensions and Layers>> - the required procedures
|
|
for creating formal Vulkan extensions and layers.
|
|
* <<markup,Markup Style>> - the required and recommended markup style for
|
|
writing asciidoc and XML source that
|
|
follows consistent formatting and layout guidelines, tags special terms
|
|
and phrases for proper processing by the spec generation tools, etc.
|
|
* <<writing,Writing Style>> - the required and recommended writing style
|
|
for overall and fine-grained structure and
|
|
conventions, normative language use, API naming conventions, common
|
|
words and phrases to use and to avoid, linking and
|
|
cross-referencing, etc.
|
|
|
|
|
|
[[introduction-asciidoc]]
|
|
== Asciidoc Markup
|
|
|
|
Vulkan Documentation is primarily written in Asciidoc, a form of text markup
|
|
language. Asciidoc is documented on its website at http://www.asciidoc.org/.
|
|
|
|
[[userguide]]
|
|
References to the Asciidoc User Guide are to sections in the document at
|
|
http://asciidoc.org/userguide.html .
|
|
|
|
Asciidoc packages are available for Linux, MacOS, and Microsoft Windows,
|
|
together with the other toolchain components required to generate output
|
|
documents corresponding to the markup.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
We are currently using the
|
|
original _asciidoc_ tool. Other tools to process Asciidoc markup, such as
|
|
_asciidoctor_, are also available, but are not currently usable for our
|
|
documents. While asciidoctor supports the basic Asciidoc markup syntax, it
|
|
does not support asciidoc macros, which are used extensively in the
|
|
documentation. We expect to transition from asciidoc to asciidoctor
|
|
eventually. There may be minor effects on markup and if so, we will
|
|
document them at the time of the transition.
|
|
====
|
|
|
|
The asciidoc toolchain and build process are not addressed by this
|
|
document, which concentrates solely on source documents.
|
|
|
|
|
|
[[introduction-normative]]
|
|
== Normative References
|
|
|
|
Normative references are references to external documents or resources to
|
|
which documentation authors must comply.
|
|
|
|
[[KhronosGroup/Vulkan-Docs]]:: Khronos Vulkan Working Group,
|
|
+KhronosGroup/Vulkan-Docs+ project on GitHub,
|
|
https://github.com/KhronosGroup/Vulkan-Docs,
|
|
July 5, 2016.
|
|
|
|
[[Vulkan API Specification]]:: Vulkan Working Group,
|
|
_Vulkan 1.0.19 - A Specification_,
|
|
https://www.khronos.org/registry/vulkan/,
|
|
July 1, 2016.
|
|
|
|
Version 1.0.19 is the latest patch release of the Vulkan API Specification as of the
|
|
time this reference was created, but that Specification is frequently
|
|
updated with minor bugfixes and clarifications. When a more recent patch
|
|
release is made, it becomes the normative reference for the API.
|
|
|
|
|
|
// Chapters of the text are included below
|
|
|
|
include::style/naming.txt[]
|
|
|
|
include::style/extensions.txt[]
|
|
|
|
include::style/markup.txt[]
|
|
|
|
include::style/writing.txt[]
|
|
|
|
|
|
= Still To Be Done
|
|
|
|
* Something about Image formats
|
|
* Something about validation scripts
|
|
* Something about pictures
|
|
* Glossary lists
|
|
* New param/enum macros
|
|
|
|
= Revision History
|
|
|
|
* August 30, 2016 - remove mustnot{cl} and shouldnot{cl} macro definitions,
|
|
which are no longer used in the Specification (internal issue 407).
|
|
* August 29, 2016 - Add spelling and compound word rules (public issue 352).
|
|
* August 23, 2016 - Modify description of specifying extensions in the
|
|
<<extensions,Layers and Extensions>> chapter to refer to the new
|
|
single-branch model for extensions (internal issue 397).
|
|
* July 26, 2016 - Add section describing <<writing-refpages,markup for
|
|
automatic reference page extraction>>.
|
|
* July 18, 2016 - Add examples of function-parameter and structure-member
|
|
markup (based on public issue 286).
|
|
* July 11, 2016 - Change the document title.
|
|
* July 7, 2016 - Rename document, change license to CC BY, clarify required
|
|
and recommended actions, and reserve use of ``normative'' for the
|
|
Specifications.
|
|
* June 26, 2016 - Move Layers and Extensions chapter from Appendix C of the
|
|
Vulkan API Specification and merge content with the naming guide. Put
|
|
extension and naming chapters into their own source files.
|
|
* June 20, 2016 - Add API naming guide.
|
|
* May 22, 2016 - Add markup and image creation rules, after fixing missing
|
|
figure captions for public issue 219.
|
|
* May 1, 2016 - Include feedback from public issues 120 and 190. Use
|
|
consistent conventions for defining structures. Use American rather than
|
|
British spelling conventions.
|
|
* March 12, 2016 - Recommend against "the value of".
|
|
* February 26, 2016 - Replace use of the "maynot{cl}" macro with "may{cl} not".
|
|
* February 16, 2016 - Place asciidoc conversion post-release.
|
|
* February 9, 2016 - Added quotation mark convention.
|
|
* February 1, 2016 - add the Oxford Comma section and issue resolution.
|
|
* January 26, 2016 - add bullet-list style description of command parameters.
|
|
* January 11, 2016 - add ``Numbers in Text'' section from WSI work.
|
|
* December 16, 2015 - Make ``begin / end'' preferred terms to ``start /
|
|
finish''.
|
|
* December 15, 2015 - Make ``implementation'' preferred term instead of
|
|
``system''.
|
|
* December 13, 2015 - Add tlink{cl}/tname{cl} macros for function pointer
|
|
types.
|
|
* December 10, 2015 - Initial release for feedback.
|