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,68 +1,66 @@
 # 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
 
 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
 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
 
 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 [email protected]
-

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/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/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>