Update VkSwapchainCreateInfoKHR descriptions

- fix `pretransform` and `compositeAlpha`; they are values not bitmasks
- update `imageFormat`, `imageColorSpace`, `imageUsage`  and
`oldSwapchain` to be specific to behavior of this command
- fix broken unintended code block
- move `VK_TRUE` clipping text to correct bullet point
- random tweaks...

doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt

@@ -110,106 +110,110 @@ include::../../api/structs/VkSwapchainCreateInfoKHR.txt[]
   * pname:sType is the type of this structure.
   * pname:pNext is `NULL` or a pointer to an extension-specific structure.
   * pname:flags is a bitmask of elink:VkSwapchainCreateFlagBitsKHR
-    indicating parameters of swapchain creation.
-  * pname:surface is the surface to which the swapchain will present images.
-    The swapchain is associated with pname:surface.
+    indicating parameters of the swapchain creation.
+  * pname:surface is the surface onto which the swapchain will present
+    images.
+    If the creation succeeds, the swapchain becomes associated with
+    pname:surface.
   * pname:minImageCount is the minimum number of presentable images that the
     application needs.
-    The platform will either create the swapchain with at least that many
-    images, or will fail to create the swapchain.
-  * pname:imageFormat is a slink:VkFormat that is valid for swapchains on
-    the specified surface.
-  * pname:imageColorSpace is a slink:VkColorSpaceKHR that is valid for
-    swapchains on the specified surface.
-  * pname:imageExtent is the non-zero size (in pixels) of the swapchain.
-    Behavior is platform-dependent when the image extent does not match the
-    surface's pname:currentExtent as returned by
+    The implementation will either create the swapchain with at least that
+    many images, or it will fail to create the swapchain.
+  * pname:imageFormat is a elink:VkFormat value specifying the format
+    the swapchain image(s) will be created with.
+  * pname:imageColorSpace is a slink:VkColorSpaceKHR value specifying the
+    way the swapchain interprets image data.
+  * pname:imageExtent is the size (in pixels) of the swapchain image(s).
+    The behavior is platform-dependent if the image extent does not match
+    the surface's pname:currentExtent as returned by
     fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR.
 
 [NOTE]
 .Note
 ====
-On some platforms, flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR can
-return in slink:VkSurfaceCapabilitiesKHR a pname:currentExtent that has a
-pname:width and/or pname:height equal to zero.
-This can happen, e.g., while a native window object is minimized.
-In this situation, the native window object may have to be restored from the
-minimized state before a sname:VkSwapchainKHR can be created, because:
-
-  * The pname:minImageExtent and pname:maxImageExtent values returned by
-    flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR may match the
-    pname:currentExtent.
-  * On some platforms, the pname:imageExtent member of
-    sname:VkSwapchainCreateInfoKHR must match the pname:currentExtent
-    returned by flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR.
+During some situations, sname:VkSwapchainKHR cannot: be created because of
+the Valid Usage of the pname:imageExtent parameter.
+
+The flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR may: return in
+slink:VkSurfaceCapabilitiesKHR a pname:currentExtent that has the
+pname:width and/or pname:height equal to 0, or that is less than its
+counterpart in pname:minImageExtent.
+Similarly, pname:maxImageExtent may: also have 0 values for pname:width
+and/or pname:height.
+For example, on some platforms that may: happen while an associated window
+is minimized.
 ====
 
   * pname:imageArrayLayers is the number of views in a multiview/stereo
     surface.
     For non-stereoscopic-3D applications, this value is 1.
-  * pname:imageUsage is a bitmask of elink:VkImageUsageFlagBits, indicating
-    how the application will use the swapchain's presentable images.
-  * pname:imageSharingMode is the sharing mode used for the images of the
+  * pname:imageUsage is a bitmask of elink:VkImageUsageFlagBits describing
+    the intended usage of the (acquired) swapchain images.
+  * pname:imageSharingMode is the sharing mode used for the image(s) of the
     swapchain.
   * pname:queueFamilyIndexCount is the number of queue families having
-    access to the images of the swapchain in case pname:imageSharingMode is
+    access to the image(s) of the swapchain when pname:imageSharingMode is
     ename:VK_SHARING_MODE_CONCURRENT.
   * pname:pQueueFamilyIndices is an array of queue family indices having
-    access to the images of the swapchain in case pname:imageSharingMode is
+    access to the images(s) of the swapchain when pname:imageSharingMode is
     ename:VK_SHARING_MODE_CONCURRENT.
-  * pname:preTransform is a bitmask of elink:VkSurfaceTransformFlagBitsKHR,
+  * pname:preTransform is a elink:VkSurfaceTransformFlagBitsKHR value
     describing the transform, relative to the presentation engine's natural
     orientation, applied to the image content prior to presentation.
     If it does not match the pname:currentTransform value returned by
     fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR, the presentation engine
     will transform the image content as part of the presentation operation.
-  * pname:compositeAlpha is a bitmask of elink:VkCompositeAlphaFlagBitsKHR
+  * pname:compositeAlpha is a elink:VkCompositeAlphaFlagBitsKHR value
     indicating the alpha compositing mode to use when this surface is
     composited together with other surfaces on certain window systems.
   * pname:presentMode is the presentation mode the swapchain will use.
     A swapchain's present mode determines how incoming present requests will
     be processed and queued internally.
   * pname:clipped indicates whether the Vulkan implementation is allowed to
-    discard rendering operations that affect regions of the surface which
+    discard rendering operations that affect regions of the surface that
     are not visible.
   ** If set to ename:VK_TRUE, the presentable images associated with the
      swapchain may: not own all of their pixels.
      Pixels in the presentable images that correspond to regions of the
-     target surface obscured by another window on the desktop or subject to
+     target surface obscured by another window on the desktop, or subject to
      some other clipping mechanism will have undefined content when read
      back.
      Pixel shaders may: not execute for these pixels, and thus any side
-     affects they would have had will not occur.
-  ** If set to ename:VK_FALSE, presentable images associated with the
-     swapchain will own all the pixels they contain.
-     Setting this value to ename:VK_TRUE does not guarantee any clipping
+     effects they would have had will not occur.
+     ename:VK_TRUE value does not guarantee any clipping
      will occur, but allows more optimal presentation methods to be used on
      some platforms.
+  ** If set to ename:VK_FALSE, presentable images associated with the
+     swapchain will own all of the pixels they contain.
 
 [NOTE]
 .Note
 ====
 Applications should: set this value to ename:VK_TRUE if they do not expect
 to read back the content of presentable images before presenting them or
-after reacquiring them and if their pixel shaders do not have any side
+after reacquiring them, and if their pixel shaders do not have any side
 effects that require them to run for all pixels in the presentable image.
 ====
 
-  * pname:oldSwapchain, if not dlink:VK_NULL_HANDLE, specifies an existing
-    non-retired swapchain that is associated with surface.
+  * pname:oldSwapchain is dlink:VK_NULL_HANDLE, or the existing non-retired
+    swapchain currently associated with pname:surface.
+    Providing a valid pname:oldSwapchain may: aid in the resource reuse, and
+    also allows the application to still present any images that are already
+    acquired from it.
+
+Upon calling fname:vkCreateSwapchainKHR with a pname:oldSwapchain that
+is not dlink:VK_NULL_HANDLE, pname:oldSwapchain is retired -- even if
+creation of the new swapchain fails.
+The new swapchain is created in the non-retired state whether or not
+pname:oldSwapchain is dlink:VK_NULL_HANDLE.
+
+Upon calling fname:vkCreateSwapchainKHR with a pname:oldSwapchain that
+is not dlink:VK_NULL_HANDLE, any images from pname:oldSwapchain that are
+not acquired by the application may: be freed by the implementation,
+which may: occur even if creation of the new swapchain fails.
+The application can: destroy pname:oldSwapchain to free all memory
+associated with pname:oldSwapchain.
 
-    Upon calling fname:vkCreateSwapchainKHR with a pname:oldSwapchain that
-    is not dlink:VK_NULL_HANDLE, pname:oldSwapchain is retired, even if
-    creation of the new swapchain fails.
-    The new swapchain is created in the non-retired state whether or not
-    pname:oldSwapchain is dlink:VK_NULL_HANDLE.
-
-    Upon calling fname:vkCreateSwapchainKHR with a pname:oldSwapchain that
-    is not dlink:VK_NULL_HANDLE, any images from pname:oldSwapchain that are
-    not acquired by the application may: be freed by the implementation,
-    which may: occur even if creation of the new swapchain fails.
-    The application must: destroy sname:oldSwapchain to free all memory
-    associated with sname:oldSwapchain.
 [NOTE]
 .Note
 ====