Improve documentation (#294)

* Add calc doc

* Link doc from readme

* Rename stdnil to stdnull

* Add items to the TODO list in the README

* Update instructions in the README

* Improve feature list in README

* Add link to doc in README

* Disable unused show command

* Add colors to chess perf command

README.md

@@ -19,31 +19,43 @@ This project started from the [seventh post][1] of the second edition of
 - [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 (using [pc-keyboard](https://crates.io/crates/pc-keyboard))
-- [x] VGA Text mode output
+- [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 enumeration
+- [x] PCI devices
 - [x] ATA PIO mode
 - [x] Random number generator (using [rand_chacha](https://crates.io/crates/rand_chacha))
 - [x] RTL8139 network card
 - [x] AMD PCNET network card
-- [x] DHCP/IP/TCP/UDP/DNS/HTTP protocols (using [smoltcp](https://crates.io/crates/smoltcp))
-- [x] Basic filesystem
-- [x] Basic shell
-- [x] Basic text editor
-- [x] Basic lisp interpreter
-- [x] Basic file and network commands
+- [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 file and [network](doc/network.md) commands
 - [x] Basic userspace for nasm binaries
-- [ ] Multitasking
+- [ ] Support for Rust binaries
+- [ ] Support for multitasking
+- [ ] C standard library port
+
+
+## Documentation
+
+Documentation is available [here](doc/index.md)
 
 
 ## Setup
 
-Install the required tools:
+Clone the repo:
+
+    $ git clone https://github.com/vinc/moros
+    $ cd moros
+
+Install the required tools with `make setup` or the following commands:
 
     $ curl https://sh.rustup.rs -sSf | sh
     $ rustup install nightly
@@ -52,11 +64,6 @@ Install the required tools:
     $ rustup component add llvm-tools-preview
     $ cargo install bootimage
 
-Clone the repo:
-
-    $ git clone https://github.com/vinc/moros
-    $ cd moros
-
 
 ## Usage
 
@@ -70,19 +77,19 @@ Run MOROS in QEMU:
 
 Run natively on a x86 computer by copying the bootloader and the kernel to a
 hard drive or USB stick (but there is currently no USB driver so the filesystem
-will not be available):
+will not be available in that case):
 
     $ sudo dd if=target/x86_64-moros/release/bootimage-moros.bin of=/dev/sdx && sync
 
-In both cases, MOROS will open a console in diskless mode after boot if no
-filesystem is detected. The following command will setup the filesystem on the
-first hard drive of the first ATA bus, allowing you to exit the diskless mode
-and log in as a normal user:
+MOROS will open a console in diskless mode after boot if no filesystem is
+detected. The following command will setup the filesystem on a hard drive,
+allowing you to exit the diskless mode and log in as a normal user:
 
     > install
 
 **Be careful not to overwrite the hard drive of your OS when using `dd` inside
-your OS, and `install` or `disk format` inside MOROS.**
+your OS, and `install` or `disk format` inside MOROS if you don't use an
+emulator.**
 
 
 ## Tests

doc/calculator.md

@@ -0,0 +1,35 @@
+# MOROS Calculator
+
+A calculator is available in MOROS using double-precision binary floating-point
+format (binary64).
+
+It can be invocked from the shell through the command `calc` with an operation
+to perform in arguments:
+
+    > calc 2 + 2
+    4
+
+And it will open a REPL if no arguments are provided:
+
+    > calc
+    MOROS Calc v0.1.0
+
+    > 2 + 2
+    4
+
+The following arithmetic operations are supported:
+
+  - `+` addition
+  - `-` subtraction
+  - `*` multiplication
+  - `/` division
+  - `%` modulo
+  - `^` exponential
+
+Parentheses `()` can change the order of operations:
+
+    > 2 + 3 * 4
+    14
+
+    > (2 + 3) * 4
+    20

doc/index.md

@@ -25,7 +25,7 @@ files or lines:
 
 ![screenshot](find.png)
 
-It also has a [lisp](lisp.md) interpreter:
+It has a [calculator](calculator.md) and also a [lisp](lisp.md) interpreter:
 
 ![screenshot](lisp.png)
 

doc/shell.md

@@ -101,11 +101,11 @@ Read file A and redirect stderr(2) to stdin(0) of write file B:
     > r a.txt 2> w b.txt
     > r a.txt 2>0 w b.txt
 
-Suppress errors by redirecting stderr(2) to stdnil(3):
+Suppress errors by redirecting stderr(2) to stdnull(3):
 
     > r a.txt 2>3 w b.txt
 
-Redirect stdout(1) to stdin(0) and stderr(2) to stdnil(3):
+Redirect stdout(1) to stdin(0) and stderr(2) to stdnull(3):
 
     > r a.txt > 2>3 w b.txt
     > r a.txt 1>0 2>3 w b.txt

src/usr/chess.rs

@@ -92,8 +92,8 @@ impl Chess {
                 "t" | "time" => self.cmd_time(args),
                 "m" | "move" => self.cmd_move(args),
                 "u" | "undo" => self.cmd_undo(args),
-                "s" | "show" => self.cmd_show(args),
                 "p" | "perf" => self.cmd_perf(args),
+                //"s" | "show" => self.cmd_show(args),
                 cmd => {
                     if cmd.is_empty() {
                         println!();
@@ -110,7 +110,6 @@ impl Chess {
 
     fn cmd_help(&mut self, _args: Vec<&str>) {
         println!("{}Commands:{}", self.csi_notif, self.csi_reset);
-        println!();
         let cmds = [
             ("q", "uit",                "Exit this program\n"),
             ("h", "elp",                "Display this screen\n"),
@@ -118,8 +117,8 @@ impl Chess {
             ("t", "ime <moves> <time>", "Set clock to <moves> in <time> (in seconds)\n"),
             ("m", "ove <move>",         "Play <move> on the board\n"),
             ("u", "ndo",                "Undo the last move\n"),
-            ("s", "how <attr>",         "Show <attr>\n"),
             ("p", "erf [<depth>]",       "Count the nodes at each depth\n"),
+            //("s", "how <attr>",         "Show <attr>\n"),
         ];
         for (alias, command, usage) in &cmds {
             let csi_col1 = Style::color("LightGreen");
@@ -136,6 +135,8 @@ impl Chess {
         println!("{}", self.game);
     }
 
+    /*
+    // TODO: implement hide command
     fn cmd_show(&mut self, args: Vec<&str>) {
         if args.len() == 1 {
             println!("{}Error:{} no <attr> given\n", self.csi_error, self.csi_reset);
@@ -151,6 +152,7 @@ impl Chess {
             }
         }
     }
+    */
 
     fn cmd_time(&mut self, args: Vec<&str>) {
         match args.len() {
@@ -227,6 +229,9 @@ impl Chess {
     }
 
     fn cmd_perf(&mut self, args: Vec<&str>) {
+        let csi_color = Style::color("Cyan");
+        let csi_reset = Style::reset();
+
         let mut depth = if args.len() > 1 {
             if let Ok(d) = args[1].parse() {
                 d
@@ -243,7 +248,7 @@ impl Chess {
             let n = self.game.perft(depth);
             let s = (((self.game.clock.system_time)() - started_at) as f64) / 1000.0;
             let nps = (n as f64) / s;
-            println!("perft {} -> {} ({:.2} s, {:.2e} nps)", depth, n, s, nps);
+            println!("{}perft {}:{} {} ({:.2} s, {:.2e} nps)", csi_color, depth, csi_reset, n, s, nps);
 
             if args.len() > 1 || sys::console::end_of_text() {
                 break;