Move all man pages to a separate directory

Simplifies processing all around, and makes more sense

.github/actions/get-pages.sh

@@ -4,7 +4,7 @@ usage() {
 	cat <<EOF
 Usage: $0 [-h] [-r] <rgbds-www> <version>
 Copy renders from RGBDS repository to rgbds-www documentation
-Execute from the root folder of the RGBDS repo, checked out at the desired tag
+Execute from the \`man/\` folder in the RGBDS repo, checked out at the desired tag
 <rgbds-www> : Path to the rgbds-www repository
 <version>   : Version to be copied, such as 'v0.4.1' or 'master'
 
@@ -35,37 +35,34 @@ if [ $bad_usage -ne 0 ]; then
 	usage
 	exit 1
 fi
-shift $(($OPTIND - 1))
+shift $((OPTIND - 1))
 
 
-declare -A PAGES
+declare -a PAGES
 PAGES=(
-	[rgbasm.1.html]=src/asm/rgbasm.1
+	rgbasm.1
-	[rgbasm.5.html]=src/asm/rgbasm.5
+	rgbasm.5
-	[rgblink.1.html]=src/link/rgblink.1
+	rgblink.1
-	[rgblink.5.html]=src/link/rgblink.5
+	rgblink.5
-	[rgbfix.1.html]=src/fix/rgbfix.1
+	rgbfix.1
-	[rgbgfx.1.html]=src/gfx/rgbgfx.1
+	rgbgfx.1
-	[rgbds.5.html]=src/rgbds.5
+	rgbds.5
-	[rgbds.7.html]=src/rgbds.7
+	rgbds.7
-	[gbz80.7.html]=src/gbz80.7
+	gbz80.7
 )
 WWWPATH="/docs"
-mkdir -p "$1/_documentation/$2"
+OUTDIR="$1/_documentation/$2"
+mkdir -p "$OUTDIR"
 
 # `mandoc` uses a different format for referring to man pages present in the **current** directory.
 # We want that format for RGBDS man pages, and the other one for the rest;
-# we thus need to copy all pages to a temporary directory, and process them there.
+# this script must thus be run from the directory all man pages are in.
 
-# Copy all pages to current dir
+for page in "${PAGES[@]}"; do
-cp "${PAGES[@]}" .
+manpage="${page%.?}(${page#*.})" # "rgbasm(5)"
+descr="$(awk -v 'FS=.Nd ' '/.Nd/ { print $2; }' "$page")" # "language documentation"
 
-for page in "${!PAGES[@]}"; do
+	cat >"$OUTDIR/$page.html" <<EOF
-stem="${page%.html}"
-manpage="${stem%.?}(${stem#*.})"
-descr="$(awk -v 'FS=.Nd ' '/.Nd/ { print $2; }' "${PAGES[$page]}")"
-
-	cat >"$1/_documentation/$2/$page" <<EOF
 ---
 layout: doc
 title: $manpage [$2]
@@ -73,16 +70,16 @@ description: RGBDS $2 — $descr
 ---
 EOF
 	options=fragment,man='%N.%S;https://linux.die.net/man/%S/%N'
-	if [ $stem = rgbasm.5 ]; then
+	if [[ $page = rgbasm.5 ]]; then
 		options+=,toc
 	fi
-	mandoc -Thtml -I os=Linux -O$options "${PAGES[$page]##*/}" | .github/actions/doc_postproc.awk >> "$1/_documentation/$2/$page"
+	mandoc -W warning -Thtml -I os=Linux -O$options "$page" | ../.github/actions/doc_postproc.awk >> "$OUTDIR/$page.html"
-	groff -Tpdf -mdoc -wall "${PAGES[$page]##*/}" >"$1/_documentation/$2/$stem.pdf"
+	groff -Tpdf -mdoc -wall "$page" >"$OUTDIR/$page.pdf"
-	if [ $is_release -ne 0 ]; then
+	if [[ $is_release -ne 0 ]]; then
-		cat - >"$1/_documentation/$page" <<EOF
+		cat - >"$1/_documentation/$page.html" <<EOF
 ---
-redirect_to: $WWWPATH/$2/${page%.html}
+redirect_to: $WWWPATH/$2/$page
-permalink: $WWWPATH/${page%.html}/
+permalink: $WWWPATH/$page/
 title: $manpage [latest stable]
 description: RGBDS latest stable — $descr
 ---
@@ -90,7 +87,7 @@ EOF
 	fi
 done
 
-cat - >"$1/_documentation/$2/index.html" <<EOF
+cat - >"$OUTDIR/index.html" <<EOF
 ---
 layout: doc_index
 permalink: /docs/$2/
@@ -101,13 +98,9 @@ EOF
 
 
 # If making a release, add a new entry right after `master`
-if [ $is_release -ne 0 ]; then
+if [[ $is_release -ne 0 ]]; then
 	awk '{ print }
-/"name": "master"/ { print "\t\t{\"name\": \"'$2'\",  \"text\": \"'$2'\" }," }
+/"name": "master"/ { print "\t\t{\"name\": \"'"$2"'\",  \"text\": \"'"$2"'\" }," }
 ' "$1/_data/doc.json" >"$1/_data/doc.json.tmp"
 	mv "$1/_data/doc.json"{.tmp,}
 fi
-
-
-# Clean up
-rm "${PAGES[@]##*/}"

.github/workflows/update-master-docs.yml

@@ -5,15 +5,15 @@ on:
       - master
     paths:
       - .github/actions/get-pages.sh
-      - src/gbz80.7
+      - man/gbz80.7
-      - src/rgbds.5
+      - man/rgbds.5
-      - src/rgbds.7
+      - man/rgbds.7
-      - src/asm/rgbasm.1
+      - man/rgbasm.1
-      - src/asm/rgbasm.5
+      - man/rgbasm.5
-      - src/link/rgblink.1
+      - man/rgblink.1
-      - src/link/rgblink.5
+      - man/rgblink.5
-      - src/fix/rgbfix.1
+      - man/rgbfix.1
-      - src/gfx/rgbgfx.1
+      - man/rgbgfx.1
 
 jobs:
   build:
@@ -43,9 +43,9 @@ jobs:
           make
           sudo make install
       - name: Update pages
-        working-directory: rgbds
+        working-directory: rgbds/man
         run: |
-          ./.github/actions/get-pages.sh ../rgbds-www master
+          ../.github/actions/get-pages.sh ../../rgbds-www master
       - name: Push new pages
         working-directory: rgbds-www
         run: |

CMakeLists.txt

@@ -97,3 +97,19 @@ if(CMAKE_BUILD_TYPE STREQUAL "Release")
     message(CHECK_FAIL "no")
   endif()
 endif()
+
+set(MANDIR "share/man")
+set(man1 "man/rgbasm.1"
+         "man/rgbfix.1"
+         "man/rgbgfx.1"
+         "man/rgblink.1")
+set(man5 "man/rgbasm.5"
+         "man/rgblink.5"
+         "man/rgbds.5")
+set(man7 "man/gbz80.7"
+         "man/rgbds.7")
+
+foreach(SECTION "man1" "man5" "man7")
+  set(DEST "${MANDIR}/${SECTION}")
+  install(FILES ${${SECTION}} DESTINATION ${DEST})
+endforeach()

Makefile

@@ -167,15 +167,15 @@ install: all
 	$Qinstall ${STRIP} -m ${BINMODE} rgblink ${DESTDIR}${bindir}/rgblink
 	$Qinstall ${STRIP} -m ${BINMODE} rgbgfx ${DESTDIR}${bindir}/rgbgfx
 	$Qmkdir -p ${DESTDIR}${mandir}/man1 ${DESTDIR}${mandir}/man5 ${DESTDIR}${mandir}/man7
-	$Qinstall -m ${MANMODE} src/rgbds.7 ${DESTDIR}${mandir}/man7/rgbds.7
+	$Qinstall -m ${MANMODE} man/rgbds.7 ${DESTDIR}${mandir}/man7/rgbds.7
-	$Qinstall -m ${MANMODE} src/gbz80.7 ${DESTDIR}${mandir}/man7/gbz80.7
+	$Qinstall -m ${MANMODE} man/gbz80.7 ${DESTDIR}${mandir}/man7/gbz80.7
-	$Qinstall -m ${MANMODE} src/rgbds.5 ${DESTDIR}${mandir}/man5/rgbds.5
+	$Qinstall -m ${MANMODE} man/rgbds.5 ${DESTDIR}${mandir}/man5/rgbds.5
-	$Qinstall -m ${MANMODE} src/asm/rgbasm.1 ${DESTDIR}${mandir}/man1/rgbasm.1
+	$Qinstall -m ${MANMODE} man/rgbasm.1 ${DESTDIR}${mandir}/man1/rgbasm.1
-	$Qinstall -m ${MANMODE} src/asm/rgbasm.5 ${DESTDIR}${mandir}/man5/rgbasm.5
+	$Qinstall -m ${MANMODE} man/rgbasm.5 ${DESTDIR}${mandir}/man5/rgbasm.5
-	$Qinstall -m ${MANMODE} src/fix/rgbfix.1 ${DESTDIR}${mandir}/man1/rgbfix.1
+	$Qinstall -m ${MANMODE} man/rgbfix.1 ${DESTDIR}${mandir}/man1/rgbfix.1
-	$Qinstall -m ${MANMODE} src/link/rgblink.1 ${DESTDIR}${mandir}/man1/rgblink.1
+	$Qinstall -m ${MANMODE} man/rgblink.1 ${DESTDIR}${mandir}/man1/rgblink.1
-	$Qinstall -m ${MANMODE} src/link/rgblink.5 ${DESTDIR}${mandir}/man5/rgblink.5
+	$Qinstall -m ${MANMODE} man/rgblink.5 ${DESTDIR}${mandir}/man5/rgblink.5
-	$Qinstall -m ${MANMODE} src/gfx/rgbgfx.1 ${DESTDIR}${mandir}/man1/rgbgfx.1
+	$Qinstall -m ${MANMODE} man/rgbgfx.1 ${DESTDIR}${mandir}/man1/rgbgfx.1
 
 # Target used to check the coding style of the whole codebase.
 # `extern/` is excluded, as it contains external code that should not be patched

README.rst

@@ -57,6 +57,8 @@ The RGBDS source code file structure somewhat resembles the following:
        │   └── ...
        ├── include/
        │   └── ...
+       ├── man/
+       │   └── ...
        ├── src/
        │   ├── asm/
        │   │   └── ...
@@ -96,7 +98,9 @@ The RGBDS source code file structure somewhat resembles the following:
 
 - ``include/`` - header files for each respective C files in `src`.
 
-- ``src/`` - source code and manual pages for RGBDS.
+- ``man/`` - manual pages.
+
+- ``src/`` - source code of RGBDS.
 
   * Note that the code unique to each RGBDS tool is stored in its respective subdirectory
     (rgbasm -> ``src/asm/``, for example). ``src/extern/`` contains code imported from external sources.

src/CMakeLists.txt

@@ -97,22 +97,6 @@ foreach(PROG "asm" "fix" "gfx" "link")
   install(TARGETS rgb${PROG} RUNTIME DESTINATION bin)
 endforeach()
 
-set(MANDIR "share/man")
-set(man1 "asm/rgbasm.1"
-         "fix/rgbfix.1"
-         "gfx/rgbgfx.1"
-         "link/rgblink.1")
-set(man5 "asm/rgbasm.5"
-         "link/rgblink.5"
-         "rgbds.5")
-set(man7 "gbz80.7"
-         "rgbds.7")
-
-foreach(SECTION "man1" "man5" "man7")
-  set(DEST "${MANDIR}/${SECTION}")
-  install(FILES ${${SECTION}} DESTINATION ${DEST})
-endforeach()
-
 if(LIBPNG_FOUND) # pkg-config
   target_include_directories(rgbgfx PRIVATE ${LIBPNG_INCLUDE_DIRS})
   target_link_directories(rgbgfx PRIVATE ${LIBPNG_LIBRARY_DIRS})