From 02c1b7f52a8a232d9c9952868eb53874e149238b Mon Sep 17 00:00:00 2001
From: Vincent Ollivier
Date: Sun, 19 Nov 2023 21:03:10 +0100
Subject: [PATCH] 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 | 13 ++++++
CONTRIBUTING.md | 40 ++++++++++++++++
Makefile | 2 +-
README.md | 50 ++++++++++----------
doc/games.md | 13 ++++++
doc/hardware.md | 50 ++++++++++++++++++++
doc/{ => images}/2048.png | Bin
doc/{ => images}/chess.png | Bin
doc/{ => images}/dark.png | Bin
doc/{ => images}/edit.png | Bin
doc/{ => images}/find.png | Bin
doc/{ => images}/hex.png | Bin
doc/{ => images}/life.png | Bin
doc/{ => images}/light.png | Bin
doc/{ => images}/lisp.png | Bin
doc/{ => images}/moros.png | Bin
doc/{ => images}/network.png | Bin
doc/{ => images}/shell.png | Bin
doc/{ => images}/usage.png | Bin
doc/index.md | 42 ++++++++---------
dsk/var/www/moros.png | 2 +-
src/usr/install.rs | 2 +-
www/2048.png | 1 -
www/build.sh | 5 +-
www/chess.png | 1 -
www/dark.png | 1 -
www/edit.png | 1 -
www/find.png | 1 -
www/games.html | 23 +++++++++
www/hardware.html | 88 +++++++++++++++++++++++++++++++++++
www/hex.png | 1 -
www/images/2048.png | 1 +
www/images/chess.png | 1 +
www/images/dark.png | 1 +
www/images/edit.png | 1 +
www/images/find.png | 1 +
www/images/hex.png | 1 +
www/images/life.png | 1 +
www/images/light.png | 1 +
www/images/lisp.png | 1 +
www/images/moros.png | 1 +
www/images/network.png | 1 +
www/images/shell.png | 1 +
www/images/usage.png | 1 +
www/index.html | 37 ++++++++-------
www/life.png | 1 -
www/light.png | 1 -
www/lisp.png | 1 -
www/moros.png | 1 -
www/network.png | 1 -
www/shell.png | 1 -
www/usage.png | 1 -
52 files changed, 311 insertions(+), 82 deletions(-)
create mode 100644 CONTRIBUTING.md
create mode 100644 doc/games.md
create mode 100644 doc/hardware.md
rename doc/{ => images}/2048.png (100%)
rename doc/{ => images}/chess.png (100%)
rename doc/{ => images}/dark.png (100%)
rename doc/{ => images}/edit.png (100%)
rename doc/{ => images}/find.png (100%)
rename doc/{ => images}/hex.png (100%)
rename doc/{ => images}/life.png (100%)
rename doc/{ => images}/light.png (100%)
rename doc/{ => images}/lisp.png (100%)
rename doc/{ => images}/moros.png (100%)
rename doc/{ => images}/network.png (100%)
rename doc/{ => images}/shell.png (100%)
rename doc/{ => images}/usage.png (100%)
delete mode 120000 www/2048.png
delete mode 120000 www/chess.png
delete mode 120000 www/dark.png
delete mode 120000 www/edit.png
delete mode 120000 www/find.png
create mode 100644 www/games.html
create mode 100644 www/hardware.html
delete mode 120000 www/hex.png
create mode 120000 www/images/2048.png
create mode 120000 www/images/chess.png
create mode 120000 www/images/dark.png
create mode 120000 www/images/edit.png
create mode 120000 www/images/find.png
create mode 120000 www/images/hex.png
create mode 120000 www/images/life.png
create mode 120000 www/images/light.png
create mode 120000 www/images/lisp.png
create mode 120000 www/images/moros.png
create mode 120000 www/images/network.png
create mode 120000 www/images/shell.png
create mode 120000 www/images/usage.png
delete mode 120000 www/life.png
delete mode 120000 www/light.png
delete mode 120000 www/lisp.png
delete mode 120000 www/moros.png
delete mode 120000 www/network.png
delete mode 120000 www/shell.png
delete mode 120000 www/usage.png
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 33e03fc..7fb78dc 100644
--- a/CHANGELOG.md
+++ b/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))
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..a22ba4a
--- /dev/null
+++ b/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)
diff --git a/Makefile b/Makefile
index f397edf..ce4d3a9 100644
--- a/Makefile
+++ b/Makefile
@@ -100,4 +100,4 @@ website:
clean:
cargo clean
- rm -f www/*.html www/*.png
+ rm -f www/*.html www/images/*.png
diff --git a/README.md b/README.md
index 7b9dce7..99ff7be 100644
--- a/README.md
+++ b/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
diff --git a/doc/games.md b/doc/games.md
new file mode 100644
index 0000000..a1ec695
--- /dev/null
+++ b/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)
diff --git a/doc/hardware.md b/doc/hardware.md
new file mode 100644
index 0000000..f1aebd2
--- /dev/null
+++ b/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
diff --git a/doc/2048.png b/doc/images/2048.png
similarity index 100%
rename from doc/2048.png
rename to doc/images/2048.png
diff --git a/doc/chess.png b/doc/images/chess.png
similarity index 100%
rename from doc/chess.png
rename to doc/images/chess.png
diff --git a/doc/dark.png b/doc/images/dark.png
similarity index 100%
rename from doc/dark.png
rename to doc/images/dark.png
diff --git a/doc/edit.png b/doc/images/edit.png
similarity index 100%
rename from doc/edit.png
rename to doc/images/edit.png
diff --git a/doc/find.png b/doc/images/find.png
similarity index 100%
rename from doc/find.png
rename to doc/images/find.png
diff --git a/doc/hex.png b/doc/images/hex.png
similarity index 100%
rename from doc/hex.png
rename to doc/images/hex.png
diff --git a/doc/life.png b/doc/images/life.png
similarity index 100%
rename from doc/life.png
rename to doc/images/life.png
diff --git a/doc/light.png b/doc/images/light.png
similarity index 100%
rename from doc/light.png
rename to doc/images/light.png
diff --git a/doc/lisp.png b/doc/images/lisp.png
similarity index 100%
rename from doc/lisp.png
rename to doc/images/lisp.png
diff --git a/doc/moros.png b/doc/images/moros.png
similarity index 100%
rename from doc/moros.png
rename to doc/images/moros.png
diff --git a/doc/network.png b/doc/images/network.png
similarity index 100%
rename from doc/network.png
rename to doc/images/network.png
diff --git a/doc/shell.png b/doc/images/shell.png
similarity index 100%
rename from doc/shell.png
rename to doc/images/shell.png
diff --git a/doc/usage.png b/doc/images/usage.png
similarity index 100%
rename from doc/usage.png
rename to doc/images/usage.png
diff --git a/doc/index.md b/doc/index.md
index b54876a..61b6189 100644
--- a/doc/index.md
+++ b/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
-
diff --git a/dsk/var/www/moros.png b/dsk/var/www/moros.png
index 2dc35f0..02777ca 120000
--- a/dsk/var/www/moros.png
+++ b/dsk/var/www/moros.png
@@ -1 +1 @@
-../../../www/moros.png
\ No newline at end of file
+../../../www/images/moros.png
\ No newline at end of file
diff --git a/src/usr/install.rs b/src/usr/install.rs
index 7ff941f..e9f0c0d 100644
--- a/src/usr/install.rs
+++ b/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> {
diff --git a/www/2048.png b/www/2048.png
deleted file mode 120000
index 307cc33..0000000
--- a/www/2048.png
+++ /dev/null
@@ -1 +0,0 @@
-../doc/2048.png
\ No newline at end of file
diff --git a/www/build.sh b/www/build.sh
index e8f3ca8..962202c 100644
--- a/www/build.sh
+++ b/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
diff --git a/www/chess.png b/www/chess.png
deleted file mode 120000
index 7dcf4c6..0000000
--- a/www/chess.png
+++ /dev/null
@@ -1 +0,0 @@
-../doc/chess.png
\ No newline at end of file
diff --git a/www/dark.png b/www/dark.png
deleted file mode 120000
index 688a6d7..0000000
--- a/www/dark.png
+++ /dev/null
@@ -1 +0,0 @@
-../doc/dark.png
\ No newline at end of file
diff --git a/www/edit.png b/www/edit.png
deleted file mode 120000
index 45069c7..0000000
--- a/www/edit.png
+++ /dev/null
@@ -1 +0,0 @@
-../doc/edit.png
\ No newline at end of file
diff --git a/www/find.png b/www/find.png
deleted file mode 120000
index 5f95f57..0000000
--- a/www/find.png
+++ /dev/null
@@ -1 +0,0 @@
-../doc/find.png
\ No newline at end of file
diff --git a/www/games.html b/www/games.html
new file mode 100644
index 0000000..ed58f05
--- /dev/null
+++ b/www/games.html
@@ -0,0 +1,23 @@
+
+
+
+
+ MOROS Games
+
+
+
+
+
+
diff --git a/www/hex.png b/www/hex.png
deleted file mode 120000
index 1613804..0000000
--- a/www/hex.png
+++ /dev/null
@@ -1 +0,0 @@
-../doc/hex.png
\ No newline at end of file
diff --git a/www/images/2048.png b/www/images/2048.png
new file mode 120000
index 0000000..bd27f56
--- /dev/null
+++ b/www/images/2048.png
@@ -0,0 +1 @@
+../../doc/images/2048.png
\ No newline at end of file
diff --git a/www/images/chess.png b/www/images/chess.png
new file mode 120000
index 0000000..c89c7d4
--- /dev/null
+++ b/www/images/chess.png
@@ -0,0 +1 @@
+../../doc/images/chess.png
\ No newline at end of file
diff --git a/www/images/dark.png b/www/images/dark.png
new file mode 120000
index 0000000..2e69168
--- /dev/null
+++ b/www/images/dark.png
@@ -0,0 +1 @@
+../../doc/images/dark.png
\ No newline at end of file
diff --git a/www/images/edit.png b/www/images/edit.png
new file mode 120000
index 0000000..ac8fa7e
--- /dev/null
+++ b/www/images/edit.png
@@ -0,0 +1 @@
+../../doc/images/edit.png
\ No newline at end of file
diff --git a/www/images/find.png b/www/images/find.png
new file mode 120000
index 0000000..fc61353
--- /dev/null
+++ b/www/images/find.png
@@ -0,0 +1 @@
+../../doc/images/find.png
\ No newline at end of file
diff --git a/www/images/hex.png b/www/images/hex.png
new file mode 120000
index 0000000..e9c4895
--- /dev/null
+++ b/www/images/hex.png
@@ -0,0 +1 @@
+../../doc/images/hex.png
\ No newline at end of file
diff --git a/www/images/life.png b/www/images/life.png
new file mode 120000
index 0000000..c593c49
--- /dev/null
+++ b/www/images/life.png
@@ -0,0 +1 @@
+../../doc/images/life.png
\ No newline at end of file
diff --git a/www/images/light.png b/www/images/light.png
new file mode 120000
index 0000000..1e408d4
--- /dev/null
+++ b/www/images/light.png
@@ -0,0 +1 @@
+../../doc/images/light.png
\ No newline at end of file
diff --git a/www/images/lisp.png b/www/images/lisp.png
new file mode 120000
index 0000000..e8a4699
--- /dev/null
+++ b/www/images/lisp.png
@@ -0,0 +1 @@
+../../doc/images/lisp.png
\ No newline at end of file
diff --git a/www/images/moros.png b/www/images/moros.png
new file mode 120000
index 0000000..220aa26
--- /dev/null
+++ b/www/images/moros.png
@@ -0,0 +1 @@
+../../doc/images/moros.png
\ No newline at end of file
diff --git a/www/images/network.png b/www/images/network.png
new file mode 120000
index 0000000..c5c6b95
--- /dev/null
+++ b/www/images/network.png
@@ -0,0 +1 @@
+../../doc/images/network.png
\ No newline at end of file
diff --git a/www/images/shell.png b/www/images/shell.png
new file mode 120000
index 0000000..90bf810
--- /dev/null
+++ b/www/images/shell.png
@@ -0,0 +1 @@
+../../doc/images/shell.png
\ No newline at end of file
diff --git a/www/images/usage.png b/www/images/usage.png
new file mode 120000
index 0000000..c578b57
--- /dev/null
+++ b/www/images/usage.png
@@ -0,0 +1 @@
+../../doc/images/usage.png
\ No newline at end of file
diff --git a/www/index.html b/www/index.html
index c3f7d36..7e13d52 100644
--- a/www/index.html
+++ b/www/index.html
@@ -8,12 +8,14 @@
MOROS: Obscure Rust Operating System
-
+
-
MOROS is a hobby operating system written in Rust by Vincent Ollivier.
+
MOROS is a hobby operating system written in Rust by
+ Vincent Ollivier.
-
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).
+
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.