-
Notifications
You must be signed in to change notification settings - Fork 8
/
styleguide.txt
162 lines (120 loc) · 5.33 KB
/
styleguide.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
// Copyright (c) 2014-2021 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/
= ANARI^®^ Documentation and Extensions: Procedures and Conventions
ANARI Working Group
:data-uri:
:icons: font
:toc2:
:toclevels: 3
:max-width: 100
:numbered:
:doctype: book
:imagewidth: 800
:fullimagewidth: width="800"
:cl: :
// Various special / math symbols. This is easier to edit with than Unicode.
include::config/attribs.txt[]
:leveloffset: 1
<<<<
include::copyright-ccby.txt[]
<<<<
[[introduction]]
= Introduction
This document contains required procedures and conventions when writing
specifications for new ANARI APIs, extensions and layers, or related
Khronos^{reg}^ documentation such as white papers and tutorials; or
contributing to existing ANARI specifications.
These are collectively referred to as _ANARI 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 ANARI 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 ANARI Working Group processes.
[[introduction-terminology]]
== Terminology
The key words *must*, *required*, *should*, *recommend*, *may*, and
*optional* in this document are to be interpreted as described in RFC 2119
and by the ANARI 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 ANARI identifiers of all types.
* <<extensions,Extensions>> - the required procedures for creating
formal ANARI core and vendor extensions.
* <<markup,Markup Style>> - the required and recommended markup style for
writing asciidoctor 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]]
== Asciidoctor Markup
ANARI Documentation is primarily written in Asciidoctor, a text markup
language.
We use the command-line asciidoctor client that is actively maintained by
asciidoctor, which is documented on its website at https://asciidoctor.org.
References to the Asciidoctor User Manual are to sections in the document at
https://asciidoctor.org/docs/user-manual/.
Asciidoctor is implemented in Ruby (https://www.ruby-lang.org/), which is
available for Linux, MacOS, and Microsoft Windows.
[NOTE]
.Note
====
There are other implementations of asciidoctor, such as AsciidoctorJ
(https://github.com/asciidoctor/asciidoctorj) and asciidoctor.js
(https://github.com/asciidoctor/asciidoctor.js).
In particular, GitHub and GitLab both have preview renderers for .adoc or
.asciidoc files in repositories, and live preview extensions exist for
Chrome and Firefox.
However, because of the use of custom Ruby macros in the ANARI
Specification toolchain, and the high complexity of the documents and
toolchain used to generate it, these web tools cannot currently render the
Specification from source.
Instead, we generate HTML and PDF versions of the Specification and publish
them on the Khronos website.
The Asciidoctor 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.
[[acm-references]]
Association for Computing Machinery.
_Citation Style and Reference Formats_.
Retrieved July 27, 2019.
https://www.acm.org/publications/authors/reference-formatting .
[[iso-8601]]
International Organization for Standardization.
_Data elements and interchange formats -- Information interchange --
Representation of dates and times_ (2004-12-01).
https://www.iso.org/standard/40874.html .
Also see https://www.w3.org/QA/Tips/iso-date for colloquial examples.
Version 1.0.0 is the latest release of the ANARI 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[]
include::style/misc.txt[]
// Appendices are included below
// include::style/vuid.txt[]
= Revision History
* 2021-07-30 - Initial release for feedback.