Merge pull request #294 from davidrg/k95manual

Update the Kermit 95 User Manual for v3.0

.github/actions/load-tools/action.yml

@@ -88,6 +88,9 @@ runs:
         curl -LsS -o zip.zip ${{env.INFOZIP_FTP}}win32/zip300xn.zip
         7z x zip.zip -oinfo-zip
         rm -f zip.zip
+        curl -LsS -o unzip.zip ${{env.INFOZIP_FTP}}win32/unz600xn.exe
+        7z x unzip.zip -oinfo-zip -y
+        rm -f unzip.zip
         curl -LsS -o unzip.zip ${{env.INFOZIP_FTP}}os2/unz600.exe
         7z x unzip.zip -oinfo-zip/os2
         rm -f unzip.zip

.github/workflows/build.yml

@@ -1763,3 +1763,307 @@ jobs:
           cat linux+ssl.txt
           popd
         shell: bash
+
+
+  ##############################################################################
+  # Build the Kermit 95 Manual                                                 #
+  ##############################################################################
+  # A built version of Kermit 95 with REXX support is required to do this, so
+  # we can't do it until after the Build-VisualCxx job has completed as all
+  # the x86 builds have REXX support included
+
+  # This version is for publishing on the internet. HTML files end in .html,
+  # and index.html is the front page of the manual
+  Build-Manual-Web:
+    runs-on: windows-latest
+    # We need at least one artifact from the Build-VisualCxx step but Github
+    needs: Build-VisualCxx
+    steps:
+      - uses: actions/checkout@v4
+      - name: Fetch K95
+        uses: actions/download-artifact@v4
+        with:
+          name: k95-vs2022-x86
+          path: ${{ github.workspace }}\dist
+      - name: Prepare Documentation
+        run: |
+          set root=${{ github.workspace }}
+          call mkdocs.bat /W /D
+        shell: cmd
+        working-directory: ${{ github.workspace }}\doc
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: k95-manual-web
+          path: ${{ github.workspace }}\dist\docs\manual
+          retention-days: 1
+
+  # This is the normal version for distribution with the application. HTML
+  # files end in .htm, index.htm is the front page of the K95 documentation,
+  # and k95manual.htm is the front page of the manual
+  Build-Manual-Dist:
+    runs-on: windows-latest
+    # We need at least one artifact from the Build-VisualCxx step but Github
+    needs: Build-VisualCxx
+    steps:
+      - uses: actions/checkout@v4
+      - name: Fetch K95
+        uses: actions/download-artifact@v4
+        with:
+          name: k95-vs2022-x86
+          path: ${{ github.workspace }}\dist
+      - name: Prepare Documentation
+        run: |
+          set root=${{ github.workspace }}
+          call mkdocs.bat /D
+        shell: cmd
+        working-directory: ${{ github.workspace }}\doc
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: k95-manual-dist
+          path: ${{ github.workspace }}\dist\docs\manual
+          retention-days: 1
+
+  # This is a version for distribution with Kermit 95 for vintage PCs. It's the
+  # same as the normal version above, but doesn't use https:// links. Files
+  # end in .htm, index.htm is the front page of the K95 documentation, and
+  # k95manual.htm is the front page of the manual
+  Build-Manual-Dist-Vintage:
+    runs-on: windows-latest
+    # We need at least one artifact from the Build-VisualCxx step but Github
+    needs: Build-VisualCxx
+    steps:
+      - uses: actions/checkout@v4
+      - name: Fetch K95
+        uses: actions/download-artifact@v4
+        with:
+          name: k95-vs2022-x86
+          path: ${{ github.workspace }}\dist
+      - name: Prepare Documentation
+        run: |
+          set root=${{ github.workspace }}
+          call mkdocs.bat /D /I
+        shell: cmd
+        working-directory: ${{ github.workspace }}\doc
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: k95-manual-dist-vintage
+          path: ${{ github.workspace }}\dist\docs\manual
+          retention-days: 1
+
+  ##############################################################################
+  # Generate final "releasable" artifacts                                      #
+  ##############################################################################
+  # This produces releasable artifacts containing the manual and anything
+  # else that isn't generated as part of the normal build.
+  #
+  # At this time this is limited to the manual. *IF* OpenWatcom supported
+  # ctl3d32 then we'd also insert the OpenWatcom-built dialer here too.
+  #
+  # For x86, x86-64 and arm32 we use the Visual C++ 14.2-built artifacts
+  # as this is newest we can get away with for Windows XP and Windows RT.
+  #
+  # For ARM64 we use the latest compiler (Visual C++ 14.4)
+  #
+  # For IA64 we use the Visual C++ 2010 version (Visual C++ 10.0)
+  #
+  # The results are all k95-${arch}.zip
+  #
+
+  Update-x86-Artifact:
+    runs-on: windows-latest
+    needs: Build-Manual-Dist
+    steps:
+      - name: Fetch K95 x86
+        uses: actions/download-artifact@v4
+        with:
+          name: k95-vs2019-x86
+          path: ${{ github.workspace }}\k95
+      - name: Fetch Manual
+        uses: actions/download-artifact@v4
+        with:
+          name: k95-manual-dist
+          path: ${{ github.workspace }}\k95\docs\manual
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: k95-x86
+          path: ${{ github.workspace }}\k95
+          retention-days: 1
+
+  Update-x86-64-Artifact:
+    runs-on: windows-latest
+    needs: Build-Manual-Dist
+    steps:
+      - name: Fetch K95 x86-64
+        uses: actions/download-artifact@v4
+        with:
+          name: k95-vs2019-x64
+          path: ${{ github.workspace }}\k95
+      - name: Fetch Manual
+        uses: actions/download-artifact@v4
+        with:
+          name: k95-manual-dist
+          path: ${{ github.workspace }}\k95\docs\manual
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: k95-x86-64
+          path: ${{ github.workspace }}\k95
+          retention-days: 7
+
+  Update-arm32-Artifact:
+    runs-on: windows-latest
+    needs: Build-Manual-Dist
+    steps:
+      - name: Fetch K95 arm32
+        uses: actions/download-artifact@v4
+        with:
+          name: k95-vs2022-x64_arm
+          path: ${{ github.workspace }}\k95
+      - name: Fetch Manual
+        uses: actions/download-artifact@v4
+        with:
+          name: k95-manual-dist
+          path: ${{ github.workspace }}\k95\docs\manual
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: k95-arm32
+          path: ${{ github.workspace }}\k95
+          retention-days: 7
+
+  Update-arm64-Artifact:
+    runs-on: windows-latest
+    needs: Build-Manual-Dist
+    steps:
+      - name: Fetch K95 arm32
+        uses: actions/download-artifact@v4
+        with:
+          name: k95-vs2022-x64_arm64
+          path: ${{ github.workspace }}\k95
+      - name: Fetch Manual
+        uses: actions/download-artifact@v4
+        with:
+          name: k95-manual-dist
+          path: ${{ github.workspace }}\k95\docs\manual
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: k95-arm64
+          path: ${{ github.workspace }}\k95
+          retention-days: 7
+
+  Update-ia64-Artifact:
+    runs-on: windows-latest
+    needs: [Build-Manual-Dist, Build-VS2010-PSDK71]
+    steps:
+      - name: Fetch K95 ia64
+        uses: actions/download-artifact@v4
+        with:
+          name: k95-vs2010-ia64
+          path: ${{ github.workspace }}\k95
+      - name: Fetch Manual
+        uses: actions/download-artifact@v4
+        with:
+          name: k95-manual-dist
+          path: ${{ github.workspace }}\k95\docs\manual
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: k95-ia64
+          path: ${{ github.workspace }}\k95
+          retention-days: 7
+
+  Update-os2-Artifact:
+    runs-on: windows-latest
+    needs: [Build-Manual-Dist-Vintage, Build-Open-Watcom]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Load Build Tools
+        uses: "./.github/actions/load-tools"
+        with:
+          nocache: ${{vars.NOCACHE}}
+      - name: Fetch K95 os2 full
+        uses: actions/download-artifact@v4
+        with:
+          name: k2-full-install
+          path: ${{ github.workspace }}\k2-full
+      - name: Fetch K95 os2 mini
+        uses: actions/download-artifact@v4
+        with:
+          name: k2-mini-install
+          path: ${{ github.workspace }}\k2-mini
+      - name: Decompress artifacts
+        run: |         
+          cd ${{ github.workspace }}\k2-full
+          ${{ github.workspace }}\info-zip\unzip k2pack.exe
+          del k2pack.exe
+          cd ${{ github.workspace }}\k2-mini
+          ${{ github.workspace }}\info-zip\unzip k2pack.exe
+          del k2pack.exe
+        shell: cmd
+      - name: Fetch Manual - Mini
+        uses: actions/download-artifact@v4
+        with:
+          name: k95-manual-dist-vintage
+          path: ${{ github.workspace }}\k2-mini\docs\manual
+      - name: Fetch Manual - Full
+        uses: actions/download-artifact@v4
+        with:
+          name: k95-manual-dist-vintage
+          path: ${{ github.workspace }}\k2-full\docs\manual
+      - name: Compress artifacts
+        run: |
+          echo :: Create Directories
+          mkdir ${{ github.workspace }}\dist-mini
+          mkdir ${{ github.workspace }}\dist-full
+          
+          echo :: Repack K2-FULL
+          cd ${{ github.workspace }}\k2-full
+          ${{ github.workspace }}\info-zip\zip.exe -r -5 -v -o k2pack * -x setup.exe
+          copy /b ${{ github.workspace }}\info-zip\os2\unzipsfx.exe + k2pack.zip K2PACK.EXE
+          
+          echo :: Repack K2-MINI
+          cd ${{ github.workspace }}\k2-mini
+          ${{ github.workspace }}\info-zip\zip.exe -r -5 -v -o k2pack * -x setup.exe
+          copy /b ${{ github.workspace }}\info-zip\os2\unzipsfx.exe + k2pack.zip K2PACK.EXE
+          
+          echo :: Prepare DIST-MINI
+          cd ${{ github.workspace }}\dist-mini
+          copy ${{ github.workspace }}\k2-mini\setup.exe
+          copy ${{ github.workspace }}\k2-mini\K2PACK.exe
+          
+          echo :: Prepare DIST-FULL
+          cd ${{ github.workspace }}\dist-full
+          copy ${{ github.workspace }}\k2-full\setup.exe
+          copy ${{ github.workspace }}\k2-full\K2PACK.exe
+        shell: cmd
+
+      - name: Delete old full artifact
+        uses: geekyeggo/delete-artifact@v5
+        with:
+          name: k2-full-install
+
+      - name: Delete old mini artifact
+        uses: geekyeggo/delete-artifact@v5
+        with:
+          name: k2-mini-install
+
+      - name: Upload Full Installer Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: k2-full-install
+          path: ${{github.workspace}}/dist-full
+          if-no-files-found: error
+          retention-days: 7
+
+      - name: Upload Minimal Installer Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: k2-mini-install
+          path: ${{github.workspace}}/dist-mini
+          if-no-files-found: error
+          retention-days: 7

doc/README.md

@@ -0,0 +1,79 @@
+Kermit 95 Documentation Index
+==============================
+This directory contains documentation for Kermit 95:
+
+* [Change Log](changes.md)
+* [SSH Readme](ssh-readme.md)
+* [The User Manual](#the-user-manual)
+* Build instructions
+  * [Supported Compilers](compilers.md)
+  * [Building for Windows with Visual C++ or Open Watcom](building.md)
+  * [Building for OS/2 with Open Watcom](os2-building.md)
+  * [Building for Windows with MinGW](mingw-building.md)
+  * [Optional Dependencies](optional-dependencies.md)
+  * [Source code index](code-index.md)
+  * [Build Flags](build-flags.md)
+
+The User Manual
+---------------
+The [manual](manual) directory contains the Kermit 95 User Manual. This was
+originally a printed booklet and a collection of text files until Kermit 95
+v1.1.17 of June 1998 when it was converted into HTML 1.0 format and updated with
+each release.
+
+With the cancellation of the Kermit Project in 2011, Manning Publications
+assigned the copyright back to Columbia University and in March 2011 Frank da
+Cruz updated it for the web and [put it online](http://www.columbia.edu/kermit/k95manual/).
+In July 2024 Frank gave permission to add the manual to the git repo and sent
+through the version that was on kermitproject.org at the time. This has now
+been revised for the new open-source Kermit 95.
+
+To make keeping it up-to-date, the various version numbers, release dates, and
+last modified dates scattered around the place have been updated with tags to
+allow them to be updated with a script. That script is 
+mkdocs.bat/mkdocs.ksc/mkdocs.rex.
+
+### Building the Manual
+
+The manual can be built in one of two ways:
+* For the web: HTML files end in `.html`, and `index.html` is the main page of
+  the manual. This is just like [the online version](http://www.columbia.edu/kermit/k95manual/).
+* For distribution *with* Kermit 95. HTML files end in `.htm` for better
+  compatibility with vintage computers, `index.html` is an index to the offline
+  documentation shipped with Kermit 95, and `kermit95.html` is the main page of
+  the manual. Can optionally be built with insecure (http:// rather than 
+  https://) links to kermitproject.org for better compatibility with older 
+  browsers
+
+To build the manual you must:
+* Be in the K95 build environment (have run `setenv.bat`)
+* Have built the Kermit 95 distribution (run `mkdist.bat`)
+* Have built the Kermit 95 distribution for A CPU architecture compatible with
+  the computer you're building it on (if you're on an x86 machine, you've got
+  to build Kermit 95 for x86 or x86-64 in order to build the manual) as building
+  the manual involves running the freshly built version of Kermit 95.
+* Kermit 95 must be built with REXX support, and must include the regutil and
+  rexxre external function libraries.
+
+The reason for the above requirements is that Kermit 95 is used to build the
+manual, and version numbers and build dates from the version of Kermit 95 being
+used will be injected into the manual.
+
+To build the manual for the web (note the output path must end with a `\`):
+```batch
+mkdocs.bat /W
+```
+
+To build the manual for distribution with K95:
+```batch
+mkdocs.bat
+```
+
+To build the manual for distribution with K95 on vintage computers (fewer 
+https links):
+```batch
+mkdocs.bat /I
+```
+
+Regardless of how you build it, the manual will end up in the dist directory, 
+under `\docs\manual`