Bug#939999: libvulkan-dev: Please include manpages for all library functions, structs, extensions
Package: libvulkan-dev
Version: 1.1.114.0-1
Severity: wishlist
The upstream do have both a general Vulkan spec text plus all the
functions description, but the functions and structures / types
documentation is also available as "manual pages", i.e.
https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkGetPhysicalDeviceFeatures.html
https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/vkCreateDisplayModeKHR.html
etc.
It can also be found via this page:
https://vulkan.lunarg.com/doc/sdk/1.1.114.0/windows/apispec.html
where they are kind of bundled together.
They already look man-like to me.
These are all generated afaik from common source somewhere, and should be
very easy to generate nroff (or troff/groff) / man files and include in
the package. PS. Make sure they are compressed. man supports .Z, .z and
.gz, and automatically decompresses them. (I have 18380 .gz files in my
/usr/share/man directory, and zero uncompcressed files).
I think this is the source for all these docs, both a specification and
man pages:
https://github.com/KhronosGroup/Vulkan-Docs
It appears that most of the documentation and spec is written in
asciidoctor, and could be transformed to proper format.
I am not sure where exactly the text for this html pages comes from, as
they contain way more descriptions than just what is in the registry
/usr/share/vulkan/registry/vk.xml , which only provide short comments for
each member of struct or argument, but not full documentation and
explanation of semantics, or valid usages. In fact the registry doesn't
provide any comments or descriptions about functions, only about fields
in types (structs).
AFAIK, it would be fine to bundle these man pages in libvulkan-dev
package, without needing separate package.
With possibly separate libvulkan-doc for the full spec text, tutorials
and examples from SDK.
Similar generated docs:
https://devdocs.io/vulkan/
https://vulkan.lunarg.com/doc/view/1.0.30.0/linux/vkspec.chunked/ch04s01.html
Any way, considering how complex and explicit the spec is, with its
number of input, output structs, functions and extensions, it make sense
to have it more accessible from terminal (or other man viewer or IDE that
can link to man pages) quickly without using Internet or Google. ;)
Cheers,
Witold
-- System Information:
Debian Release: bullseye/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Foreign Architectures: i386
Kernel: Linux 5.2.0-2-amd64 (SMP w/32 CPU cores)
Kernel taint flags: TAINT_PROPRIETARY_MODULE, TAINT_OOT_MODULE, TAINT_UNSIGNED_MODULE
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /usr/bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled
Versions of packages libvulkan-dev depends on:
ii libvulkan1 1.1.114.0-1
libvulkan-dev recommends no packages.
libvulkan-dev suggests no packages.
-- no debconf information
Reply to: