Improve documentation (#547)

* Update readme

* Add hardware page

* Add contributing page

* Update changelog

* Update contributing

* Update index

* Add games page

* Move images to doc/images

* Rebuild website

* Fix dsk/var/www

* Update contributing

* Change games order

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+- Add process page table (#454)
+- Bump vte from 0.12.1 to 0.13.0 (#543)
+- Add more code examples to lisp (#542)
+- Add support for hexadecimal numbers in Lisp (#540)
+- Upgrade acpi crate to 5.0.0 (#538)
+- Run cargo clippy (#541)
+- Bump vte from 0.12.0 to 0.12.1 (#539)
+- Bump num-traits from 0.2.16 to 0.2.17 (#536)
+- Bump libm from 0.2.7 to 0.2.8 (#535)
+- Bump x86_64 from 0.14.10 to 0.14.11 (#531)
+- Bump vte from 0.11.1 to 0.12.0 (#532)
+- Bump sha2 from 0.10.7 to 0.10.8 (#533)
+
 ## 0.10.1 (2023-09-23)
 - Add PageUp and PageDown keys support ([#515](https://github.com/vinc/moros/pull/515))
 - Add namespaces to lisp ([#511](https://github.com/vinc/moros/pull/511))

CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to MOROS
+
+First off, thanks for taking the time to contribute! ❤️
+
+And if you like the project, but just don't have time to contribute, that's
+fine. There are other easy ways to support the project and show your
+appreciation, which we would also be very happy about:
+
+- Star the project on GitHub ✨
+- Talk about it on social media
+- Mention the project at local meetups and tell your friends/colleagues
+
+## Did you find a bug?
+
+- Ensure the bug was not already reported by searching on GitHub under
+  [Issues](https://github.com/vinc/moros/issues)
+- If you're unable to find an open issue addressing the problem,
+  [open a new one](https://github.com/vinc/moros/issues/new). Be sure to
+  include a **title and clear description**, as much relevant information as
+  possible to reproduce it
+
+## Did you write a patch that fixes a bug?
+
+- Open a new GitHub pull request with the patch
+- Ensure the PR description clearly describes the problem and solution
+  Include the relevant issue number if applicable
+
+## Do you intend to add a new feature or change an existing one?
+
+- Suggest your idea by [creating a new discussion](https://github.com/vinc/moros/discussions/new?category=ideas)
+- Be aware that MOROS is a personal hobby project with the goal of creating an
+  simple operating system that can fit in one standard human brain and
+  inspiring others to do the same
+- If you want an operating system that does more you might want to collaborate
+  on a bigger project like [Redox](https://www.redox-os.org/) or
+  [Serenity](https://serenityos.org/)
+
+## Do you have questions about the project?
+
+- Ask any question about how to use MOROS by [creating a new discussion](https://github.com/vinc/moros/discussions/new?category=q-a)

Makefile

@@ -100,4 +100,4 @@ website:
 
 clean:
 	cargo clean
-	rm -f www/*.html www/*.png
+	rm -f www/*.html www/images/*.png

README.md

@@ -1,6 +1,6 @@
 # MOROS: Obscure Rust Operating System
 
-![screenshot](doc/moros.png)
+![screenshot](doc/images/moros.png)
 
 MOROS is a hobby operating system written in Rust by [Vincent Ollivier](https://vinc.cc).
 
@@ -17,31 +17,29 @@ This project started from the [seventh post][1] of the second edition of
 
 ## Features
 
-- [x] External bootloader (using [bootloader](https://github.com/rust-osdev/bootloader))
-- [x] x86 CPU support (using [x86_64](https://crates.io/crates/x86_64))
-- [x] Hardware interrupts (using [pic8259](https://crates.io/crates/pic8259))
-- [x] PS/2 Keyboard with customizable layout (using [pc-keyboard](https://crates.io/crates/pc-keyboard))
-- [x] VGA Text mode with customizable font and color palette
-- [x] Serial output (using [uart_16550](https://crates.io/crates/uart_16550))
-- [x] Paging
-- [x] Heap allocation (using [linked_list_allocator](https://crates.io/crates/linked_list_allocator))
-- [x] ACPI shutdown (using [acpi](https://crates.io/crates/acpi) and [aml](https://crates.io/crates/aml))
-- [x] RTC clock
-- [x] PCI devices
-- [x] ATA PIO mode
-- [x] Random number generator (using [rand_hc](https://crates.io/crates/rand_hc))
-- [x] RTL8139 network card
-- [x] AMD PCNET network card
-- [x] DHCP/IP/TCP/UDP/DNS/HTTP network protocols (using [smoltcp](https://crates.io/crates/smoltcp))
-- [x] Basic [filesystem](doc/filesystem.md)
-- [x] Basic [shell](doc/shell.md)
-- [x] Basic [text editor](doc/editor.md)
-- [x] Basic [lisp](doc/lisp.md) interpreter
-- [x] Basic userspace for NASM and Rust programs without alloc
-- [x] Some file and [network](doc/network.md) commands
-- [x] Some games
-- [ ] Multitasking
-- [ ] C standard library port
+- External bootloader (using [bootloader](https://github.com/rust-osdev/bootloader))
+- x86 CPU support (using [x86_64](https://crates.io/crates/x86_64))
+- Hardware interrupts (using [pic8259](https://crates.io/crates/pic8259))
+- PS/2 Keyboard with customizable layout (using [pc-keyboard](https://crates.io/crates/pc-keyboard))
+- VGA Text mode with customizable font and color palette
+- Serial output (using [uart_16550](https://crates.io/crates/uart_16550))
+- Paging
+- Heap allocation (using [linked_list_allocator](https://crates.io/crates/linked_list_allocator))
+- ACPI shutdown (using [acpi](https://crates.io/crates/acpi) and [aml](https://crates.io/crates/aml))
+- RTC clock
+- PCI devices
+- ATA PIO mode
+- Random number generator (using [rand_hc](https://crates.io/crates/rand_hc))
+- RTL8139 network card
+- AMD PCNET network card
+- DHCP/IP/TCP/UDP/DNS/HTTP network protocols (using [smoltcp](https://crates.io/crates/smoltcp))
+- Basic [filesystem](doc/filesystem.md)
+- Basic [shell](doc/shell.md)
+- Basic [text editor](doc/editor.md)
+- Basic [lisp](doc/lisp.md) interpreter
+- Basic userspace for NASM and Rust programs
+- Some file and [network](doc/network.md) commands
+- Some [games](doc/games.md)
 
 
 ## Documentation

doc/games.md

@@ -0,0 +1,13 @@
+# MOROS Games
+
+## Chess
+
+![chess](images/chess.png)
+
+## Conway's Game of Life
+
+![life](images/life.png)
+
+## 2048
+
+![2048](images/2048.png)

doc/hardware.md

@@ -0,0 +1,50 @@
+# MOROS Hardware Compatibility
+
+## Emulators
+
+- [x] QEMU
+  - [x] CPU: Intel Core 2 Duo T7700
+  - [x] NIC: Realtek RTL8139
+
+- [x] VirtualBox
+  - [x] NIC: PCnet-FAST III
+
+- [x] Bochs
+
+## Computers
+
+### Desktops
+
+- [x] Homebuilt (2007)
+  - [x] MB: Asus P5K
+  - [x] CPU: Intel Core 2 Duo E6850
+  - [x] NIC: Realtek RTL8139D
+
+- [x] HP ProLiant MicroServer N40L (2012)
+  - [x] CPU: AMD Athlon II Dual Core
+  - [ ] NIC: HP NC107i
+
+- [x] Intel NUC 5CPYH (2015)
+  - [x] CPU: Intel Celeron N3050
+  - [ ] NIC: Realtek RTL8111HN
+
+### Laptops
+
+- [x] Dell Latitude E6400 (2008)
+  - [x] CPU: Intel Core 2 Duo P8600
+  - [ ] NIC: Intel PRO/1000
+
+- [x] Lenovo ThinkPad X200 (2008)
+  - [x] CPU: Intel Core 2 Duo P8600
+  - [ ] NIC: Intel 82567-LM
+
+- [x] Lenovo ThinkPad T440p (2013)
+  - [x] CPU: Intel Core i5-4300M
+  - [ ] NIC: Intel I217-LM
+
+- [x] ASUS EeeBook E202SA (2017)
+  - [x] CPU: Intel Pentium N3710
+
+- [x] Lenovo ThinkPad T480 (2018)
+  - [x] CPU: Intel Core i5-8350U
+  - [ ] NIC: Intel I219-LM

doc/index.md

@@ -1,12 +1,13 @@
 # MOROS: Obscure Rust Operating System
 
-![screenshot](moros.png)
+![screenshot](images/moros.png)
 
-MOROS is a hobby operating system written in Rust by [Vincent Ollivier](https://vinc.cc).
-
-It targets computers with a x86-64 architecture and a BIOS, so mostly from 2005
-to 2020, but it also runs well on most emulators (Bochs, QEMU, and VirtualBox).
+MOROS is a hobby operating system written in Rust by
+[Vincent Ollivier](https://vinc.cc).
 
+It targets [computers](hardware.md#computers) with a x86-64 architecture and a
+BIOS, so mostly from 2005 to 2020, but it also runs well on most
+[emulators](hardware.md#emulators).
 
 ## Usage
 
@@ -14,8 +15,6 @@ MOROS is open source, you can [build it](https://github.com/vinc/moros)
 or [download an image](https://github.com/vinc/moros/releases). Consult the
 [manual](manual.md) to learn how to use the system.
 
-
-
 ## Features
 
 Everything in MOROS is done from a command line interface and most programs are
@@ -23,41 +22,41 @@ rather minimalist.
 
 It has a [shell](shell.md):
 
-![screenshot](shell.png)
+![screenshot](images/shell.png)
 
 With a few programs like `find` that use a [regex engine](regex.md) to find
 files or lines:
 
-![screenshot](find.png)
+![screenshot](images/find.png)
 
 It has a [calculator](calculator.md) and also a [lisp](lisp.md) interpreter:
 
-![screenshot](lisp.png)
+![screenshot](images/lisp.png)
 
 And a [text editor](editor.md):
 
-![screenshot](edit.png)
+![screenshot](images/edit.png)
 
-It has a [network stack](network.md) with two drivers for RTL8139 and PCNET cards:
+It has a [network stack](network.md) with two drivers for RTL8139 and PCNET
+cards:
 
-![screenshot](network.png)
+![screenshot](images/network.png)
 
-It has a chess game:
+It has a [chess game](games.md#chess):
 
-![chess](chess.png)
+![chess](images/chess.png)
 
-And the game of life:
+And the [game of life](games.md#conways-game-of-life):
 
-![life](life.png)
+![life](images/life.png)
 
-It even has 2048:
+It even has [2048](games.md#2048):
 
-![2048](2048.png)
+![2048](images/2048.png)
 
 And finally it is quite customizable:
 
-![light](light.png)
-
+![light](images/light.png)
 
 ## Demo
 
@@ -65,4 +64,3 @@ You can log in to a demo with the following command using the name of the
 system as a password for the guest account:
 
     $ ssh guest@try.moros.cc
-

dsk/var/www/moros.png

@@ -1 +1 @@
-../../../www/moros.png
+../../../www/images/moros.png

src/usr/install.rs

@@ -89,8 +89,8 @@ pub fn copy_files(verbose: bool) {
 
     create_dir("/var/www", verbose);
     copy_file("/var/www/index.html", include_bytes!("../../dsk/var/www/index.html"), verbose);
-    copy_file("/var/www/moros.png", include_bytes!("../../dsk/var/www/moros.png"), verbose);
     copy_file("/var/www/moros.css", include_bytes!("../../dsk/var/www/moros.css"), verbose);
+    copy_file("/var/www/moros.png", include_bytes!("../../dsk/var/www/moros.png"), verbose);
 }
 
 pub fn main(args: &[&str]) -> Result<(), ExitCode> {

www/2048.png

@@ -1 +0,0 @@
-../doc/2048.png

www/build.sh

@@ -1,6 +1,9 @@
 set -e
 
-ln -fs ../doc/*.png .
+mkdir -p images
+for file in ../doc/images/*.png; do
+  ln -s "../$file" images/
+done
 
 echo "# MOROS" > ../doc/test.md
 

www/chess.png

@@ -1 +0,0 @@
-../doc/chess.png

www/dark.png

@@ -1 +0,0 @@
-../doc/dark.png

www/edit.png

@@ -1 +0,0 @@
-../doc/edit.png

www/find.png

@@ -1 +0,0 @@
-../doc/find.png

www/games.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>MOROS Games</title>
+    <link rel="stylesheet" type="text/css" href="moros.css">
+  </head>
+  <body>
+    <h1>MOROS Games</h1>
+
+    <h2>2048</h2>
+
+    <p><img src="images/2048.png" alt="2048"></p>
+
+    <h2>Chess</h2>
+
+    <p><img src="images/chess.png" alt="chess"></p>
+
+    <h2>Conway&#39;s Game of Life</h2>
+
+    <p><img src="images/life.png" alt="life"></p>
+  </body>
+</html>

www/hardware.html

@@ -0,0 +1,88 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>MOROS Hardware Compatibility</title>
+    <link rel="stylesheet" type="text/css" href="moros.css">
+  </head>
+  <body>
+    <h1>MOROS Hardware Compatibility</h1>
+
+    <h2>Emulators</h2>
+
+    <ul>
+    <li><p>[x] QEMU</p>
+
+    <ul>
+    <li>[x] CPU: Intel Core 2 Duo T7700</li>
+    <li>[x] NIC: Realtek RTL8139</li>
+    </ul></li>
+    <li><p>[x] VirtualBox</p>
+
+    <ul>
+    <li>[x] NIC: PCnet-FAST III</li>
+    </ul></li>
+    <li><p>[x] Bochs</p></li>
+    </ul>
+
+    <h2>Computers</h2>
+
+    <h3>Desktops</h3>
+
+    <ul>
+    <li><p>[x] Homebuilt (2007)</p>
+
+    <ul>
+    <li>[x] MB: Asus P5K</li>
+    <li>[x] CPU: Intel Core 2 Duo E6850</li>
+    <li>[x] NIC: Realtek RTL8139D</li>
+    </ul></li>
+    <li><p>[x] HP ProLiant MicroServer N40L (2012)</p>
+
+    <ul>
+    <li>[x] CPU: AMD Athlon II Dual Core</li>
+    <li>[ ] NIC: HP NC107i</li>
+    </ul></li>
+    <li><p>[x] Intel NUC 5CPYH (2015)</p>
+
+    <ul>
+    <li>[x] CPU: Intel Celeron N3050</li>
+    <li>[ ] NIC: Realtek RTL8111HN</li>
+    </ul></li>
+    </ul>
+
+    <h3>Laptops</h3>
+
+    <ul>
+    <li><p>[x] Dell Latitude E6400 (2008)</p>
+
+    <ul>
+    <li>[x] CPU: Intel Core 2 Duo P8600</li>
+    <li>[ ] NIC: Intel PRO/1000</li>
+    </ul></li>
+    <li><p>[x] Lenovo ThinkPad X200 (2008)</p>
+
+    <ul>
+    <li>[x] CPU: Intel Core 2 Duo P8600</li>
+    <li>[ ] NIC: Intel 82567-LM</li>
+    </ul></li>
+    <li><p>[x] Lenovo ThinkPad T440p (2013)</p>
+
+    <ul>
+    <li>[x] CPU: Intel Core i5-4300M</li>
+    <li>[ ] NIC: Intel I217-LM</li>
+    </ul></li>
+    <li><p>[x] ASUS EeeBook E202SA (2017)</p>
+
+    <ul>
+    <li>[x] CPU: Intel Pentium N3710</li>
+    </ul></li>
+    <li><p>[x] Lenovo ThinkPad T480 (2018)</p>
+
+    <ul>
+    <li>[x] CPU: Intel Core i5-8350U</li>
+    <li>[ ] NIC: Intel I219-LM</li>
+    </ul></li>
+    </ul>
+  </body>
+</html>

www/hex.png

@@ -1 +0,0 @@
-../doc/hex.png

www/images/2048.png

@@ -0,0 +1 @@
+../../doc/images/2048.png

www/images/chess.png

@@ -0,0 +1 @@
+../../doc/images/chess.png

www/images/dark.png

@@ -0,0 +1 @@
+../../doc/images/dark.png

www/images/edit.png

@@ -0,0 +1 @@
+../../doc/images/edit.png

www/images/find.png

@@ -0,0 +1 @@
+../../doc/images/find.png

www/images/hex.png

@@ -0,0 +1 @@
+../../doc/images/hex.png

www/images/life.png

@@ -0,0 +1 @@
+../../doc/images/life.png

www/images/light.png

@@ -0,0 +1 @@
+../../doc/images/light.png

www/images/lisp.png

@@ -0,0 +1 @@
+../../doc/images/lisp.png

www/images/moros.png

@@ -0,0 +1 @@
+../../doc/images/moros.png

www/images/network.png

@@ -0,0 +1 @@
+../../doc/images/network.png

www/images/shell.png

@@ -0,0 +1 @@
+../../doc/images/shell.png

www/images/usage.png

@@ -0,0 +1 @@
+../../doc/images/usage.png

www/index.html

@@ -8,12 +8,14 @@
   <body>
     <h1>MOROS: Obscure Rust Operating System</h1>
 
-    <p><img src="moros.png" alt="screenshot"></p>
+    <p><img src="images/moros.png" alt="screenshot"></p>
 
-    <p>MOROS is a hobby operating system written in Rust by <a href="https://vinc.cc">Vincent Ollivier</a>.</p>
+    <p>MOROS is a hobby operating system written in Rust by
+    <a href="https://vinc.cc">Vincent Ollivier</a>.</p>
 
-    <p>It targets computers with a x86-64 architecture and a BIOS, so mostly from 2005
-to 2020, but it also runs well on most emulators (Bochs, QEMU, and VirtualBox).</p>
+    <p>It targets <a href="hardware.html#computers">computers</a> with a x86-64 architecture and a
+BIOS, so mostly from 2005 to 2020, but it also runs well on most
+    <a href="hardware.html#emulators">emulators</a>.</p>
 
     <h2>Usage</h2>
 
@@ -28,40 +30,41 @@ rather minimalist.</p>
 
     <p>It has a <a href="shell.html">shell</a>:</p>
 
-    <p><img src="shell.png" alt="screenshot"></p>
+    <p><img src="images/shell.png" alt="screenshot"></p>
 
     <p>With a few programs like <code>find</code> that use a <a href="regex.html">regex engine</a> to find
 files or lines:</p>
 
-    <p><img src="find.png" alt="screenshot"></p>
+    <p><img src="images/find.png" alt="screenshot"></p>
 
     <p>It has a <a href="calculator.html">calculator</a> and also a <a href="lisp.html">lisp</a> interpreter:</p>
 
-    <p><img src="lisp.png" alt="screenshot"></p>
+    <p><img src="images/lisp.png" alt="screenshot"></p>
 
     <p>And a <a href="editor.html">text editor</a>:</p>
 
-    <p><img src="edit.png" alt="screenshot"></p>
+    <p><img src="images/edit.png" alt="screenshot"></p>
 
-    <p>It has a <a href="network.html">network stack</a> with two drivers for RTL8139 and PCNET cards:</p>
+    <p>It has a <a href="network.html">network stack</a> with two drivers for RTL8139 and PCNET
+cards:</p>
 
-    <p><img src="network.png" alt="screenshot"></p>
+    <p><img src="images/network.png" alt="screenshot"></p>
 
-    <p>It has a chess game:</p>
+    <p>It has a <a href="games.html#chess">chess game</a>:</p>
 
-    <p><img src="chess.png" alt="chess"></p>
+    <p><img src="images/chess.png" alt="chess"></p>
 
-    <p>And the game of life:</p>
+    <p>And the <a href="games.html#conways-game-of-life">game of life</a>:</p>
 
-    <p><img src="life.png" alt="life"></p>
+    <p><img src="images/life.png" alt="life"></p>
 
-    <p>It even has 2048:</p>
+    <p>It even has <a href="games.html#2048">2048</a>:</p>
 
-    <p><img src="2048.png" alt="2048"></p>
+    <p><img src="images/2048.png" alt="2048"></p>
 
     <p>And finally it is quite customizable:</p>
 
-    <p><img src="light.png" alt="light"></p>
+    <p><img src="images/light.png" alt="light"></p>
 
     <h2>Demo</h2>
 

www/life.png

@@ -1 +0,0 @@
-../doc/life.png

www/light.png

@@ -1 +0,0 @@
-../doc/light.png

www/lisp.png

@@ -1 +0,0 @@
-../doc/lisp.png

www/moros.png

@@ -1 +0,0 @@
-../doc/moros.png

www/network.png

@@ -1 +0,0 @@
-../doc/network.png

www/shell.png

@@ -1 +0,0 @@
-../doc/shell.png

www/usage.png

@@ -1 +0,0 @@
-../doc/usage.png