Skip to content

Commit 46f9257

Browse files
davidrgdavidrg
authored
Merge pull request #294 from davidrg/k95manual
Update the Kermit 95 User Manual for v3.0
2 parents 5e2d09b + 5ef6f88 commit 46f9257

File tree

199 files changed

+95615
-94
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

199 files changed

+95615
-94
lines changed

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

+3
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,9 @@ runs:
8888
curl -LsS -o zip.zip ${{env.INFOZIP_FTP}}win32/zip300xn.zip
8989
7z x zip.zip -oinfo-zip
9090
rm -f zip.zip
91+
curl -LsS -o unzip.zip ${{env.INFOZIP_FTP}}win32/unz600xn.exe
92+
7z x unzip.zip -oinfo-zip -y
93+
rm -f unzip.zip
9194
curl -LsS -o unzip.zip ${{env.INFOZIP_FTP}}os2/unz600.exe
9295
7z x unzip.zip -oinfo-zip/os2
9396
rm -f unzip.zip

‎.github/workflows/build.yml

+304
Original file line numberDiff line numberDiff line change
@@ -1763,3 +1763,307 @@ jobs:
17631763
cat linux+ssl.txt
17641764
popd
17651765
shell: bash
1766+
1767+
1768+
##############################################################################
1769+
# Build the Kermit 95 Manual #
1770+
##############################################################################
1771+
# A built version of Kermit 95 with REXX support is required to do this, so
1772+
# we can't do it until after the Build-VisualCxx job has completed as all
1773+
# the x86 builds have REXX support included
1774+
1775+
# This version is for publishing on the internet. HTML files end in .html,
1776+
# and index.html is the front page of the manual
1777+
Build-Manual-Web:
1778+
runs-on: windows-latest
1779+
# We need at least one artifact from the Build-VisualCxx step but Github
1780+
needs: Build-VisualCxx
1781+
steps:
1782+
- uses: actions/checkout@v4
1783+
- name: Fetch K95
1784+
uses: actions/download-artifact@v4
1785+
with:
1786+
name: k95-vs2022-x86
1787+
path: ${{ github.workspace }}\dist
1788+
- name: Prepare Documentation
1789+
run: |
1790+
set root=${{ github.workspace }}
1791+
call mkdocs.bat /W /D
1792+
shell: cmd
1793+
working-directory: ${{ github.workspace }}\doc
1794+
- name: Upload artifact
1795+
uses: actions/upload-artifact@v4
1796+
with:
1797+
name: k95-manual-web
1798+
path: ${{ github.workspace }}\dist\docs\manual
1799+
retention-days: 1
1800+
1801+
# This is the normal version for distribution with the application. HTML
1802+
# files end in .htm, index.htm is the front page of the K95 documentation,
1803+
# and k95manual.htm is the front page of the manual
1804+
Build-Manual-Dist:
1805+
runs-on: windows-latest
1806+
# We need at least one artifact from the Build-VisualCxx step but Github
1807+
needs: Build-VisualCxx
1808+
steps:
1809+
- uses: actions/checkout@v4
1810+
- name: Fetch K95
1811+
uses: actions/download-artifact@v4
1812+
with:
1813+
name: k95-vs2022-x86
1814+
path: ${{ github.workspace }}\dist
1815+
- name: Prepare Documentation
1816+
run: |
1817+
set root=${{ github.workspace }}
1818+
call mkdocs.bat /D
1819+
shell: cmd
1820+
working-directory: ${{ github.workspace }}\doc
1821+
- name: Upload artifact
1822+
uses: actions/upload-artifact@v4
1823+
with:
1824+
name: k95-manual-dist
1825+
path: ${{ github.workspace }}\dist\docs\manual
1826+
retention-days: 1
1827+
1828+
# This is a version for distribution with Kermit 95 for vintage PCs. It's the
1829+
# same as the normal version above, but doesn't use https:// links. Files
1830+
# end in .htm, index.htm is the front page of the K95 documentation, and
1831+
# k95manual.htm is the front page of the manual
1832+
Build-Manual-Dist-Vintage:
1833+
runs-on: windows-latest
1834+
# We need at least one artifact from the Build-VisualCxx step but Github
1835+
needs: Build-VisualCxx
1836+
steps:
1837+
- uses: actions/checkout@v4
1838+
- name: Fetch K95
1839+
uses: actions/download-artifact@v4
1840+
with:
1841+
name: k95-vs2022-x86
1842+
path: ${{ github.workspace }}\dist
1843+
- name: Prepare Documentation
1844+
run: |
1845+
set root=${{ github.workspace }}
1846+
call mkdocs.bat /D /I
1847+
shell: cmd
1848+
working-directory: ${{ github.workspace }}\doc
1849+
- name: Upload artifact
1850+
uses: actions/upload-artifact@v4
1851+
with:
1852+
name: k95-manual-dist-vintage
1853+
path: ${{ github.workspace }}\dist\docs\manual
1854+
retention-days: 1
1855+
1856+
##############################################################################
1857+
# Generate final "releasable" artifacts #
1858+
##############################################################################
1859+
# This produces releasable artifacts containing the manual and anything
1860+
# else that isn't generated as part of the normal build.
1861+
#
1862+
# At this time this is limited to the manual. *IF* OpenWatcom supported
1863+
# ctl3d32 then we'd also insert the OpenWatcom-built dialer here too.
1864+
#
1865+
# For x86, x86-64 and arm32 we use the Visual C++ 14.2-built artifacts
1866+
# as this is newest we can get away with for Windows XP and Windows RT.
1867+
#
1868+
# For ARM64 we use the latest compiler (Visual C++ 14.4)
1869+
#
1870+
# For IA64 we use the Visual C++ 2010 version (Visual C++ 10.0)
1871+
#
1872+
# The results are all k95-${arch}.zip
1873+
#
1874+
1875+
Update-x86-Artifact:
1876+
runs-on: windows-latest
1877+
needs: Build-Manual-Dist
1878+
steps:
1879+
- name: Fetch K95 x86
1880+
uses: actions/download-artifact@v4
1881+
with:
1882+
name: k95-vs2019-x86
1883+
path: ${{ github.workspace }}\k95
1884+
- name: Fetch Manual
1885+
uses: actions/download-artifact@v4
1886+
with:
1887+
name: k95-manual-dist
1888+
path: ${{ github.workspace }}\k95\docs\manual
1889+
- name: Upload artifact
1890+
uses: actions/upload-artifact@v4
1891+
with:
1892+
name: k95-x86
1893+
path: ${{ github.workspace }}\k95
1894+
retention-days: 1
1895+
1896+
Update-x86-64-Artifact:
1897+
runs-on: windows-latest
1898+
needs: Build-Manual-Dist
1899+
steps:
1900+
- name: Fetch K95 x86-64
1901+
uses: actions/download-artifact@v4
1902+
with:
1903+
name: k95-vs2019-x64
1904+
path: ${{ github.workspace }}\k95
1905+
- name: Fetch Manual
1906+
uses: actions/download-artifact@v4
1907+
with:
1908+
name: k95-manual-dist
1909+
path: ${{ github.workspace }}\k95\docs\manual
1910+
- name: Upload artifact
1911+
uses: actions/upload-artifact@v4
1912+
with:
1913+
name: k95-x86-64
1914+
path: ${{ github.workspace }}\k95
1915+
retention-days: 7
1916+
1917+
Update-arm32-Artifact:
1918+
runs-on: windows-latest
1919+
needs: Build-Manual-Dist
1920+
steps:
1921+
- name: Fetch K95 arm32
1922+
uses: actions/download-artifact@v4
1923+
with:
1924+
name: k95-vs2022-x64_arm
1925+
path: ${{ github.workspace }}\k95
1926+
- name: Fetch Manual
1927+
uses: actions/download-artifact@v4
1928+
with:
1929+
name: k95-manual-dist
1930+
path: ${{ github.workspace }}\k95\docs\manual
1931+
- name: Upload artifact
1932+
uses: actions/upload-artifact@v4
1933+
with:
1934+
name: k95-arm32
1935+
path: ${{ github.workspace }}\k95
1936+
retention-days: 7
1937+
1938+
Update-arm64-Artifact:
1939+
runs-on: windows-latest
1940+
needs: Build-Manual-Dist
1941+
steps:
1942+
- name: Fetch K95 arm32
1943+
uses: actions/download-artifact@v4
1944+
with:
1945+
name: k95-vs2022-x64_arm64
1946+
path: ${{ github.workspace }}\k95
1947+
- name: Fetch Manual
1948+
uses: actions/download-artifact@v4
1949+
with:
1950+
name: k95-manual-dist
1951+
path: ${{ github.workspace }}\k95\docs\manual
1952+
- name: Upload artifact
1953+
uses: actions/upload-artifact@v4
1954+
with:
1955+
name: k95-arm64
1956+
path: ${{ github.workspace }}\k95
1957+
retention-days: 7
1958+
1959+
Update-ia64-Artifact:
1960+
runs-on: windows-latest
1961+
needs: [Build-Manual-Dist, Build-VS2010-PSDK71]
1962+
steps:
1963+
- name: Fetch K95 ia64
1964+
uses: actions/download-artifact@v4
1965+
with:
1966+
name: k95-vs2010-ia64
1967+
path: ${{ github.workspace }}\k95
1968+
- name: Fetch Manual
1969+
uses: actions/download-artifact@v4
1970+
with:
1971+
name: k95-manual-dist
1972+
path: ${{ github.workspace }}\k95\docs\manual
1973+
- name: Upload artifact
1974+
uses: actions/upload-artifact@v4
1975+
with:
1976+
name: k95-ia64
1977+
path: ${{ github.workspace }}\k95
1978+
retention-days: 7
1979+
1980+
Update-os2-Artifact:
1981+
runs-on: windows-latest
1982+
needs: [Build-Manual-Dist-Vintage, Build-Open-Watcom]
1983+
steps:
1984+
- uses: actions/checkout@v4
1985+
- name: Load Build Tools
1986+
uses: "./.github/actions/load-tools"
1987+
with:
1988+
nocache: ${{vars.NOCACHE}}
1989+
- name: Fetch K95 os2 full
1990+
uses: actions/download-artifact@v4
1991+
with:
1992+
name: k2-full-install
1993+
path: ${{ github.workspace }}\k2-full
1994+
- name: Fetch K95 os2 mini
1995+
uses: actions/download-artifact@v4
1996+
with:
1997+
name: k2-mini-install
1998+
path: ${{ github.workspace }}\k2-mini
1999+
- name: Decompress artifacts
2000+
run: |
2001+
cd ${{ github.workspace }}\k2-full
2002+
${{ github.workspace }}\info-zip\unzip k2pack.exe
2003+
del k2pack.exe
2004+
cd ${{ github.workspace }}\k2-mini
2005+
${{ github.workspace }}\info-zip\unzip k2pack.exe
2006+
del k2pack.exe
2007+
shell: cmd
2008+
- name: Fetch Manual - Mini
2009+
uses: actions/download-artifact@v4
2010+
with:
2011+
name: k95-manual-dist-vintage
2012+
path: ${{ github.workspace }}\k2-mini\docs\manual
2013+
- name: Fetch Manual - Full
2014+
uses: actions/download-artifact@v4
2015+
with:
2016+
name: k95-manual-dist-vintage
2017+
path: ${{ github.workspace }}\k2-full\docs\manual
2018+
- name: Compress artifacts
2019+
run: |
2020+
echo :: Create Directories
2021+
mkdir ${{ github.workspace }}\dist-mini
2022+
mkdir ${{ github.workspace }}\dist-full
2023+
2024+
echo :: Repack K2-FULL
2025+
cd ${{ github.workspace }}\k2-full
2026+
${{ github.workspace }}\info-zip\zip.exe -r -5 -v -o k2pack * -x setup.exe
2027+
copy /b ${{ github.workspace }}\info-zip\os2\unzipsfx.exe + k2pack.zip K2PACK.EXE
2028+
2029+
echo :: Repack K2-MINI
2030+
cd ${{ github.workspace }}\k2-mini
2031+
${{ github.workspace }}\info-zip\zip.exe -r -5 -v -o k2pack * -x setup.exe
2032+
copy /b ${{ github.workspace }}\info-zip\os2\unzipsfx.exe + k2pack.zip K2PACK.EXE
2033+
2034+
echo :: Prepare DIST-MINI
2035+
cd ${{ github.workspace }}\dist-mini
2036+
copy ${{ github.workspace }}\k2-mini\setup.exe
2037+
copy ${{ github.workspace }}\k2-mini\K2PACK.exe
2038+
2039+
echo :: Prepare DIST-FULL
2040+
cd ${{ github.workspace }}\dist-full
2041+
copy ${{ github.workspace }}\k2-full\setup.exe
2042+
copy ${{ github.workspace }}\k2-full\K2PACK.exe
2043+
shell: cmd
2044+
2045+
- name: Delete old full artifact
2046+
uses: geekyeggo/delete-artifact@v5
2047+
with:
2048+
name: k2-full-install
2049+
2050+
- name: Delete old mini artifact
2051+
uses: geekyeggo/delete-artifact@v5
2052+
with:
2053+
name: k2-mini-install
2054+
2055+
- name: Upload Full Installer Artifact
2056+
uses: actions/upload-artifact@v4
2057+
with:
2058+
name: k2-full-install
2059+
path: ${{github.workspace}}/dist-full
2060+
if-no-files-found: error
2061+
retention-days: 7
2062+
2063+
- name: Upload Minimal Installer Artifact
2064+
uses: actions/upload-artifact@v4
2065+
with:
2066+
name: k2-mini-install
2067+
path: ${{github.workspace}}/dist-mini
2068+
if-no-files-found: error
2069+
retention-days: 7

‎doc/README.md

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
Kermit 95 Documentation Index
2+
==============================
3+
This directory contains documentation for Kermit 95:
4+
5+
* [Change Log](changes.md)
6+
* [SSH Readme](ssh-readme.md)
7+
* [The User Manual](#the-user-manual)
8+
* Build instructions
9+
* [Supported Compilers](compilers.md)
10+
* [Building for Windows with Visual C++ or Open Watcom](building.md)
11+
* [Building for OS/2 with Open Watcom](os2-building.md)
12+
* [Building for Windows with MinGW](mingw-building.md)
13+
* [Optional Dependencies](optional-dependencies.md)
14+
* [Source code index](code-index.md)
15+
* [Build Flags](build-flags.md)
16+
17+
The User Manual
18+
---------------
19+
The [manual](manual) directory contains the Kermit 95 User Manual. This was
20+
originally a printed booklet and a collection of text files until Kermit 95
21+
v1.1.17 of June 1998 when it was converted into HTML 1.0 format and updated with
22+
each release.
23+
24+
With the cancellation of the Kermit Project in 2011, Manning Publications
25+
assigned the copyright back to Columbia University and in March 2011 Frank da
26+
Cruz updated it for the web and [put it online](http://www.columbia.edu/kermit/k95manual/).
27+
In July 2024 Frank gave permission to add the manual to the git repo and sent
28+
through the version that was on kermitproject.org at the time. This has now
29+
been revised for the new open-source Kermit 95.
30+
31+
To make keeping it up-to-date, the various version numbers, release dates, and
32+
last modified dates scattered around the place have been updated with tags to
33+
allow them to be updated with a script. That script is
34+
mkdocs.bat/mkdocs.ksc/mkdocs.rex.
35+
36+
### Building the Manual
37+
38+
The manual can be built in one of two ways:
39+
* For the web: HTML files end in `.html`, and `index.html` is the main page of
40+
the manual. This is just like [the online version](http://www.columbia.edu/kermit/k95manual/).
41+
* For distribution *with* Kermit 95. HTML files end in `.htm` for better
42+
compatibility with vintage computers, `index.html` is an index to the offline
43+
documentation shipped with Kermit 95, and `kermit95.html` is the main page of
44+
the manual. Can optionally be built with insecure (http:// rather than
45+
https://) links to kermitproject.org for better compatibility with older
46+
browsers
47+
48+
To build the manual you must:
49+
* Be in the K95 build environment (have run `setenv.bat`)
50+
* Have built the Kermit 95 distribution (run `mkdist.bat`)
51+
* Have built the Kermit 95 distribution for A CPU architecture compatible with
52+
the computer you're building it on (if you're on an x86 machine, you've got
53+
to build Kermit 95 for x86 or x86-64 in order to build the manual) as building
54+
the manual involves running the freshly built version of Kermit 95.
55+
* Kermit 95 must be built with REXX support, and must include the regutil and
56+
rexxre external function libraries.
57+
58+
The reason for the above requirements is that Kermit 95 is used to build the
59+
manual, and version numbers and build dates from the version of Kermit 95 being
60+
used will be injected into the manual.
61+
62+
To build the manual for the web (note the output path must end with a `\`):
63+
```batch
64+
mkdocs.bat /W
65+
```
66+
67+
To build the manual for distribution with K95:
68+
```batch
69+
mkdocs.bat
70+
```
71+
72+
To build the manual for distribution with K95 on vintage computers (fewer
73+
https links):
74+
```batch
75+
mkdocs.bat /I
76+
```
77+
78+
Regardless of how you build it, the manual will end up in the dist directory,
79+
under `\docs\manual`

0 commit comments

Comments
 (0)