Vulkan-Docs/doc/specs/vulkan/styleguide.txt

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

* 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 Github issue 219.
* May 1, 2016 - Include feedback from public Github 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.