├── .gitignore ├── LICENSE ├── Makefile ├── README.md ├── VERSION ├── build.sh ├── example.png └── patches └── Makefile /.gitignore: -------------------------------------------------------------------------------- 1 | # ignored cloned directory 2 | /Vulkan-Docs/ 3 | 4 | # swap files from vim 5 | *.swp 6 | *.swo 7 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 Wasin Thonkaew 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | .PHONY: all clean install purge 2 | 3 | # forward target API version to internal script 4 | SPECV= 5 | 6 | all: 7 | @if [ -z $(SPECV) ]; then \ 8 | echo "Target build is latest spec."; \ 9 | ./build.sh; \ 10 | else \ 11 | echo "Target build spec is $(SPECV)"; \ 12 | ./build.sh $(SPECV); \ 13 | fi; 14 | 15 | clean: 16 | # note: execute bash script in Makefile (remember to use \ and ; at the end) 17 | @if [ -f Vulkan-Docs/Makefile ]; then \ 18 | cd Vulkan-Docs; \ 19 | make clean_onlymanpages; \ 20 | fi; 21 | 22 | install: 23 | @if [ -d Vulkan-Docs/out/man ]; then \ 24 | cd Vulkan-Docs/out/man; \ 25 | cp -p * /usr/local/man/man3/; \ 26 | echo "Installed successfully"; \ 27 | else \ 28 | echo "Do nothing as there is no generated manpages"; \ 29 | fi; 30 | 31 | purge: 32 | rm -rf Vulkan-Docs 33 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # vkdocs-manpages-autogensh 2 | 3 | Auto-generator Vulkan-Docs manpages 4 | Tested mainly on Ubuntu but should works the same on other distros. 5 | Not tested on macOS, and Windows. It would need slightly modifications on top of parameters supplied to each command as it might have different variants. PRs welcome. 6 | 7 | [Vulkan-Docs](https://github.com/KhronosGroup/Vulkan-Docs) has man source files which can be converted into manpages with a few clean-up/reformat ontop but 8 | their decision doesn't include maintaining of manpages generation code in the repo. So in short, it is possible to do it and this project will serve that purpose. 9 | 10 | # Pre-Built Manpages for Downloads 11 | 12 | In case you don't have time or don't want to build it yourself, head over to downstream Vulkan-Docs repository's [release](https://github.com/haxpor/Vulkan-Docs/releases) section, then you can download manpages (either as original `.3` or `.gz` file) as zip file there. Extract it to your system proper location then you're ready to use. 13 | 14 | If you use WSL (Linux subsystem in Windows), recommended to download `.gz` zip file then extract it into `/usr/share/man/man3`. Then execute `sudo mandb` to update and index man pages. 15 | 16 | # Example 17 | 18 | Notice those normative keywords, and **inline code** format. 19 | 20 | ![example man page](example.png) 21 | 22 | # Dependency 23 | 24 | * NodeJS (only if users target to build manpages against `Vulkan-Docs` API version `v1.2.137` or newer) 25 | * Asciidoctor (package name `asciidoctor` on debian-based distro) 26 | 27 | # How To 28 | 29 | ## Build 30 | 31 | * `make` - Build lastest spec release version 32 | * `make SPECV=v1.2.138` - Build a custom spec release version. `SPECV` shorts for spec version. You can get list of spec versions [here](https://github.com/KhronosGroup/Vulkan-Docs/releases). **Note:** For now, all 1.2.x series are built without errors. 33 | 34 | 35 | ## Install 36 | 37 | `make install` 38 | 39 | This will install all generated manpages from `Vulkan-Docs/out/man/` to your `/usr/local/man/man3/`. 40 | 41 | ## Clean 42 | 43 | `make clean` 44 | 45 | This will remove all generated files resulting from `make`. This will only remove generated files inside Vulkan-Docs directory. 46 | It doesn't have any effect to your installed manpages on your system. 47 | 48 | ## Purge 49 | 50 | `make purge` 51 | 52 | This will remove entire directory `Vulkan-Docs`. This is equivalent of manually removing such directory yourself. 53 | 54 | # Behind the scene 55 | 56 | The script will perform the following operations 57 | 58 | * Clone [Vulkan-Docs](https://github.com/KhronosGroup/Vulkan-Docs) into `Vulkan-Docs` then make sure everytime it has the lastet commits and (release) tags. 59 | * (if need) Perform installation of packages from `npm` (NodeJS) 60 | * Make sure the repo is latest 61 | * Start fresh, and checkout a target release tag of per instructed (if not supply via command line's parameter, then it will base on lastest release) 62 | * Inject patch for `Makefile` as seen from `patches/Makefile` without heavily modify original `Makefile` source that much 63 | * Clean `Vulkan-Docs` to ensure freshness on behalf of its `Makefile` 64 | * Build manpages only `Vulkan-Docs` on behalf of its `Makefile` 65 | * Clean or reformat some artifacts as seen from generated manpages 66 | 67 | # Credits 68 | 69 | Thanks to Ryp for his inspiring [PR](https://github.com/KhronosGroup/Vulkan-Docs/pull/839/files) to make manpages generation possible. 70 | The core logic to generate manpage of this project is based on top of that. 71 | 72 | # License 73 | 74 | The script files of this repository **not** include the genereated artifact, man source files, or generated manpages are licensed under [MIT](https://github.com/haxpor/vkdocs-manpages-autogensh/blob/master/LICENSE), Wasin Thonkaew. 75 | 76 | Artifactrs, man source files, or generated manpages (simply, what's inside `Vulkan-Docs` directory) are based on original [Vulkan-Docs's multiple Licenses](https://github.com/KhronosGroup/Vulkan-Docs/blob/master/COPYING.md). 77 | -------------------------------------------------------------------------------- /VERSION: -------------------------------------------------------------------------------- 1 | 0.2 2 | -------------------------------------------------------------------------------- /build.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # Script to pull upstream KhronosGroup/Vulkan-Docs 3 | # This script is intended to be executed from parent Makefile 4 | 5 | ### Section of variable declarations ### 6 | 7 | git_upstream_repo=https://github.com/KhronosGroup/Vulkan-Docs.git 8 | repo_dir=Vulkan-Docs 9 | target_api_version_release= 10 | is_need_fetch_latest_tag_release=0 11 | 12 | ### Section of logic code ### 13 | # check if target api version is supplied, if not we use latest branch 14 | if [ -z $1 ]; then 15 | echo "No target API version supplied." 16 | echo "This will fetch latest release." 17 | is_need_fetch_latest_tag_release=1 18 | fi 19 | 20 | # check if already pulled down upstream repo 21 | # if not clone yet, then do it 22 | if [ ! -d $repo_dir ]; then 23 | echo "Repo directory not exist, cloning ..." 24 | git clone $git_upstream_repo 25 | 26 | # if failed, then shout out error message 27 | if [ $? -ne 0 ]; then 28 | echo "Error cloning upstream repo" 29 | exit 1 30 | fi 31 | fi 32 | 33 | cd $repo_dir 34 | 35 | git reset --hard 36 | git clean -fx 37 | git checkout master 38 | git fetch --all # make sure to get all release branches 39 | git pull origin master 40 | 41 | # install all required nodejs packages locally (as per package.json if exists) 42 | # certain release version especially 1.2.138 includes nodejs as part of dependency, and 43 | # users need to install a few packages as required per package.json states 44 | if [ -f "package.json" ]; then 45 | npm install 46 | if [ $? -ne 0 ]; then 47 | echo "Error from installing required NodeJS packages" 48 | exit 1 49 | fi 50 | fi 51 | 52 | # get the most recent tag release 53 | if [ $is_need_fetch_latest_tag_release -eq 1 ]; then 54 | target_api_version_release=`git tag --list --sort=-committerdate | head -n1` 55 | else 56 | # set from forwarded parameter from parent Makefile 57 | target_api_version_release=$1 58 | fi 59 | 60 | # check if such tag release ever exists 61 | git checkout $target_api_version_release 62 | if [ $? -ne 0 -a $is_need_fetch_latest_tag_release -eq 1 ]; then 63 | echo "No such release for '$target_api_version_release'!" 64 | echo "Cloned repo is possibly corrupted." 65 | echo "Please remove cloned repo directory, then try again." 66 | exit 1 67 | fi 68 | 69 | # inject Makefile's patch to repo's Makefile 70 | cat ../patches/Makefile >> Makefile 71 | 72 | # clean possible generated files only manpages first 73 | make clean_onlymanpages 74 | 75 | # build only manpages 76 | make -j4 onlymanpages 77 | 78 | ## FIXME: a few files will be linted with result of errors, for now we just let it complete. This 79 | ## applies for version 1.1.x. 80 | if [ $? -ne 0 ]; then 81 | echo "Error in making manpages. Some files are failed in building!" 82 | exit 1 83 | fi 84 | 85 | # correct artifacts of generated manpages 86 | ls out/man | grep -e '[vV][kK].*.3' | xargs -I{} sed -i -e 's//\\fB/g' -e 's||\\fR|g' -e 's||\\fI|g' -e 's||\\fR|g' out/man/{}; 87 | ls out/man | grep -e 'PFN.*.3' | xargs -I{} sed -i -e 's//\\fB/g' -e 's||\\fR|g' -e 's||\\fI|g' -e 's||\\fR|g' out/man/{}; 88 | 89 | # show stats result of number of manpages generated 90 | total_files=$(($(ls out/man | grep -e '^[vV][kK].*.3' | wc -l) + $(ls out/man | grep -e '^PFN.*.3' | wc -l))) 91 | echo "Generated in total $total_files manpages" 92 | -------------------------------------------------------------------------------- /example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/haxpor/vkdocs-manpages-autogensh/100584a1bdd2975c1be7d12a1bad1433f6b0b9f8/example.png -------------------------------------------------------------------------------- /patches/Makefile: -------------------------------------------------------------------------------- 1 | 2 | ## additional of manpages generation 3 | # define a new mansources to allow manpages to be generated without errors 4 | MANSOURCES2 = $(CORESOURCES) 5 | onlymanpages: manpages allchecks 6 | 7 | manpages: man/apispec.txt $(GENDEPENDS) 8 | $(MAKE) buildmanpages2 9 | 10 | MANPAGESDIR = $(OUTDIR)/man 11 | MANPAGES = $(MANSOURCES2:$(MANDIR)/%.txt=$(MANPAGESDIR)/%.3) 12 | buildmanpages2: $(MANPAGES) 13 | 14 | $(MANPAGESDIR)/%.3: $(MANDIR)/%.txt $(MANCOPYRIGHT) $(GENINCLUDE) $(GENDEPENDS) 15 | $(QUIET)$(MKDIR) $(MANPAGESDIR) 16 | $(ASCIIDOC) -b manpage $(ADOCOPTS) -d manpage -o $@ $< 17 | 18 | # separate clean target 19 | # to clean generated files from `make onlymanpages` use `make clean_onlymanpages` 20 | # at the root directory of Vulkan-Docs 21 | clean_onlymanpages: 22 | $(QUIET)$(RM) man/apispec.txt $(LOGFILE) man/[Vv][Kk]*.txt man/PFN*.txt 23 | $(QUIET)$(RMRF) $(MANPAGESDIR) 24 | --------------------------------------------------------------------------------