From 94b59c35a1547e63a62ac3c6b6e630e2c03b978a Mon Sep 17 00:00:00 2001 From: Petr Kraus Date: Wed, 22 May 2019 13:45:35 +0200 Subject: [PATCH] Fix styleguide links (#965) --- style/extensions.txt | 19 ++++++++++--------- style/naming.txt | 9 +++++---- style/writing.txt | 8 ++++---- styleguide.txt | 12 ++++++------ 4 files changed, 25 insertions(+), 23 deletions(-) diff --git a/style/extensions.txt b/style/extensions.txt index fb047909..22b160c8 100644 --- a/style/extensions.txt +++ b/style/extensions.txt @@ -810,14 +810,15 @@ extensions must define two additional tokens. specification, and is incremented when changes are made. Note that the revision of an extension defined in the Vulkan header files and the revision supported by the Vulkan implementation (the - pname:specVersion field of the slink:VkExtensionProperties structure + pname:specVersion field of the sname:VkExtensionProperties structure corresponding to the extension and returned by one of the - <>) may differ. + link:html/vkspec.html#extendingvulkan-extensions[extension queries]) + may differ. The revision value indicates a patch version of the extension specification, and differences in this version number maintain full compatibility, as defined in the - link:html/vkspec.html#fundamentals-versionnum[API Version Numbers and - Semantics] section of the <>. + link:html/vkspec.html#_compatibility_guarantees_informative[Compatibility Guarantees] + section of the <>. [NOTE] .Note @@ -866,7 +867,7 @@ added to ename:VkObjectType (as defined in the "`Debugging`" section of the identify and track objects of the new type. The new enumeration value must conform to the naming defined in the -<> section. +<> section. In this case, the type's etext:Vk prefix is replaced with the enum prefix etext:VK_OBJECT_TYPE_, and the rest of the handle name is converted as described in that section. @@ -932,7 +933,7 @@ implementations. == Accessing Extension Functions from Programs -flink:vkGetInstanceProcAddr and flink:vkGetDeviceProcAddr can be used in +fname:vkGetInstanceProcAddr and fname:vkGetDeviceProcAddr can be used in order to obtain function pointer addresses for core and extension commands (per the description in the "`Command Function Pointers`" section of the <>). @@ -1004,7 +1005,7 @@ interaction must: be described in the explicit Valid Usage section of the parent structure, rather than the chained structure, and must: be protected by appropriate extension-specific `ifdef` constructs. -For example, a constraint added to the slink:VkImageCreateInfo structure by +For example, a constraint added to the sname:VkImageCreateInfo structure by the presence of two extensions which cannot interact is properly described as: @@ -1020,7 +1021,7 @@ as: \endif::VK_NV_external_memory+VK_KHR_external_memory[] ---- -However, a constraint added to slink:VkBufferCreateInfo by a structure in +However, a constraint added to sname:VkBufferCreateInfo by a structure in the `VK_NV_dedicated_allocation` extension must not be described as part of that structure's valid usage: @@ -1037,7 +1038,7 @@ that structure's valid usage: ---- Instead, define the constraint as part of the parent -slink:VkBufferCreateInfo structure's valid usage: +sname:VkBufferCreateInfo structure's valid usage: [source,asciidoc] .Example Markup diff --git a/style/naming.txt b/style/naming.txt index 1c17860c..40019c57 100644 --- a/style/naming.txt +++ b/style/naming.txt @@ -275,8 +275,9 @@ The queried properties may either be invariant, or they may: change based on application behavior. If the results are not invariant, the lifetime of the results should be clearly described in the command description. -See <> in the specification for more information. +See +link:html/vkspec.html#fundamentals-commandsyntax-results-lifetime[Lifetime of Retrieved Results] +in the specification for more information. These commands fall into two categories from a naming perspective: @@ -487,7 +488,7 @@ typedef struct VkSurfaceFormatKHR { } VkSurfaceFormatKHR; ---- - +[[naming-extension-enumerant-names]] === Extension Enumerant Names Enumerants defined by extensions have the author ID appended to the end of @@ -574,7 +575,7 @@ Mip:: If referred to some associating with a mipmap, such as levels, sampling mode, size, tail images, etc., use "`mip`" as a standalone prefix word, e.g. pname:maxMipLevels, ename:VK_MIP_MODE, etc. - This is analogous to the <> [NOTE] diff --git a/style/writing.txt b/style/writing.txt index 250b7a3e..8a4ed3ca 100644 --- a/style/writing.txt +++ b/style/writing.txt @@ -18,7 +18,7 @@ the "`and`" separating the last item. *Incorrect:* The red, green, blue and alpha components. -Also see http://blog.oxforddictionaries.com/2011/06/oxford-comma/ +Also see https://blog.oxforddictionaries.com/2015/01/21/video-oxford-comma/ === Date Format @@ -43,7 +43,7 @@ Never use ambigious formats such as "`09/12/16`". [[writing-misc-a-an]] === A/An and Markup Macros -Use "`a`" and "`an`" http://www.grammar.com/a-vs-an-when-to-use/[correctly], +Use "`a`" and "`an`" https://www.grammar.com/a-vs-an-when-to-use/[correctly], based on the *sound* of the letter beginning the following word. It is easy to get this wrong when talking about Vulkan API names tagged with @@ -258,7 +258,7 @@ Occasional non-normative explanations can be included in the <>. -[[writing-latexmath]] +[[writing-math]] == Math Markup There is a considerable amount of math in the documentation, ranging from @@ -915,7 +915,7 @@ additional conditional section which is only included when *none* of the relevant extensions are enabled. For example, the relevant part of the -elink:VkDescriptorSetLayoutCreateFlagBits description, whose only value is +ename:VkDescriptorSetLayoutCreateFlagBits description, whose only value is defined by an extension, will look like this: [source,asciidoc,subs=attributes+] diff --git a/styleguide.txt b/styleguide.txt index bb7c66aa..89b4f784 100644 --- a/styleguide.txt +++ b/styleguide.txt @@ -86,10 +86,10 @@ Vulkan Documentation is primarily written in Asciidoc, a form of text markup language. Specifically we're using the version of Asciidoc that is actively maintained by asciidoctor, which is documented on its website at -http://www.asciidoctor.org/. +https://asciidoctor.org. References to the Asciidoctor User Manual are to sections in the document at -http://asciidoctor.org/docs/user-manual/. +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. @@ -113,7 +113,7 @@ which documentation authors must comply. [[iso-8601]] International Organization for Standardization, _Data elements and interchange formats -- Information interchange -- Representation of dates -and times_, http://www.iso.org/iso/catalogue_detail?csnumber=40874, +and times_, https://www.iso.org/standard/40874.html, 2004-12-01. Also see https://www.w3.org/QA/Tips/iso-date for colloquial examples. @@ -122,10 +122,10 @@ Khronos Vulkan Working Group, +KhronosGroup/Vulkan-Docs+ project on GitHub, https://github.com/KhronosGroup/Vulkan-Docs, 2016-07-05. [[vulkan-spec]] -Vulkan Working Group, _Vulkan 1.1.70 - A Specification_, -https://www.khronos.org/registry/vulkan/, 2018-03-07 +Vulkan Working Group, _Vulkan 1.1.108 - A Specification_, +https://www.khronos.org/registry/vulkan/, 2019-05-13 -Version 1.1.70 is the latest patch release of the Vulkan API Specification +Version 1.1.108 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