Merge pull request #2990 from cameronos/docs-fixes

Adjust COSMOS documentation

Docs/articles/Changelog.md

@@ -1,4 +1,4 @@
-# Devkit changelog
+# DevKit changelog
 
 ## c5c087c697d106348adbcff86d5d43331500e648 (update then merged in)
 
@@ -10,3 +10,5 @@
 ### Breaking changes
 
 Plugs are now included via a nuget package, to update cosmos past this commit you need to add the `Cosmos.Plugs` package to your kernel project. Don't forget to tick the `Include prerelease` checkbox and to set the package origin to `All`!
+
+*Last updated on 4 September 2023.*

Docs/articles/Compiler/il2cpu.md

@@ -1,13 +1,15 @@
 # IL2CPU
 
-This is one of the most important pieces of code in Cosmos. It's an AOT (Ahead-Of-Time) compiler.
+IL2CPU is one of the most important pieces of code in Cosmos. It's an AOT (Ahead-Of-Time) compiler.
 
-When you compile your C# (or any .NET language) program, it is compiled into CIL (common intermediate language). The CIL is then interpreted and executed by a virtual machine when you open your exe.
+When you compile your C# (or any other .NET language) program, it is compiled into CIL (common intermediate language). The CIL is then interpreted and executed by a virtual machine when you open your .exe.
 
-Cosmos is written in C# and Visual Studio compiles it into CIL as always. But a PC does not come with an interpreter for the CIL code. And writing a virtual machine for running an operating system is not always ideal.
+Cosmos is written in C# and Visual Studio compiles it into CIL like usual. But a PC does not come with an interpreter for the CIL code, and writing a virtual machine for running an operating system is not ideal.
 
-This is where IL2CPU comes in. IL2CPU takes the CIL code and translates it to processor opcodes. Currently, only x86 opcodes are available at the moment. However, more architectures are planned for the future (ARM, PowerPC, x86-64).
+This is where IL2CPU comes in. IL2CPU takes the CIL code and translates it to processor op-codes. Currently, only x86 opcodes are available at the moment. However, more architectures are planned for the future (ARM, PowerPC, x86-64).
 
-At this point, IL2CPU performs some more magic before finally converting the entire file into a bootable binary file, which can be loaded by a bootloader on any system (Cosmos uses the [Limine bootloader](https://github.com/limine-bootloader/limine)).
+At this point, IL2CPU performs some more magic before finally converting the entire file into a bootable binary file, which can be loaded by a bootloader on any system (Cosmos uses the [Limine bootloader](https://github.com/limine-bootloader/limine).
 
-As you might think, IL2CPU is a fundamental part of the development of Cosmos. IL2CPU is responsible for the final output, which is why most optimizations added are for IL2CPU.
+As you might think, IL2CPU is a fundamental part of the development of Cosmos. IL2CPU is responsible for the final output, which is why most optimizations added are for IL2CPU.
+
+*Last updated on 24 March 2024.*

Docs/articles/Debugger/DebugCommands.md

@@ -60,3 +60,5 @@ Max = 18;
 
 ## Debug channel
 We support channels, which are prefixed with anything prefixed with 192 and up. 192 is used for a debug view.
+
+*Last updated on 12 February 2020.*

Docs/articles/GettingStarted.md

@@ -4,27 +4,20 @@
 
 Cosmos (C# Open Source Managed Operating System) is an operating system
 development kit which uses Visual Studio as its development environment.
-Despite C# in the name any .NET based language can be used including VB.NET,
+Despite C# in the name, any .NET based language can be used, including VB.NET,
 Fortran, Delphi Prism, IronPython, F# and more. Cosmos itself and the kernel
 routines are primarily written in C#, and thus the Cosmos name. Besides that,
-NOSMOS (.NET Open Source Managed Operating System) sounds stupid.
+NOSMOS (.NET Open Source Managed Operating System) sounds silly.
 
-Cosmos is not an operating system in the traditional sense, but instead it is
-an "Operating System Kit", or as I like to say "Operating System Legos".
-Cosmos lets you create operating systems just as Visual Studio and C# normally
-let you create applications. Most users can write and boot their own operating
-system in just a few minutes, all using Visual Studio. You can debug your operating system directly from Visual
-Studio using breakpoints.
+Cosmos diverts from traditional operating systems because it is not an operating system in the conventional sense; rather, it is an "Operating System Kit," similar to "Operating System Legos". With Cosmos, you have the flexibility to construct operating systems just as how Visual Studio and C# help you develop applications. Using Visual Studio, most users can swiftly write and boot their own operating system within minutes. Additionally, debugging your operating system directly from Visual Studio is a feature, allowing for efficient troubleshooting through breakpoints.
 
-Cosmos is available in two distributions, the developer kit (dev kit), and the user kit. The dev kit is designed for users who want to work on Cosmos itself.
-The user kit is designed for those who are interested in building their own
-operating system and doing some Cosmos work. The dev kit might be thought of
-as the Cosmos SDK. Most users should start off with the user kit as it is not
-so overwhelming like the dev kit. This article focuses on the user kit.
+Cosmos is available in two distributions, the developer kit (abbr. *DevKit*), and the user kit. 
+The DevKit was originally designed for those who want to work on Cosmos's core features, but now has superceded the inferior user kit due to having much more technical ability.
+The User Kit was designed for those who are interested in building their own operating system and doing some Cosmos work. Since the User Kit is so heavily outdated, it is often recommended to download the DevKit when installing. The documentation will cover both.
 
 ##  Writing your first Operating System
 
-Create a new project as you would any C# project, but select Cosmos as the project type.
+Once you have installed Cosmos (see other docs), you can create a new project as you would any C# project, but select Cosmos as the project type.
 
 ![](images/SNAG-0000.png)
 
@@ -39,40 +32,40 @@ console window, you will see the following:
 ![](images/SNAG-0003.png)
 
 This is your operating system running in VMware Player! Cosmos can of course
-also be booted in VMware Workstation, Hyper-V, Virtual PC, Bochs, or on real
-hardware. But by default Cosmos uses VMware Player because it is both free,
+also be booted in VMware Workstation, VirtualBox, Bochs, or on real
+hardware. But by default, Cosmos uses VMware Player because it is both free,
 and reliable. Cosmos can even debug in Visual Studio, even when running on
 another machine.
 
 ##  Integrated Debugging
 
 Debugging is a major issue with operating system development. The Cosmos team
 was not content enough to simply conquer building and deployment, we want to
-make developing operating system as easy as developing Windows applications.
+make developing operating systems as easy as developing Windows applications.
 Debugging a Cosmos based operating system should feel very familiar to you.
 Lets modify our project a little bit to show the effect, and set a breakpoint. 
-**Note that the debugger only works in Visual Studio, and not Linux**
+*Note that the debugger only works in Visual Studio, and not Linux!*
 
 ![](images/SNAG-0005.png)
 
 Now run the project again.
 
 ![](images/SNAG-0007.png)
 
-Note that the execution stopped at "One"? That is becuase in Visual Studio our
+Notice how the execution stopped at "One"? That is becuase in Visual Studio our
 project has stopped on a breakpoint. Simply press F5 to continue just as you
 would in a normal application!
 
-In addition to breakpoints Cosmos also supports step into (F11) as well. Trace
+In addition to breakpoints, Cosmos also supports step into (F11) as well. Trace
 over (F10) is not supported yet.
 
 ##  Debugger Communication
 
 The debugger uses the serial port to communicate. Because of this, debugging
-only works wtih virtualization environments that support serial ports such as
+only works within virtualization environments that support serial ports, such as
 VMware. QEMU supports serial ports as well, but its serial port implementation
 is seriously broken on Windows and makes debugging impossible using QEMU. To
-debug on real hardware, you must use a physical serial cable. In the future
+debug on real hardware, you must use a physical serial cable. In the future,
 Cosmos will also support debugging over Ethernet.
 
 ##  Extra Debugging
@@ -109,7 +102,7 @@ Both functions will produce the same result.
 
 ##  Debug Output
 
-Debug strings can be output to the debug window of the host. Because Cosmos
+Debug strings can be outputted to the debug window of the host. Because Cosmos
 does not support watches yet, this functionality can be very useful for
 watching variable values and for performing tracing without breakpoints.
 
@@ -124,13 +117,14 @@ and it will appear in the Visual Studio output window.
 ##  What's the catch?
 
 There really is no catch. Everything we've shown here is functioning as seen.
-No mockups were used. However we still have a lot of work to go. Items of
-interest that are on our current task list include threads and networking. 
+No mockups were used. However, we still have a lot of work to do. Items of
+interest that are on our current task list include multithreading and x64 systems. 
 We have prototypes and experiments for each, but none have been rolled into 
 the mainline Cosmos development as of yet.
 
 ##  Obtaining Cosmos
 
-  * Cosmos Website - [http://www.GoCosmos.org](http://www.GoCosmos.org)
-  * Source Code - Both dev kit and user kit - [http://github.com/CosmosOS/Cosmos/](http://github.com/CosmosOS/Cosmos/)
+  * Cosmos website - [http://www.GoCosmos.org](http://www.GoCosmos.org)
+  * Source code - Both DevKit and User Kit - [http://github.com/CosmosOS/Cosmos/](http://github.com/CosmosOS/Cosmos/)
 
+*Last updated on 24 March 2024.*

Docs/articles/Installation/DevKit.md

@@ -1,18 +1,19 @@
-# Dev Kit Installation 
+# DevKit Installation 
 
 ## Windows
 
 ###  Prerequisites
 
-* (Free) source code of Development Kit from [Cosmos on GitHub](https://github.com/CosmosOS/Cosmos)
+* Source code of Development Kit from [Cosmos on GitHub](https://github.com/CosmosOS/Cosmos)
    * You must clone the repository using Git. For a detailed walkthrough, [see here](https://help.github.com/articles/fork-a-repo/).
-* (Free) [Visual Studio 2022 Community](https://visualstudio.microsoft.com/vs/)  
-* (Free) [InnoSetup](http://www.jrsoftware.org/isdl.php#qsp)
+* [Visual Studio 2022 Community](https://visualstudio.microsoft.com/vs/)  
+* [InnoSetup](http://www.jrsoftware.org/isdl.php#qsp)
    * This is required to build the setup kit which is used to build and install the Visual Studio integration libaries for Cosmos.
    * During install it will ask you about optional components to install. Be sure you check "Install Inno Setup Preprocessor".
 
 ###  Installation
 
+* Git clone the current source code of Cosmos or download the source code directly from GitHub. If you downlaod the source code, you will need to rename the folder to simply 'Cosmos'.
 * Look in the downloaded sources and run **install-VS2022.bat** with admin privileges (UAC will ask for permission), needed for install in system directories.
 * When the installation is complete, Visual Studio will automatically open and you may begin programming with your new, modified copy of Cosmos.
 
@@ -28,49 +29,51 @@
 * QEMU or any other virtual machine. See [Running](https://cosmosos.github.io/articles/Installation/Running.html) for more information.
 
 ###  Installation
-Run `make` to build Cosmos. Cosmos will clone all the required repos, build itself, and install it and it's nuget packages to the system automatically.
+Git cline the current source code of Cosmos.
+Run `make` to build Cosmos. Cosmos will clone all the required repos, build itself, and install it and its nuget packages to the system automatically.
 
 ## MacOS (Apple Silicon/Intel)
-There is currently hard to build on Apple Silicon Devices. So are going to build DevKit on Docker (Virtual Environment Service).
+It is currently difficult to build Cosmos on Apple Silicon Devices. So, we are going to build DevKit on Docker (Virtual Environment Service).
 
 ### Prerequisites
 
-* Docker(`brew cask install docker`)
+* Docker (`brew cask install docker`)
 * QEMU or any other virtual machine. See [Running](https://cosmosos.github.io/articles/Installation/Running.html) for more information.
 
 
 ###  Installation
-First we need to set directory to the path of Cosmos source directory and build the Dockerfile:
+First, we need to set directory to the path of Cosmos source directory and build the Dockerfile:
 ```
 cd /path/to/Cosmos/
 docker build -t cosmos .
 ```
 This will take a while. If there is no error, you successfully installed Cosmos on a Virtual Environment!
 
-## notes / FAQ
+## Notes / FAQ
 
-### custom cosmos repos
+### Custom Cosmos Repos
 
-if you are using custom cosmos repos you will need to clone them all manually as the installer script will pull from https://github.com/CosmosOS/
+If you are using custom Cosmos repos, you will need to clone them all manually, as the installer script will only pull from https://github.com/CosmosOS/
 
 A tree diagram of the source should look like the following:   
 
 <img src="https://raw.githubusercontent.com/CosmosOS/Cosmos/master/Docs/images/Dir.png" width="200">
 
 
-### get stuck pulling the git repos
+### I get stuck pulling the git repos!
 
-check if git is installed and in your path as we use git to pull the repos
+Check if [Git](https://git-scm.com/) is installed on your machine and within your path. We use Git to pull the repos from GitHub.
 
-### i just updated and my project is sill using the old version
+### I just updated my DevKit and my project is still using the older version!
 
-you may need to clear you nuget cache try ``dotnet clean`` to clear the project level cache
+Although Cosmos typically uninstalls previous kits before installing a new one; it is possible that your project can reference an older-version. In the rare case this does occur, you may need to clear the NuGet cache. Try running `dotnet clean` to clear the project-level cache. 
 
-### the project templates are not showing in visual studio
+### The project templates are not showing in Visual Studio!
 
-if you have more then 1 version of visual studio installed this can bug this follow "dotnet Project Templates" should fix it
+If you have more than 1 version of Visual Studio *(such as both 2022 and 2019)*, this bug can occur. Try running `dotnet Project Templates` to get them back.
 
 ### dotnet Project Templates
-If you are using linux or prefer not using Visual Studio for your projects, you can install the dotnet project template using `dotnet new --install ./source/templates/csharp/` assuming you are currently in the Cosmos base directory.
-After installing the template use `dotnet new cosmosCSKernel -n {name}` to create a new Cosmos Kernel project. 
+If you are using Linux, or prefer not using Visual Studio for your projects, you can install the dotnet project template using `dotnet new --install ./source/templates/csharp/` assuming you are currently in the Cosmos base directory. After installing the template, use `dotnet new cosmosCSKernel -n {name}` to create a new Cosmos Kernel project. 
 The dotnet template can be removed at a later time using `dotnet new --uninstall ./source/templates/csharp/`.
+
+*Last updated on 24 March 2024.*

Docs/articles/Installation/Running.md

@@ -1,8 +1,8 @@
 # Running
-Cosmos supports running on any Intel x86 environment. However for debugging
+Cosmos supports running on any Intel x86 environment. However, for debugging
 and ease of use, many virtual and physical setups have integrated support. If
 you do not see your environment, this does not mean Cosmos will not work. You
-can simply fall back to ISO which should work with any environment.
+can simply fall back to ISO, which should work with any environment.
 
 ##  ISO
 
@@ -11,17 +11,17 @@ mounted and booted by most virtualization technologies. In addition, a physical
 optical disk can be burned and used to boot physical hardware.
 
 # Linux/Posix
-### DISCLAIMER: This article assumes that you are using a debian based operating system
+**DISCLAIMER: This article assumes that you are using a Debian-based operating system!**
 
 ## QEMU
-Here you can use a generic run file, you can run it by using `sh run.sh -i <ISO> -m <memory size> -h <hdd image>`.
-It has to be at the root directory of the project
+Here you can use a generic run file, you can run it by using `sh run.sh -i <ISO> -m <memory size> -h <hdd image>`. It has to be at the root directory of the project.
 
 QEMU is required and can be installed with `apt-get install qemu-system`.
 
-To create an hdd image, you have to convert this [.vmdk](https://github.com/CosmosOS/Cosmos/blob/master/Build/VMWare/Workstation/Filesystem.vmdk?raw=true) file to a .img wich can then be used by QEMU using the following command
+To create an HDD image, you have to convert this [.vmdk](https://github.com/CosmosOS/Cosmos/blob/master/Build/VMWare/Workstation/Filesystem.vmdk?raw=true) file to a .img, which can then be used by QEMU using the following command
 `qemu-img convert -f vmdk -O raw Filesystem.vmdk cosmos.img`
 
+Here is the run.sh:
 `run.sh:`
 ```sh
 #!/bin/bash
@@ -60,8 +60,9 @@ dotnet build
 qemu-system-x86_64 -boot d -cdrom $ISO -m $MEMORY_SIZE -hda $HDD_IMAGE
 ```
 
-## Virtualbox
-Create a virtual machine and use this [.vmdk](https://github.com/CosmosOS/Cosmos/blob/master/Build/VMWare/Workstation/Filesystem.vmdk?raw=true) as HDD image
+## VirtualBox
+Create a virtual machine and use this [.vmdk](https://github.com/CosmosOS/Cosmos/blob/master/Build/VMWare/Workstation/Filesystem.vmdk?raw=true) as your HDD image.
+If you are utilizing audio, we recommend VirtualBox for the ability to use their AC97 driver.
 
 # Windows
 
@@ -80,17 +81,18 @@ VMWare Player can be downloaded [here](https://www.vmware.com/go/getplayer-win).
 
 ### VMWare Workstation
 
-VMWare Workstation can be downloaded for free trial [here](https://www.vmware.com/go/getworkstation-win).
+VMWare Workstation (paid version) can be downloaded for a free trial [here](https://www.vmware.com/go/getworkstation-win).
 
 ##  QEMU
 
-Not officially supported at this time, but can be done. Just use the ISO option above with debugging turned off.
+QEMU is not officially supported for Cosmos at this time, but can be used. Just use the ISO option above with debugging turned off.
+If you want to use graphical mode in QEMU (Canvas or SVGA-II), ensure that VBE multiboot is enabled in your project settings of Cosmos.
 
 QEMU can be downloaded [here](https://www.qemu.org/download/)
 
 ## Bochs
 
-Bochs is officially supported.
+Bochs is officially supported for Cosmos. As Bochs is a full emulation software, results vary and are often times slower than other virtualization platforms.
 
 Bochs can be downloaded [here](https://bochs.sourceforge.io/getcurrent.html)
 
@@ -99,7 +101,7 @@ Bochs can be downloaded [here](https://bochs.sourceforge.io/getcurrent.html)
 For PXE, no special software is required. Only an ethernet connection to your router. However, if you have a computer that does not support network booting, or if you must perform the action over WiFi, you may need to look at a PXE chainloader such as [gPXE](http://etherboot.org/wiki/).
 To run your Cosmos kernel in PXE you need to follow these steps:
 
-Step #1: disable Cosmos Remote Debugger, activate PXE and compilation in bin format.
+Step #1: Disable Cosmos Remote Debugger, activate PXE and compile in bin format.
 Go to Properties and copy these settings:
 
 ![image](https://user-images.githubusercontent.com/98218366/178479237-a22a7b5f-250e-432d-ba74-0da502e82f7b.png)
@@ -108,10 +110,11 @@ Boot the machine and connect it via Ethernet and will show this screen:
 
 ![image](https://user-images.githubusercontent.com/98218366/178479800-c70faa5d-1fab-4da4-8f27-05eefee89b75.png)
 
-Wait and your os will boot up.
+Wait and your OS will boot up.
 
-## Hyper-V
+## Hyper-V, VirtualPC
 
 Not supported at this time.
 
 
+*Last updated on 24 March 2024.*