WIP documentation book

.github/workflows/book.yml

@@ -0,0 +1,26 @@
+name: Build
+
+on:
+  schedule:
+    - cron: "0 0 * * 0"
+  push:
+    branches: [main, publish]
+
+jobs:
+  build:
+    timeout-minutes: 15
+    continue-on-error: true
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [windows-latest, ubuntu-latest, macOS-latest]
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: "latest"
+
+      - name: Build
+        run: mdbook build ./docs

.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish
+
+on:
+  schedule:
+    - cron: "0 0 1 * *"
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    timeout-minutes: 15
+    continue-on-error: true
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: "latest"
+
+      - name: Build
+        run: mdbook build ./docs
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          cname: tomas.tonybark.com
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/book

.gitignore

@@ -1,7 +1,6 @@
 # File created using '.gitignore Generator' for Visual Studio Code: https://bit.ly/vscode-gig
-
-# Created by https://www.toptal.com/developers/gitignore/api/windows,visualstudiocode,visualstudio,rider,macos,linux,backup,dotenv
-# Edit at https://www.toptal.com/developers/gitignore?templates=windows,visualstudiocode,visualstudio,rider,macos,linux,backup,dotenv
+# Created by https://www.toptal.com/developers/gitignore/api/windows,visualstudiocode,visualstudio,rider,macos,linux,dotenv,backup,mdbook
+# Edit at https://www.toptal.com/developers/gitignore?templates=windows,visualstudiocode,visualstudio,rider,macos,linux,dotenv,backup,mdbook
 
 ### Backup ###
 *.bak
@@ -57,12 +56,43 @@ Network Trash Folder
 Temporary Items
 .apdisk
 
+### macOS Patch ###
+# iCloud generated files
+*.icloud
+
+### MdBook ###
+book
+
+
 ### Rider ###
 # Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
 # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
 
 # User-specific stuff
-.idea/**
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
 
 # Gradle and Maven with auto-import
 # When using Gradle or Maven with auto-import, you should exclude module files,
@@ -98,6 +128,9 @@ atlassian-ide-plugin.xml
 # Cursive Clojure plugin
 .idea/replstate.xml
 
+# SonarLint plugin
+.idea/sonarlint/
+
 # Crashlytics plugin (for Android Studio and IntelliJ)
 com_crashlytics_export_strings.xml
 crashlytics.properties
@@ -112,9 +145,17 @@ fabric.properties
 
 ### VisualStudioCode ###
 .vscode/*
+!.vscode/settings.json
 !.vscode/tasks.json
 !.vscode/launch.json
-*.code-workspace
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
 
 ### VisualStudioCode Patch ###
 # Ignore all local history of files
@@ -151,7 +192,7 @@ $RECYCLE.BIN/
 ## Ignore Visual Studio temporary files, build results, and
 ## files generated by popular Visual Studio add-ons.
 ##
-## Get latest from https://github.com/github/gitignore/blob/master/VisualStudio.gitignore
+## Get latest from https://github.com/github/gitignore/blob/main/VisualStudio.gitignore
 
 # User-specific files
 *.rsuser
@@ -173,6 +214,7 @@ mono_crash.*
 [Rr]eleases/
 x64/
 x86/
+[Ww][Ii][Nn]32/
 [Aa][Rr][Mm]/
 [Aa][Rr][Mm]64/
 bld/
@@ -211,6 +253,9 @@ project.lock.json
 project.fragment.lock.json
 artifacts/
 
+# ASP.NET Scaffolding
+ScaffoldingReadMe.txt
+
 # StyleCop
 StyleCopReport.xml
 
@@ -235,6 +280,7 @@ StyleCopReport.xml
 *.tmp_proj
 *_wpftmp.csproj
 *.log
+*.tlog
 *.vspscc
 *.vssscc
 .builds
@@ -287,7 +333,9 @@ _TeamCity*
 !.axoCover/settings.json
 
 # Coverlet is a free, cross platform Code Coverage Tool
-coverage*[.json, .xml, .info]
+coverage*.json
+coverage*.xml
+coverage*.info
 
 # Visual Studio code coverage results
 *.coverage
@@ -435,6 +483,15 @@ node_modules/
 # Visual Studio 6 auto-generated workspace file (contains which files were open etc.)
 *.vbw
 
+# Visual Studio 6 auto-generated project file (contains which files were open etc.)
+*.vbp
+
+# Visual Studio 6 workspace and project file (working project files containing files to include in project)
+*.dsw
+*.dsp
+
+# Visual Studio 6 technical files
+
 # Visual Studio LightSwitch build output
 **/*.HTMLClient/GeneratedArtifacts
 **/*.DesktopClient/GeneratedArtifacts
@@ -491,6 +548,9 @@ ASALocalRun/
 # Local History for Visual Studio
 .localhistory/
 
+# Visual Studio History (VSHistory) files
+.vshistory/
+
 # BeatPulse healthcheck temp database
 healthchecksdb
 
@@ -500,7 +560,23 @@ MigrationBackup/
 # Ionide (cross platform F# VS Code tools) working folder
 .ionide/
 
-# End of https://www.toptal.com/developers/gitignore/api/windows,visualstudiocode,visualstudio,rider,macos,linux,backup,dotenv
+# Fody - auto-generated XML schema
+FodyWeavers.xsd
+
+# VS Code files for those working on multiple tools
+*.code-workspace
+
+# Local History for Visual Studio Code
+
+# Windows Installer files from build outputs
+
+# JetBrains Rider
+*.sln.iml
+
+### VisualStudio Patch ###
+# Additional files built by Visual Studio
+
+# End of https://www.toptal.com/developers/gitignore/api/windows,visualstudiocode,visualstudio,rider,macos,linux,dotenv,backup,mdbook
 
 # Custom rules (everything added below won't be overriden by 'Generate .gitignore File' if you use 'Update' option)
 

README.md

@@ -1,9 +1,9 @@
 # TOMAS
 
 <p align="center">
-<img title="" src="assets/logo.svg" width="250" alt=""">
+<img title="" src="docs/src/static/imgs/logo.svg" width="250" alt=""">
 <br>
-<img title="" src="assets/screenshot.png" alt=""">
+<img title="" src="docs/src/static/imgs/screenshot.png" alt=""">
 <hr>
 </p>
 <p align="center">
@@ -18,9 +18,9 @@
 
 TOMAS (**To**ny's **Ma**naged Operating **S**ystem) is a hobby operating system based on the [COSMOS](https://github.com/CosmosOS/Cosmos) framework that comes with a respective terminal emulator.
 
-## Fictional version
+<!--## Fictional version
 
-Within [Casey Universe](https://github.com/tonytins/cugame), TOMAS is an operating system that serves as Anthony's tool to explore the galaxy while working for the Akonos Corporation, a company that builds artificial worlds. He can hack into any system he pleases and uses that 
+Within [Casey Universe](https://github.com/tonytins/cugame), TOMAS is an operating system that serves as Anthony's tool to explore the galaxy while working for the Akonos Corporation, a company that builds artificial worlds. He can hack into any system he pleases and uses that -->
 
 ## Requirements
 

docs/.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+    "editor.tabCompletion": "on",
+    "diffEditor.codeLens": true
+}

docs/.vscode/tasks.json

@@ -0,0 +1,25 @@
+{
+  // See https://go.microsoft.com/fwlink/?LinkId=733558
+  // for the documentation about the tasks.json format
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "build",
+      "type": "shell",
+      "command": "mdbook build",
+      "problemMatcher": []
+    },
+    {
+      "label": "clean",
+      "type": "shell",
+      "command": "mdbook clean",
+      "problemMatcher": []
+    },
+    {
+      "label": "serve",
+      "type": "shell",
+      "command": "mdbook serve",
+      "problemMatcher": []
+    }
+  ]
+}

docs/book.toml

@@ -0,0 +1,17 @@
+[book]
+authors = ["Tony Bark"]
+language = "en"
+multilingual = false
+src = "src"
+title = "TOMAS"
+
+[build]
+create-missing = false
+
+[output.html]
+no-section-label = true
+git-repository-url = "https://github.com/tonytins/tomas"
+additional-css = ["custom.css"]
+
+[output.html.fold]
+enable = true

docs/custom.css

@@ -0,0 +1,3 @@
+code {
+    white-space : pre-wrap !important;
+}

docs/src/README.md

@@ -0,0 +1,9 @@
+# Introduction
+
+<p align="center">
+<img title="" src="./static/imgs/logo.svg" width="250" alt=""">
+</p>
+
+TOMAS (**To**ny's **Ma**naged Operating **S**ystem) is a modular hobby operating system written in C# using the [COSMOS](https://github.com/CosmosOS/Cosmos) framework. It comes with a respective terminal emulator using for Core testing.
+
+Both the kernel and terminal emulator will eventually support programs and plugins, respectfully. With the former allowing for running of native .NET executables and the latter Lua plugins, while taking advantage of the existing [interface](./design/interfaces.md) architecture.

docs/src/SUMMARY.md

@@ -0,0 +1,14 @@
+# Summary
+
+- [Introduction](./README.md)
+- [Changelog](./changelog.md)
+
+# Design
+
+- [Interfaces](./design/interfaces.md)
+- [File System]()
+- [Translations]()
+
+# Nethington
+
+- [Compliance](./nethington/compliance.md)

docs/src/changelog.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 23.1
+
+- With the help of ChatGPT, the ``IProgram`` interface has been rewritten to handle command line arguments. Being ChatGPT derived, it's still rough around the edges (not sure what to do with ``IArguments`` right now), but it's one hell of a jumping start!
+- Speaking of, the [CST parser](https://github.com/tonytins/cstdotnet) has been rewritten to finally support arguments with the help of ChatGPT too. While I could have always looked at FreeSO's implantation for reference, that code is just awful. It will be ported back upstream ASAP!
+
+## 23.0
+
+- Split versioning systems between kernal and terminal
+  - Calendar versioning, `YY.MINOR.MICRO`, for kernal
+  - Semantic versioning for terminal
+- If the file system is activate, system activity will be logged
+- Build number based on commit hash
+
+Due to the huge time skip and architectural changes, I've (retroactively) switched to calendar versioning with ``v0.1`` now known as ``v20.1`` as well.
+
+## 20.1
+
+- Filesystem (based on the Cosmos Wiki [guide](https://csos-guide-to-cosmos.fandom.com/wiki/Getting_Started_-_Materials_and_Setting_Up))
+- Semantic versioning
+- Replaced BasicApp with AboutApp
+- Removd TerminalCancelEventArgs and everything related to it

docs/src/design/filesystem.md

@@ -0,0 +1,3 @@
+# File System
+
+Since 19.1, a virtual file system was introduced based on ``CosmosVFS`` and ``VFSManager``, respectfully.

docs/src/design/interfaces.md

@@ -0,0 +1,29 @@
+# Interfaces
+
+Since 19.1, TOMAS uses a modular interface design for writing and executing programs. At the moment, the operating system doesn't yet support loading assemblies that would take advantage of this API, but it is being looked into.
+
+## Design
+
+``IProgram`` is used to create the actual program while ``IShell`` executes the respective program from a dictionary. While still early in development, the approach has allowed for easy migration from one major release of COSMOS to another with little to no modifications of the code itself.
+
+```csharp
+public interface IProgram
+{
+    string Name { get; }
+
+    string Description { get; }
+
+    bool Entry(IShell shell, IEnumerable<KeyValuePair<string, object>> arguments);
+}
+```
+
+```csharp
+public interface IShell
+{
+    string ReadLine { get; }
+
+    Dictionary<string, IProgram> Programs { get; }
+
+    IEnumerable<KeyValuePair<string, object>>? ParseArguments(IProgram program, string[] arguments);
+}
+```

docs/src/design/translations.md

@@ -0,0 +1,3 @@
+# Translations
+
+Since 23.0, TOMAS uses a derivative of [CST.NET](https://github.com/tonytins/cstdotnet) for handling translations. Naturally, it follows the same [interface](./interfaces.md) paradigm as described in the last chapter with ``IUIText`` being renamed to ``ITranslations``, located in ``Tomas.Interface.Globalization``, but the two remain compatible. Changes made here will eventually make their way back upstream.

docs/src/nethington/compliance.md

@@ -0,0 +1,7 @@
+# Compliance with Regulations in Nethington
+
+In order to comply with the Nethington[^1] government's [adoption of open-source software](https://nethington.tonybark.com/bills/drafts/hr2.html) for all government-owned computer systems, TOMAS will be used as government software. The operating system will meet the functional and technical requirements of the government and adhere to the principles of responsible and open source development. TOMAS will meet the requirements for strong track record of security and stability, and be in compliance with all applicable laws and regulations, including those outlined in [Article V](https://nethington.tonybark.com/constitution.html#article-v-cybersecurity) of the Constitution regarding cybersecurity and the use of long-term support or enterprise-grade open source software. The Nethington Cybersecurity Agency (NCA) will evaluate TOMAS and determine its suitability for use by the government. TOMAS will implement software to keep the identity of individuals working for the NCA confidential as further outlined in Article V of the Constitution.
+
+## Footnotes
+
+[^1]: [Nethington](https://nethington.tonybark.com) is another hobby project of mine in the form of micronation,