n-tek / openglreftoman Goto Github PK

# openGLRefToMan

Scripts and patches for creating a Slackware 15.0 installation package from manpages created by conversion of official OpenGL Reference repository.

• Target User and Alternatives
• Building and Installation
  • Requirements
  • Building
  • Installation For Slackware 15.0
  • Installation For Other Distros
• Removal
  • For Slackware 15.0
  • For Other Distros
• Usage
  • From CLI
  • From vim
• Support
• Roadmap
• Code of Conduct
• Contributing
• License
• Project Status

If you would like to have OpenGL API references as manpages this repo probably presents the most readable and extensible solution (if you don't like my edits on various manpages for increasing readability only thing you've to do is adding your version of manpage into the corrected_manpages directory and building by following the steps presented in the following section).

Alternatives that I'm aware of for the presented solution are as follows:

1. A web scraped version of the official API reference repo presented here.

   • Very nice project, can update everything as the official repo gets updated by rebuilding everything, but I need a solution that I could integrate into vim.

2. An Ubuntu package is available named opengl-4-man-doc.

   • Only GL4.1 API and has lots of unreadable pages, could not update manpages as the official repos gets updated.

3. Also Arch-Linux has it's own packaged version as opengl-man-pages.

   • As a Slackware user I cannot use this one but inspired me for the creation of everything presented in this repo.

Manpages can be build for all distros but a removable installation package creation option is only presented for Slackware 15.0.

Operating System: Linux

Distro          : Slackware 15.0 (64-bit x86_64 edition) for removable package creation
                  Others                                 for only raw manpage creation

Shell           : bash          ≥ 5.1.16

Others          : GNU diffutils ≥ 3.8
                                       diff
                  GNU coreutils ≥ 9.0
                                       basename
                                       cp
                                       echo
                                       mkdir
                                       mv
                  GNU patch     ≥ 2.7.6
                  GNU sed       ≥ 4.8
                  man           ≥ 2.9.4
                  gzip          ≥ 1.11
                  git           ≥ 2.35.1
                  unzip         ≥ 6.00
                  xsltproc      compiled against libxml 20910

Manpages will be build as follows:

1. Download or clone the OpenGL repo if you didn't cloned this repo.

2. Check the requirements of the OpenGL repo stated in the file README.adoc and make sure that you've the required software.
   For Slackware64 15.0 you can use following packages:
   * mathML2dtd
   * docbookMathML1mods
   * docbook-xml5

3. By using OpenGLprocessRepo.sh script convert DocBook xml sources to manpages (may take ≥30 minutes).

   All converted manpages will be located under the directory of man3/ in the OpenGL repo's root directory, having following suffixes as gzip archives:

   Description	Repo Directory	Manpage Suffix
   OpenGL ES 1.1 (fixed function)	es1.1	3GLesEarliest
   OpenGL ES 2.0	es2.0	3GLesSecond
   OpenGL ES 3.0	es3.0	3GLesThird
   OpenGL ES 3.1	es3.1	3GLesFourth
   OpenGL ES 3.x (latest ES, currently 3.2)	es3	3GLesLatest
   OpenGL 2.1 (including fixed functionality)	gl2.1	3GLearliest
   OpenGL 4.x (latest GL, currently 4.5)	gl4	3GLlatest

   Manpages under the directory of man3/ can be checked with OpenGLrefViewer.sh before and after patching (Steps 4 and 5).

4. Create a directory to store patch files having '.diff' suffix.

5. Create patch files having '.diff' suffix by using OpenGLcreateManPatches.sh and edited manpage files presented under corrected_manpages/ directory.

6. patch existing manpages using newly created patch files by using OpenGLpatchManPages.sh.

   Following directories will be created in the parent directory of man3/ directory:

   • orig/ stores prepatched manpages as patch backup.
   • patched/ stores copies of patched manpages for checking with viewer.sh.

By using SlackBuild script, slack-desc and doinst.sh file build manpages automatically with the usage of related shell scripts and create a removable package.

Manually install the package.

For detailed package creation and installation info check here.

The user is presented with an option for creation of up-to-date SlackBuild source tarball in scripts/CreateSlackBuildSourceTarball.sh of the source tarball instead of using potentially out-dated SlackBuild source tarball.

As a result of installation newly created patched manpages will be automatically copied into /usr/man/ and whatis database will be automatically updated

Follow the building steps presented previously and manually execute related scripts with required arguments.

Copy man3/ directory to your distro's main manpage directory OR create an installation package for your distro and install it.

Create a backup of your distro's 'whatis' database and update it.

Remove package by using removepkg command as root. For further info check here.

Index database update used by whatis command for clearing deleted OpenGL API reference manpage entries will start automatically after package removal

If manually copied all manpages use the following command: rm -iv *3GL* else check your distro's manual for package removal

Update 'whatis' database of your distro.

• To reach a manpage defined in single API from command-line-interface(CLI) use
  man FUNCTION_NAME.

• To reach a manpage defined in multiple APIs from command-line-interface(CLI) use
  man -a FUNCTION_NAME.

• To reach a manpage defined in a single API from vim use
  :Man FUNCTION_NAME.

• To reach a manpage defined in multiple APIs from vim use
  :Man -a FUNCTION_NAME.

All types of constructive criticisms and contributions are welcome, and I'll try my best for solving your problems related with the scripts and patches presented in this repo as an engineering geologist, a self-learner and a guy who enjoys coding.

For further info please check SUPPORT.md.

Essentially I've created this repo to solve my problem at the first place and I've to admit I really have no idea in the beginning but with time I've learned lots of stuff from the guys and the gals like myself who has tried to solve their problems and decided to share their findings with other individuals who might face similar problems. Remembering all of them individually at this point is a bit hard for me so I've created this repo to show my graditude.

The next thing for this repo might be encouriging users of other distros for creation of a similar packages for their preferred distros

and

entering the listed packages of slackbuilds dot org.

Additional ideas related with the future are welcomed.

Contributor Covenant version 2.1 is the effective code of conduct for this project.

For further info please check CODE_OF_CONDUCT.md.

Please check CONTRIBUTING.md.

Software presented in this repository is licensed with GPLv3.

For further info please check COPYING.

This project is actively maintained by Necib ÇAPAR.