docs: Restructure sources and touch up compile.xml script

.github/workflows/build.yml

@@ -265,9 +265,7 @@ jobs:
           meson setup build \
             -Dbuild-tests=true \
             -Denable-macos=true \
-            -Dwith-bdb=/opt/homebrew/opt/berkeley-db \
-            -Dwith-ssl-dir=/opt/homebrew/opt/libressl \
-            -Denable-macos=true
+            -Dwith-bdb=/opt/homebrew/opt/berkeley-db
       - name: Meson - Build
         run: ninja -C build
       - name: Meson - Tests

configure.ac

@@ -1162,7 +1162,7 @@ AC_CONFIG_FILES([Makefile
 	doc/man.xsl
 	doc/manual/Makefile
 	doc/manual/manual.xml
-	doc/manual/netatalk.html
+	doc/manual/pageheader.txt
 	doc/manpages/Makefile
 	doc/manpages/man1/Makefile
 	doc/manpages/man3/Makefile

doc/manual/generate_compile_docs.py → doc/generate_compile_docs.py

@@ -2,54 +2,60 @@
 
 # This script generates the compile.xml manual page from the GitHub build.yml file.
 
+import datetime
 import re
-import yaml
 import xmltodict
+import yaml
+
+now = datetime.datetime.now()
+date_time = now.strftime("%Y-%m-%d")
+
+lang_en = {
+  "title_1": "Compile Netatalk from Source",
+  "title_2": "Overview",
+  "title_3": "Operating Systems",
+  "heading_1": "Install required packages",
+  "heading_2": "Configure and build",
+  "para_1": "This appendix describes how to compile Netatalk from source for specific operating systems.",
+  "para_2": "Please note that the steps below are automatically generated, and may not be optimized for your system.",
+  "para_3": "Choose one of the build systems: Autotools or Meson. Test steps are optional.",
+}
+
+output_en = "./manual/compile.xml"
 
-def main():
-  with open('../../.github/workflows/build.yml', 'r') as file:
-    workflow = yaml.safe_load(file)
+with open('../.github/workflows/build.yml', 'r') as file:
+  workflow = yaml.safe_load(file)
 
-  apt_packages_pattern = r'\$\{\{\senv\.APT_PACKAGES\s\}\}'
-  apt_packages = workflow["env"]["APT_PACKAGES"]
+apt_packages_pattern = r'\$\{\{\senv\.APT_PACKAGES\s\}\}'
+apt_packages = workflow["env"]["APT_PACKAGES"]
 
+def generate_docbook(strings, output_file):
   docbook = {
     "appendix": {
       "@id": "compile",
-      "title": "Compile Netatalk from Source",
+      "appendixinfo": [
+        {
+          "pubdate": date_time
+        },
+      ],
+      "title": strings["title_1"],
       "sect1": [
         {
           "@id": "compile-overview",
-          "title": "Overview",
+          "title": strings["title_2"],
         },
         {
           "para": [
-            """
-            This section describes how to compile Netatalk from source for specific operating systems.
-            """,
-            """
-            The Netatalk project is in the process of transitioning the build system
-            from GNU Autotools to Meson.
-            During the transitional period,
-            the documentation will contain both Autotools and Meson build instructions.
-            """,
-            """
-            Please note that this document is automatically generated from the GitHub workflow YAML file.
-            This may or may not be the most optimal way to build Netatalk for your system.
-            """,
+            strings["para_1"],
+            strings["para_2"],
+            strings["para_3"],
           ],
         },
         {
           "@id": "compile-os",
-          "title": "Operating Systems",
+          "title": strings["title_3"],
         },
         {
-          "para": [
-            """
-            Note: You only have to use execute the steps for one of the build systems, not both.
-            Additionally, the test steps are entirely optional for compiling from source.
-            """,
-          ],
           "sect2": [],
         }
       ],
@@ -58,7 +64,7 @@ def main():
 
   for key, value in workflow["jobs"].items():
     sections = {}
-    # Skip the SonarQube job
+    # Skip the SonarCloud job
     if value["name"] != "Static Analysis":
       sections["@id"] = key
       sections["title"] = value["name"]
@@ -76,9 +82,9 @@ def main():
 
         # The vmactions jobs have a different structure
         if "uses" in step and step["uses"].startswith("vmactions/"):
-          para.append("Install dependencies")
+          para.append(strings["heading_1"])
           para.append({"screen": step["with"]["prepare"]})
-          para.append("Configure and build")
+          para.append(strings["heading_2"])
           para.append({"screen": step["with"]["run"]})
         else:
           para.append(step["name"])
@@ -90,10 +96,9 @@ def main():
 
   xml = xmltodict.unparse(docbook, pretty=True)
 
-  with open('compile.xml', 'w') as file:
+  with open(output_file, 'w') as file:
     file.write(xml)
 
-  print("Wrote compile.xml")
+  print("Wrote to " + output_file)
 
-if __name__ == '__main__':
-    main()
+generate_docbook(lang_en, output_en)

doc/html.xsl.in

@@ -9,7 +9,7 @@
 	<xsl:param name="toc.max.depth" select="2"/>
 
 	<xsl:template name="user.header.navigation">
-		<xsl:variable name="codefile" select="document('netatalk.html',/)"/>
+		<xsl:variable name="codefile" select="document('pageheader.txt',/)"/>
 		<xsl:copy-of select="$codefile/*/node()"/>
 	</xsl:template>
 </xsl:stylesheet>

doc/manual/.gitignore

@@ -1,3 +1,3 @@
 manual.xml
-netatalk.html
+pageheader.txt
 *.html

doc/manual/Makefile.am

@@ -19,7 +19,7 @@ EXTRA_DIST = \
 	install.xml \
 	intro.xml \
 	manual.xml.in \
-	netatalk.html.in \
+	pageheader.txt.in \
 	upgrade.xml
 
 HTML_PAGES = \
@@ -70,7 +70,7 @@ HTML_PAGES = \
 	uniconv.1.html \
 	upgrade.html
 
-DISTCLEANFILES = manual.xml natatalk.html
+DISTCLEANFILES = manual.xml pageheader.txt
 
 if HAVE_XSLTPROC
 CLEANFILES += $(HTML_PAGES)

doc/manual/meson.build

@@ -4,9 +4,9 @@ manual_xml = configure_file(
     configuration: cdata,
 )
 
-netatalk_html = configure_file(
-    input: 'netatalk.html.in',
-    output: 'netatalk.html',
+pageheader = configure_file(
+    input: 'pageheader.txt.in',
+    output: 'pageheader.txt',
     configuration: cdata,
 )