Bug#939999: libvulkan-dev: Please include manpages for all library functions, structs, extensions
On 12.9.2019 0.58, Witold Baryluk wrote: > Package: libvulkan-dev > Version: 1.1.114.0-1 > Followup-For: Bug #93 > > Just a minor update, > > https://www.khronos.org/registry/vulkan/ > > section 'API Reference Pages' says: > > """ In addition to the format published here, it is possible to generate other > formats from the reference page sources, such as PDF or Unix nroff man page > sources. """ > > I couldn't find the nroff generator in the git repo, but maybe I didn't > search well, (maybe it was removed in master head in git?). > > Also, I found out that indeed it is possible, as Arch does ship with vulkan > man > pages: > > > https://aur.archlinux.org/packages/vulkan-man-git/ > > Examples: > > https://manned.org/VkDeviceCreateInfo.3 > https://manned.org/vkCreateGraphicsPipelines.3 > > > Sources (not upstreamed fully yet) are in this forked repo: > https://github.com/Ryp/Vulkan-Docs The repo seems obsolete. Providing manpages belongs upstream, file it there. -- t
Bug#939999: libvulkan-dev: Please include manpages for all library functions, structs, extensions
Package: libvulkan-dev Version: 1.1.114.0-1 Followup-For: Bug #93 Just a minor update, https://www.khronos.org/registry/vulkan/ section 'API Reference Pages' says: """ In addition to the format published here, it is possible to generate other formats from the reference page sources, such as PDF or Unix nroff man page sources. """ I couldn't find the nroff generator in the git repo, but maybe I didn't search well, (maybe it was removed in master head in git?). Also, I found out that indeed it is possible, as Arch does ship with vulkan man pages: https://aur.archlinux.org/packages/vulkan-man-git/ Examples: https://manned.org/VkDeviceCreateInfo.3 https://manned.org/vkCreateGraphicsPipelines.3 Sources (not upstreamed fully yet) are in this forked repo: https://github.com/Ryp/Vulkan-Docs and some diffs can be seen here: https://github.com/KhronosGroup/Vulkan-Docs/compare/master...Ryp:master So, it looks pretty easy. Bulk of the work is done by asciidoctor output plugin, which is part of official upstream asciidoctor: https://asciidoctor.org/docs/user-manual/#man-pages So, there is very little extra work to do beyond maybe adding a small patch to docs, and adding a package. Thank you. -- System Information: Debian Release: bullseye/sid APT prefers testing-debug APT policy: (500, 'testing-debug'), (500, 'testing'), (1, 'experimental') 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
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
