Add man page (#56)

Add initial man page

.github/workflows/make.yml

@@ -17,7 +17,7 @@ jobs:
     - uses: actions/checkout@v4
     - name: Install dependencies
       run: |
-        sudo apt-get install meson shellcheck
+        sudo apt-get install meson shellcheck scdoc
     - name: Initialize submodules
       run: |
         git submodule update --init --recursive

Makefile.in

@@ -7,6 +7,7 @@ PREFIX ?= /usr
 BINDIR := $(PREFIX)/bin
 LIBDIR := $(PREFIX)/lib
 DATADIR := $(PREFIX)/share
+MANDIR ?= $(DATADIR)/man
 
 DESTDIR ?=
 USERINSTALL ?= xfalse
@@ -109,12 +110,20 @@ user-install:
 	$(info :: Installed under user-only location "$(DATADIR)/$(INSTALLDIR)")
 	$(info :: To run you need to make sure "$(BINDIR)" is in your PATH)
 
+ulwgl-docs-install:
+	$(info :: Installing man pages)
+	@mkdir -p $(DESTDIR)$(MANDIR)/man1
+	@mkdir -p $(DESTDIR)$(MANDIR)/man5
+	scdoc < docs/ulwgl.1.scd > $(OBJDIR)/ulwgl.1
+	scdoc < docs/ulwgl.5.scd > $(OBJDIR)/ulwgl.5
+	install -m644 $(OBJDIR)/ulwgl.1 $(DESTDIR)$(MANDIR)/man1/ulwgl.1
+	install -m644 $(OBJDIR)/ulwgl.5 $(DESTDIR)$(MANDIR)/man5/ulwgl.5
 
 .PHONY: install
 ifeq ($(USERINSTALL), xtrue)
-install: reaper-install ulwgl-install ulwgl-launcher-install user-install
+install: reaper-install ulwgl-install ulwgl-launcher-install user-install ulwgl-docs-install
 else
-install: reaper-install ulwgl-install ulwgl-launcher-install
+install: reaper-install ulwgl-install ulwgl-launcher-install ulwgl-docs-install
 endif
 
-# vim: ft=make
+# vim: ft=make

ULWGL/ulwgl_consts.py

@@ -26,16 +26,3 @@ class Color(Enum):
     "getcompatpath",
     "getnativepath",
 }
-
-USAGE = """
-example usage:
-  GAMEID= ulwgl-run /home/foo/example.exe
-  WINEPREFIX= GAMEID= ulwgl-run /home/foo/example.exe
-  WINEPREFIX= GAMEID= PROTONPATH= ulwgl-run /home/foo/example.exe
-  WINEPREFIX= GAMEID= PROTONPATH= ulwgl-run /home/foo/example.exe -opengl
-  WINEPREFIX= GAMEID= PROTONPATH= ulwgl-run ""
-  WINEPREFIX= GAMEID= PROTONPATH= PROTON_VERB= ulwgl-run /home/foo/example.exe
-  WINEPREFIX= GAMEID= PROTONPATH= STORE= ulwgl-run /home/foo/example.exe
-  ULWGL_LOG= GAMEID= ulwgl-run /home/foo/example.exe
-  ulwgl-run --config /home/foo/example.toml
-"""

ULWGL/ulwgl_run.py

@@ -10,7 +10,7 @@
 from re import match
 from subprocess import run
 from ulwgl_dl_util import get_ulwgl_proton
-from ulwgl_consts import PROTON_VERBS, USAGE, DEBUG_FORMAT
+from ulwgl_consts import PROTON_VERBS, DEBUG_FORMAT
 from ulwgl_util import setup_ulwgl
 from ulwgl_log import log, console_handler, Formatter
 from ulwgl_util import UnixUser
@@ -21,10 +21,10 @@ def parse_args() -> Union[Namespace, Tuple[str, List[str]]]:  # noqa: D103
     opt_args: Set[str] = {"--help", "-h", "--config"}
     parser: ArgumentParser = ArgumentParser(
         description="Unified Linux Wine Game Launcher",
-        epilog=USAGE,
+        epilog="See ulwgl(1) for more info and examples.",
         formatter_class=RawTextHelpFormatter,
     )
-    parser.add_argument("--config", help="path to TOML file (requires Python 3.11)")
+    parser.add_argument("--config", help="path to TOML file (requires Python 3.11+)")
 
     if not sys.argv[1:]:
         err: str = "Please see project README.md for more info and examples.\nhttps://github.com/Open-Wine-Components/ULWGL-launcher"

docs/ulwgl.1.scd

@@ -0,0 +1,84 @@
+ulwgl(1)
+
+# NAME
+
+ulwgl-run - Unified Launcher for Windows Games on Linux
+
+# SYNOPSIS
+
+*ulwgl-run* [_OPTIONS_...] [_FILE_ [_ARG_...] | _FILE_]
+
+# OPTIONS
+
+*-h, --help*
+	Show this help message
+
+*--config* <config>
+	Path to TOML configuration file (Requires Python 3.11+)
+
+	See *ulwgl*(5) for more info and examples
+
+# EXAMPLES
+
+```
+# Play a game
+$ WINEPREFIX= GAMEID=0 PROTONPATH= ulwgl-run ~/foo.exe
+```
+
+```
+# Play a game and apply a GOG Protonfix
+# Can be a Steam or non-Steam game
+$ WINEPREFIX= GAMEID=ulwgl-1228964594 PROTONPATH= STORE=gog ulwgl-run ~/foo.exe
+```
+
+```
+# Play a non-Steam game by reading a configuration file
+[ulwgl]
+prefix = "~/.wine"
+proton = "~/GE-Proton30"
+game_id = "0"
+exe = "~/foo.exe"
+launch_args = "-opengl -SkipBuildPatchPrereq"
+store = "gog"
+$ ulwgl-run --config config.toml
+```
+
+```
+# Create a ULWGL WINE prefix
+$ WINEPREFIX=~/foo GAMEID=0 PROTONPATH= ulwgl-run ""
+```
+
+```
+# Play a game and download the latest ULWGL-Proton
+$ WINEPREFIX= GAMEID=0 ulwgl-run foo.exe
+```
+
+```
+# Play a game and automatically set Proton
+# Will first search ~/.local/share/Steam/compatibilitytools.d for latest
+# When a Proton cannot be found, ULWGL-Proton will be downloaded
+$ WINEPREFIX= GAMEID=0 ulwgl-run foo.exe
+```
+
+```
+# Play a game, automatically set Proton and create a prefix
+# This will create the prefix as ~/Games/ULWGL/<ulwgl-$GAMEID>
+$ GAMEID=0 ulwgl-run foo.exe
+```
+
+```
+# Play a game and explicitly set a valid Proton verb
+$ WINEPREFIX= GAMEID=0 PROTONPATH= PROTON_VERB=waitforexitandrun ulwgl-run ~/foo.exe
+```
+
+```
+# Play a game and enable debug logs
+# Valid values include: 1, warn, debug
+$ ULWGL_LOG=1 WINEPREFIX= GAMEID=0 PROTONPATH= ulwgl-run ~/foo.exe
+```
+
+# AUTHORS
+
+Maintained by Open Wine Components members, and assisted by other open source
+contributors. For more information about ULWGL development, see
+https://github.com/Open-Wine-Components/ULWGL-launcher.

docs/ulwgl.5.scd

@@ -0,0 +1,56 @@
+ulwgl(5)
+
+# NAME
+
+ulwgl-run - configuration file
+
+# DESCRIPTION
+
+ulwgl-run can optionally read a configuration file instead of reading
+environment variables set from the command line. The configuration file for
+ulwgl-run must be written in valid Tom's Obvious Minimal Language (TOML).
+
+In the configuration file, the table *ulwgl* is required as well as the keys
+*prefix*, *proton* and *exe* which all must be basic strings. e.g.:
+
+```
+[ulwgl]
+prefix = "~/WINE/epic-games-store"
+exe = "~/EpicGamesLauncher.exe"
+proton = "~/.local/share/Steam/compatibilitytools.d/GE-Proton30"
+```
+
+Afterwards, run the command:
+```
+$ ulwgl-run --config config.toml
+```
+
+# [ulwgl] SECTION
+
+*exe*
+	Path to the game executable to run. Value must be a basic *string*.
+
+*proton*
+	Path to a Proton directory. Value must be a basic *string*.
+
+*prefix*
+	Path to a WINE prefix directory. Value must be a basic *string*.
+
+*game_id*
+	The ULWGL id to assign to the game. Depending on the value assigned, a Proton
+	fix will be applied to the prefix if available. Please refer to the ULWGL
+	database for an extended list of game ids.
+
+*store*
+	The distribution platform of the executable. Value must be a basic *string*.
+	Expects the values: egs, gog, battlenet, amazon, humble, itchio, and ubisoft.
+
+*launch_args*
+	Launch arguments for the executable. Value must be a basic *string*.
+	Assumes each argument is space-separated.
+
+# AUTHORS
+
+Maintained by Open Wine Components members, and assisted by other open source
+contributors. For more information about ULWGL development, see
+https://github.com/Open-Wine-Components/ULWGL-launcher.