Use Markdown for installer and manual docs

.github/workflows/build-mac.yml

@@ -91,6 +91,24 @@ jobs:
         cd iPlug2/Dependencies/IPlug
         ./download-clap-sdks.sh ${{env.CLAP_VER}}
 
+    - name: Install pandoc
+      uses: pandoc/actions/setup@v1
+
+    - name: Install typst
+      uses: typst-community/setup-typst@v5
+
+    - name: Validate installer docs
+      shell: bash
+      run: |
+        set -eo pipefail
+        cd ${{matrix.project}}
+        python3 scripts/prepare_installer_docs.py mac
+        test -f build-mac/installer/resources/license.rtf
+        test -f build-mac/installer/resources/readme-mac.rtf
+        test -f build-mac/installer/resources/intro.rtf
+        test -f "build-mac/manual/${{matrix.project}} manual.pdf"
+        test -f "manual/${{matrix.project}} manual.md"
+
     - name: Build
       shell: bash
       run: |

.github/workflows/build-win.yml

@@ -80,6 +80,25 @@ jobs:
         cd iPlug2/Dependencies/IPlug
         ./download-clap-sdks.sh ${{env.CLAP_VER}}
 
+    - name: Install pandoc
+      uses: pandoc/actions/setup@v1
+
+    - name: Install typst
+      uses: typst-community/setup-typst@v5
+
+    - name: Validate installer docs
+      shell: pwsh
+      run: |
+        $ErrorActionPreference = 'Stop'
+        $PSNativeCommandUseErrorActionPreference = $true
+        cd ${{matrix.project}}
+        python scripts/prepare_installer_docs.py win
+        if (!(Test-Path "build-win\installer-docs\license.txt")) { throw "Missing generated license.txt" }
+        if (!(Test-Path "build-win\installer-docs\readme-win.txt")) { throw "Missing generated readme-win.txt" }
+        if (!(Test-Path "build-win\installer-docs\readme-win-demo.txt")) { throw "Missing generated readme-win-demo.txt" }
+        if (!(Test-Path "build-win\manual\${{matrix.project}} manual.pdf")) { throw "Missing generated manual PDF" }
+        if (!(Test-Path "manual\${{matrix.project}} manual.md")) { throw "Missing Markdown manual" }
+
     - name: Add msbuild to PATH
       uses: microsoft/setup-msbuild@v2
 

.github/workflows/release-native.yml

@@ -51,6 +51,12 @@ jobs:
       with:
         submodules: recursive
 
+    - name: Install pandoc
+      uses: pandoc/actions/setup@v1
+
+    - name: Install typst
+      uses: typst-community/setup-typst@v5
+
     - name: Get VST3 SDK
       run: |
         cd iPlug2/Dependencies/IPlug
@@ -68,7 +74,7 @@ jobs:
       if: matrix.os == 'macOS-latest'
       run: |
         ARCHIVE_NAME=`python3 iPlug2/Scripts/get_archive_name.py ${{env.PROJECT_NAME}} mac full`
-        echo "name=archive_name::$ARCHIVE_NAME" >> $GITHUB_OUTPUT
+        echo "archive_name=$ARCHIVE_NAME" >> $GITHUB_OUTPUT
       shell: bash
 
     - name: Build macOS
@@ -116,7 +122,7 @@ jobs:
       if: matrix.os == 'windows-latest'
       run: |
         ARCHIVE_NAME=`python.exe iPlug2/Scripts/get_archive_name.py ${{env.PROJECT_NAME}} win full`
-        echo "name=archive_name::$ARCHIVE_NAME" >> $GITHUB_OUTPUT
+        echo "archive_name=$ARCHIVE_NAME" >> $GITHUB_OUTPUT
       shell: bash
 
     - name: Build Windows

TemplateProject/README.md

@@ -1,3 +1,7 @@
 # TemplateProject readme
 
 iPlug2 template project
+
+## Distribution docs
+
+Installer text lives in `installer/*.md` and the user manual lives in `manual/TemplateProject manual.md`. The packaging scripts use Pandoc to generate installer-compatible RTF/TXT files and a PDF manual from those Markdown sources during release builds.

TemplateProject/installer/TemplateProject.iss

@@ -14,7 +14,7 @@ SolidCompression=yes
 OutputDir=.\..\build-win\installer
 ArchitecturesInstallIn64BitMode=x64
 OutputBaseFilename=TemplateProject Installer
-LicenseFile=license.rtf
+LicenseFile=..\build-win\installer-docs\license.txt
 SetupLogging=yes
 ShowComponentSizes=no
 ; WizardImageFile=installer_bg-win.bmp
@@ -63,7 +63,7 @@ Source: "..\build-win\TemplateProject.vst3\*.*"; Excludes: "\Contents\x86\*,*.pd
 Source: "..\build-win\TemplateProject.vst3\Desktop.ini"; DestDir: "{cf64}\VST3\TemplateProject.vst3\"; Check: Is64BitInstallMode; Components:vst3_64; Flags: overwritereadonly ignoreversion; Attribs: hidden system;
 Source: "..\build-win\TemplateProject.vst3\PlugIn.ico"; DestDir: "{cf64}\VST3\TemplateProject.vst3\"; Check: Is64BitInstallMode; Components:vst3_64; Flags: overwritereadonly ignoreversion; Attribs: hidden system;
 
-Source: "..\build-win\TemplateProject.clap"; DestDir: {commoncf64}\CLAP\; Check: Is64BitInstallMode; Components:clap_64; Flags: ignoreversion;
+Source: "..\build-win\TemplateProject_x64.clap"; DestDir: {commoncf64}\CLAP\; Check: Is64BitInstallMode; Components:clap_64; Flags: ignoreversion;
 
 ;Source: "..\build-win\aax\bin\TemplateProject.aaxplugin\*.*"; Excludes: "\Contents\x64\*,*.pdb,*.exp,*.lib,*.ilk,*.ico,*.ini"; DestDir: "{cf32}\Avid\Audio\Plug-Ins\TemplateProject.aaxplugin\"; Components:aax_32; Flags: ignoreversion recursesubdirs;
 ;Source: "..\build-win\aax\bin\TemplateProject.aaxplugin\Desktop.ini"; DestDir: "{cf32}\Avid\Audio\Plug-Ins\TemplateProject.aaxplugin\"; Components:aax_32; Flags: overwritereadonly ignoreversion; Attribs: hidden system;
@@ -73,15 +73,15 @@ Source: "..\build-win\TemplateProject.clap"; DestDir: {commoncf64}\CLAP\; Check:
 ;Source: "..\build-win\TemplateProject.aaxplugin\Desktop.ini"; DestDir: "{cf64}\Avid\Audio\Plug-Ins\TemplateProject.aaxplugin\"; Check: Is64BitInstallMode; Components:aax_64; Flags: overwritereadonly ignoreversion; Attribs: hidden system;
 ;Source: "..\build-win\TemplateProject.aaxplugin\PlugIn.ico"; DestDir: "{cf64}\Avid\Audio\Plug-Ins\TemplateProject.aaxplugin\"; Check: Is64BitInstallMode; Components:aax_64; Flags: overwritereadonly ignoreversion; Attribs: hidden system;
 
-Source: "..\manual\TemplateProject manual.pdf"; DestDir: "{app}"
+Source: "..\build-win\manual\TemplateProject manual.pdf"; DestDir: "{app}"
 Source: "changelog.txt"; DestDir: "{app}"
-Source: "readme-win.rtf"; DestDir: "{app}"; DestName: "readme.rtf"; Flags: isreadme
+Source: "..\build-win\installer-docs\readme-win.txt"; DestDir: "{app}"; DestName: "readme.txt"; Flags: isreadme
 
 [Icons]
 Name: "{group}\TemplateProject"; Filename: "{app}\TemplateProject_x64.exe"
 Name: "{group}\User guide"; Filename: "{app}\TemplateProject manual.pdf"
 Name: "{group}\Changelog"; Filename: "{app}\changelog.txt"
-;Name: "{group}\readme"; Filename: "{app}\readme.rtf"
+;Name: "{group}\readme"; Filename: "{app}\readme.txt"
 Name: "{group}\Uninstall TemplateProject"; Filename: "{app}\unins000.exe"
 
 [Code]
@@ -142,4 +142,4 @@ begin
 end;
 
 [UninstallDelete]
-Type: files; Name: "{app}\InstallationLogFile.log"
+Type: files; Name: "{app}\InstallationLogFile.log"

TemplateProject/installer/intro.md

@@ -0,0 +1,7 @@
+# TemplateProject
+
+Thanks for purchasing TemplateProject.
+
+support@acmeinc.com
+
+http://www.acmeinc.com

TemplateProject/installer/license.md

@@ -0,0 +1,37 @@
+# TemplateProject License
+
+**THIS IS A PLACEHOLDER LICENCE PROVIDED WITH IPLUG2**
+
+**IT HAS NO LEGAL BASIS**
+
+**YOU MAY WISH TO CONSULT A LAWYER BEFORE MAKING A LICENCE**
+
+## Caveat
+
+By installing this software you agree to use it at your own risk. The developer cannot be held responsible for any damages caused as a result of its use.
+
+## Distribution
+
+You are not permitted to distribute the software without the developer's permission. This includes, but is not limited to, distribution on magazine covers or software review websites.
+
+## Multiple Installations*
+
+If you purchased this product as an individual, you are licensed to install and use the software on any computer you need to use it on, providing you remove it afterwards if it is a shared machine. If you purchased it as an institution or company, you are licensed to use it on one machine only, and must purchase additional copies for each machine you wish to use it on.
+
+## Upgrades*
+
+If you purchased this product you are entitled to free updates until the next major version number. The developer makes no guarantee that this product will be maintained indefinitely.
+
+## License transfers*
+
+If you purchased this product you may transfer your license to another person. As the original owner you are required to contact the developer with the details of the license transfer, so that the new owner can receive the updates and support attached to the license. Upon transferring a license the original owner must remove any copies from their machines and are no longer permitted to use the software.
+
+TemplateProject is (C) Copyright AcmeInc 2019
+
+http://www.acmeinc.com
+
+VST and VST3 are trademarks of Steinberg Media Technologies GmbH.
+Audio Unit is a trademark of Apple, Inc.
+AAX is a trademark of Avid, Inc.
+
+Applies to full version only, not the demo version.

TemplateProject/installer/readme-mac.md

@@ -0,0 +1,9 @@
+# TemplateProject
+
+The plugins will be installed in your system plugin folders, which will make them available to all user accounts on your computer. The standalone will be installed in the system Applications folder.
+
+If you do not want to install all components, click **Customize** on the **Installation Type** page.
+
+If you experience any problems with TemplateProject, please contact us at:
+
+support@acmeinc.com

TemplateProject/installer/readme-win-demo.md

@@ -0,0 +1,9 @@
+# TemplateProject Demo
+
+Thanks for installing TemplateProject Demo.
+
+The demo version is ready to use, but may include feature limits or periodic reminders.
+
+If you experience any problems with TemplateProject, please contact us at:
+
+support@acmeinc.com

TemplateProject/installer/readme-win.md

@@ -0,0 +1,9 @@
+# TemplateProject
+
+Thanks for installing TemplateProject.
+
+The plugins and standalone application are ready to use.
+
+If you experience any problems with TemplateProject, please contact us at:
+
+support@acmeinc.com

TemplateProject/manual/TemplateProject manual.md

@@ -0,0 +1,5 @@
+# TemplateProject Manual
+
+This is a placeholder manual for TemplateProject.
+
+Replace this file with product documentation before shipping.

TemplateProject/scripts/makedist-mac.sh

@@ -295,7 +295,7 @@ if [ $BUILD_INSTALLER == 1 ]; then
   else
     cp installer/changelog.txt build-mac/installer/
     cp installer/known-issues.txt build-mac/installer/
-    cp "manual/$PLUGIN_NAME manual.pdf" build-mac/installer/
+    cp "build-mac/manual/$PLUGIN_NAME manual.pdf" build-mac/installer/
     hdiutil create build-mac/$ARCHIVE_NAME.dmg -format UDZO -srcfolder build-mac/installer/ -ov -anyowners -volname $PLUGIN_NAME
   fi
 

TemplateProject/scripts/makedist-win.bat

@@ -37,6 +37,11 @@ echo ------------------------------------------------------------------
 echo Updating version numbers ...
 
 call python prepare_resources-win.py %DEMO%
+call python prepare_installer_docs.py win
+if %ERRORLEVEL% neq 0 (
+  echo ERROR: preparing installer docs failed
+  exit /B 1
+)
 call python update_installer-win.py %DEMO%
 
 cd ..\
@@ -105,6 +110,10 @@ echo Making Installer ...
 
   REM :64-Bit-is
   "%ProgramFiles(x86)%\Inno Setup 6\iscc" /Q ".\installer\TemplateProject.iss"
+  if %ERRORLEVEL% neq 0 (
+    echo ERROR: installer build failed
+    exit /B 1
+  )
   REM goto END-is
 
   REM :END-is
@@ -139,4 +148,4 @@ exit /B 1
 :SUCCESS
 echo %ZIP_NAME%
 
-exit /B 0
+exit /B 0