Improve documentation some more (#955)

copy · Dec 14, 2023 · a8cc97d · a8cc97d
1 parent fe7a0fb
commit a8cc97d
Show file tree

Hide file tree

Showing 6 changed files with 41 additions and 43 deletions.
diff --git a/Readme.md b/Readme.md
@@ -31,37 +31,41 @@ list of emulated hardware:
 
 ## Demos
 
+[9front](https://copy.sh/v86/?profile=9front) —
 [Arch Linux](https://copy.sh/v86/?profile=archlinux) —
-[Damn Small Linux](https://copy.sh/v86/?profile=dsl) —
+[Android-x86 1.6-r2](https://copy.sh/v86?profile=android) —
+[Android-x86 4.4-r2](https://copy.sh/v86?profile=android4) —
+[BasicLinux](https://copy.sh/v86/?profile=basiclinux) —
 [Buildroot Linux](https://copy.sh/v86/?profile=buildroot) —
+[Damn Small Linux](https://copy.sh/v86/?profile=dsl) —
+[ELKS](https://copy.sh/v86/?profile=elks) —
+[FreeDOS](https://copy.sh/v86/?profile=freedos) —
+[FreeBSD](https://copy.sh/v86/?profile=freebsd) —
+[FiwixOS](https://copy.sh/v86/?profile=fiwix) —
+[Haiku](https://copy.sh/v86/?profile=haiku) —
 [SkiffOS](https://copy.sh/v86/?profile=copy/skiffos) —
 [ReactOS](https://copy.sh/v86/?profile=reactos) —
 [Windows 2000](https://copy.sh/v86/?profile=windows2000) —
 [Windows 98](https://copy.sh/v86/?profile=windows98) —
 [Windows 95](https://copy.sh/v86/?profile=windows95) —
 [Windows 1.01](https://copy.sh/v86/?profile=windows1) —
-[MS-DOS](https://copy.sh/v86/?profile=msdos) —
-[FreeDOS](https://copy.sh/v86/?profile=freedos) —
-[FreeBSD](https://copy.sh/v86/?profile=freebsd) —
+[MS-DOS 6.22](https://copy.sh/v86/?profile=msdos) —
 [OpenBSD](https://copy.sh/v86/?profile=openbsd) —
-[9front](https://copy.sh/v86/?profile=9front) —
-[Haiku](https://copy.sh/v86/?profile=haiku) —
 [Oberon](https://copy.sh/v86/?profile=oberon) —
 [KolibriOS](https://copy.sh/v86/?profile=kolibrios) —
-[QNX](https://copy.sh/v86/?profile=qnx) —
-[Android 1.6-r2](https://copy.sh/v86?profile=android) —
-[Android 4.4](https://copy.sh/v86?profile=android4) —
-[SkiftOS](https://copy.sh/v86?profile=skift)
+[SkiftOS](https://copy.sh/v86?profile=skift) —
+[QNX](https://copy.sh/v86/?profile=qnx)
 
-## Docs
+## Documentation
 
 [How it works](docs/how-it-works.md) —
 [Networking](docs/networking.md) —
-[Archlinux guest setup](docs/archlinux.md) —
+[Arch Linux guest setup](docs/archlinux.md) —
 [Windows 2000/XP guest setup](docs/windows-xp.md) —
 [9p filesystem](docs/filesystem.md) —
 [Linux rootfs on 9p](docs/linux-9p-image.md) —
-[Profiling](docs/profiling.md)
+[Profiling](docs/profiling.md) —
+[CPU Idling](docs/cpu-idling.md)
 
 ## Compatibility
 
@@ -101,7 +105,7 @@ Here's an overview of the operating systems supported in v86:
 - SerenityOS works.
 - [SkiftOS](https://skiftos.org/) works.
 
-You can get some infos on the disk images here: https://github.com/copy/images.
+You can get some information on the disk images here: https://github.com/copy/images.
 
 ## How to build, run and embed?
 
@@ -143,7 +147,7 @@ download them directly from the website using:
 
 Run all tests: `make jshint rustfmt kvm-unit-test nasmtests nasmtests-force-jit expect-tests jitpagingtests qemutests rust-test tests`
 
-See [tests/Readme.md](tests/Readme.md) for more infos.
+See [tests/Readme.md](tests/Readme.md) for more information.
 
 ## API examples
 

diff --git a/docs/archlinux.md b/docs/archlinux.md
@@ -3,14 +3,12 @@
 Choosing an installer ISO
 -------------------------
 
-The last ISO installer version of Archlinux that supports 32-bit is [2017.02.01](https://www.archlinux.org/releng/releases/2017.02.01/). Later versions of the archisos don't work on the v86 emulator because the installer only supports x86_64, not x86 anymore.  For existing Archlinux installations, updates and patches will be done until somewhere around 2018.
-
-In the future the community might come up with an alternative distribution based on Archlinux to maintain support for x86. At this point in time [archlinux32](https://mirror.archlinux32.org) seems to work.
+Download Arch Linux 32 from  https://archlinux32.org.
 
 Basic installation using QEMU
 -----------------------
 
-Installing Archlinux like this will result in a raw disk image that can be booted by v86.
+Installing Arch Linux with these instructions will result in a raw disk image that can be booted by v86.
 
 ```sh
 # fetch archlinux32 installer
@@ -23,15 +21,15 @@ qemu-img create arch.img 10G
 qemu-system-x86_64 -m 256 -drive file=arch.img,format=raw -cdrom archlinux32-2021.12.01-i686.iso
 ```
 
-For keyboard support it is necessary to open /etc/mkinitcpio.conf and edit the following line:
+For keyboard support, it is necessary to open /etc/mkinitcpio.conf and edit the following line:
 
 ```sh
 MODULES="atkbd i8042"
 ```
 
-For the changes to take effect you need to regenerate the RAMdisk with `mkinitcpio -p linux`
+For the changes to take effect, you need to regenerate the initial ramdisk with `mkinitcpio -p linux`
 
-The resulting `arch.img` is a bootable disk image for v86.
+The resulting `arch.img` file is a bootable disk image for v86.
 
 Scripting image creation for v86
 --------------------------------
@@ -42,7 +40,7 @@ Installing the ISO by hand takes a long time if you intend to recreate the image
 
 [Packer](https://www.packer.io/docs/builders/qemu.html) is a tool that lets you boot an ISO in any of multiple emulators (so QEMU in our case) and send pre-scripted keystrokes to bootstrap and SSH server. Once the SSH connection is established a script can be started for further provisioning.
 
-Create a template for automating the base installation
+Create a template for automating the base installation:
 ```sh
 mkdir -p packer
 cat > packer/template.json << 'EOF'
@@ -90,20 +88,20 @@ cat > packer/template.json << 'EOF'
 EOF
 ```
 
-You can tweak the options a bit to match your situation. For debugging you can set `headless` to `false`. That will show you the vnc instead of running the `boot_command` in the background. For a `base` pacstrap using a 1.5G disk should be sufficient. The `raw` disk format is important. v86 does not read qcow2 images, only raw disk images. If your system does not support kvm (the default accelerator), you can change `"accelerator": "none"` to the settings, in macos you may use `"accelerator": "hvf"`. Other accelerator options can be found [here](https://www.packer.io/docs/builders/qemu.html#accelerator).
+You can tweak the options a bit to match your situation. For debugging, you can set `headless` to `false`. That will show you the VNC connection instead of running the `boot_command` in the background. For a `base` pacstrap, using a 2 GB disk image should be sufficient. The `raw` disk format is important. v86 does not read qcow2 images, only raw disk images. If your system does not support KVM (the default accelerator), you can change `"accelerator": "none"` to the settings, in macos you may use `"accelerator": "hvf"`. Other accelerator options can be found [here](https://www.packer.io/docs/builders/qemu.html#accelerator).
 
 After gaining SSH connectivity to the VM, packer will run the `scripts/provisioning.sh` script in the guest.
 
-### Creating the Archlinux installation script
+### Creating the Arch Linux installation script
 
-Create a script for your Archlinux installation. This runs in the ISO booted Archlinux environment, so you need to partition, pacstrap and install a bootloader.
+Create a script for your Arch Linux installation. This runs in the live Arch Linux environment, so you need to partition the disk, do a pacstrap, and install a bootloader.
 ```sh
 mkdir -p packer/scripts
 ### Write your own or copy paste the example below
 vim packer/scripts/provision.sh
 ```
 
-An example script to install Archlinux with the root mounted using the 9p network filesystem:
+An example script to install Arch Linux with the root mounted using the 9p network filesystem:
 ```sh
 #!/bin/bash
 echo "Creating a GPT partition on /dev/sda1"
@@ -132,7 +130,7 @@ pacman -Sy archlinux-keyring --noconfirm
 # uncomment to remove signing if unable to resolve signing errors
 sed -i 's/SigLevel.*/SigLevel = Never/g' /etc/pacman.conf
 
-# Install the Archlinux base system, feel free to add packages you need here
+# Install the Arch Linux base system, feel free to add packages you need here
 echo "Performing pacstrap"
 pacstrap -i /mnt base linux dhcpcd curl openssh --noconfirm
 
@@ -300,7 +298,7 @@ EOF
 umount -R /mnt
 ```
 
-With the packer template and the script you have enough to create an image that can be booted by v86. But because this example script installs an Archlinux that wants to mount root over the network with 9p, we need to host that filesystem first. If you do not want to use 9p, you can just run `(cd packer && packer build -force template.json)` to build the image.
+With the packer template and the script you have enough to create an image that can be booted by v86. But because this example script installs an Arch Linux that wants to mount root over the network with 9p, we need to host that filesystem first. If you do not want to use 9p, you can just run `(cd packer && packer build -force template.json)` to build the image.
 
 ### Creating the 9p filesystem
 
@@ -382,7 +380,7 @@ Generated artifacts are now available for serving from `output`.
 
 ### Using the created artifacts in v86
 
-Now that we have everything we need to host a server that serves an Archlinux environment over the network.
+Now that we have everything we need to host a server that serves an Arch Linux environment over the network.
 
 Create a checkout of v86 and run `make build/libv86.js`.
 We can then edit `examples/arch.html`, we have two options:
@@ -405,7 +403,7 @@ We can then edit `examples/arch.html`, we have two options:
   acpi: false,
   autostart: true,
   ```
-2. Boot the archlinux from the qemu raw disk image:
+2. Boot the Arch Linux from the qemu raw disk image:
 
   ```sh
   hda: {

diff --git a/docs/cpu-idling.md b/docs/cpu-idling.md
@@ -1,6 +1,5 @@
 Some operating systems don't support `hlt` instruction, because of this, the CPU spin loops instead of idling.
-Here some solutions for different OSes:
-
+Here are some solutions for different OSes:
 
 ## MS-DOS (using DOSIdle)
 1. Download `DOSID251.zip` from https://www.vogons.org/viewtopic.php?p=438763#p438763
@@ -11,20 +10,17 @@ Here some solutions for different OSes:
 
 **Note:** To hide output when starting DOSIdle, change `C:\path\to\dosidle.exe` to `C:\path\to\dosidle.exe > nul` on step №4.
 
-
 ## FreeDOS ([source](https://narkive.com/UGrcO8wU.2))
 1. Run `edit C:\fdconfig.sys` (or `edit C:\config.sys`)
 2. Add to file: `IDLEHALT=1`
 3. Save changes (*press Alt + F and x*) and restart FreeDOS.
 
-
 ## Windows 9x (using AmnHLT)
 1. Download `amnhltm.zip` from http://toogam.com/software/archive/drivers/cpu/cpuidle/amnhltm.zip ([mirror](https://web.archive.org/web/20060212132151/http://www.user.cityline.ru/~maxamn/amnhltm.zip))
-2. Unzip archive in any location.
-3. **Note**: If you have installed VBE9x, restart Windows, press F8 on boot, select *Command prompt only*, run `cd C:\path\to\amnhlt\` and follow to next step.
+2. Unzip the archive in any location.
+3. **Note**: If you have installed VBE9x, restart Windows, press F8 on boot, select *Command prompt only*, run `cd C:\path\to\amnhlt\`, and follow to the next step.
 4. Run `AMNHLT.BAT`
-5. Restart Windows, and while next booting AmnHLT starts automatically (you can safely delete archive and unpacked folder).
-
+5. Restart Windows, and AmnHLT will start automatically on next boot (you can safely delete archive and unpacked folder).
 
 ## Windows 98+ and Unix-like
 These systems are already supports `hlt`, no further action is required.
diff --git a/docs/filesystem.md b/docs/filesystem.md
@@ -1,4 +1,4 @@
-A 9p filesystem is supported by the emulator, using a virtio transport. Using
+A 9p filesystem is supported by v86, using a virtio transport. Using
 it, files can be exchanged with the guest OS, see `create_file` and `read_file`
 in [`starter.js`](https://github.com/copy/v86/blob/master/src/browser/starter.js).
 It can be enabled by passing the following options to `V86`:

diff --git a/docs/linux-9p-image.md b/docs/linux-9p-image.md
@@ -1,4 +1,4 @@
-In order to create a Linux image that can mount the 9p file system, use add the following lines to the kernel config:
+In order to create a Linux image that can mount the 9p file system, add the following lines to the kernel configuration:
 
 ```
 CONFIG_NET_9P=y

diff --git a/docs/networking.md b/docs/networking.md
@@ -2,7 +2,7 @@
 
 Emulating a network card is supported. It can be used by passing the
 `network_relay_url` option to `V86`. The url must point to a running
-WebSockets Proxy. The source code for WebSockets Proxy can be found at
+WebSockets Proxy. The source code for the WebSockets Proxy can be found at
 [benjamincburns/websockproxy](https://github.com/benjamincburns/websockproxy).
 An alternative, Node-based implementation is
 [krishenriksen/node-relay](https://github.com/krishenriksen/node-relay).
@@ -43,5 +43,5 @@ sending and receiving packets correctly. There are several workarounds:
   don't need any of the above workarounds. This seems to be the case for Haiku,
   OpenBSD and FreeBSD.
 
-Note that the same applies to IP addresses, so a dhcp client should only be run
+Note that the same applies to IP addresses, so a DHCP client should only be run
 after the state has been loaded.