doc: cleanup links and formatting

1 files changed, 23 insertions, 8 deletions

diff --git a/README.rst b/README.rst
index ccf3036e..bc635ea4 100644
--- a/README.rst
+++ b/README.rst
@@ -122,21 +122,22 @@ Virtual File System (VFS)
 
 A POSIX-like directory and file abstraction layer is located in `kernel/filesystem/ <kernel/kernel/filesystem>`_:
 
-* **Abstractions**: Managed via directory entries (`dentry.hpp <kernel/kernel/filesystem/dentry.hpp>`_), filesystem nodes (`inode.hpp <kernel/kernel/filesystem/inode.hpp>`_), mount hierarchies (`mount.hpp <kernel/kernel/filesystem/mount.hpp>`_), and open file tables (`open_file_table.hpp <kernel/kernel/filesystem/open_file_table.hpp>`_).
+* **Abstractions**: Managed via `directory entries <kernel/kernel/filesystem/dentry.hpp>`_,  `filesystem nodes <kernel/kernel/filesystem/inode.hpp>`_,  `mount hierarchies <kernel/kernel/filesystem/mount.hpp>`_, and the `open file table <kernel/kernel/filesystem/open_file_table.hpp>`_.
 * **Concrete Filesystems**:
-  - `rootfs <kernel/kernel/filesystem/rootfs/filesystem.hpp>`_: An in-memory filesystem mounted at `/`.
-  - `devfs <kernel/kernel/filesystem/devfs/filesystem.hpp>`_: Exposes devices as files under `/dev`.
-  - `ext2 <kernel/kernel/filesystem/ext2/filesystem.hpp>`_: An Ext2 read/write driver operating on RAM disks loaded as multiboot modules.
+
+  - `RootFS <kernel/kernel/filesystem/rootfs>`_: An in-memory filesystem mounted at `/` during early boot.
+  - `Device FS <kernel/kernel/filesystem/devfs>`_: Exposes devices as files under `/dev`.
+  - `Second Extended Filesystem <kernel/kernel/filesystem/ext2>`_: An Ext2 driver.
 
 Standalone Support Libraries
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Standalone support libraries under `libs/ <libs>`_ compile independently of the kernel logic:
 
-* `kstd <libs/kstd/kstd>`_: A custom standard library containing containers, support infrastructure, and printing/formatting implementations in lieu of a hosted standard library.
-* `multiboot2 <libs/multiboot2/multiboot2/information.hpp>`_: A Multiboot2 structure parser.
-* `acpi <libs/acpi/acpi/acpi.hpp>`_: An ACPI parsing utility.
-* `elf <libs/elf/elf/section_header.hpp>`_: An ELF file format parser.
+* `kstd <libs/kstd>`_: A custom standard library containing containers, support infrastructure, and printing/formatting implementations in lieu of a hosted standard library.
+* `multiboot2 <libs/multiboot2>`_: A Multiboot2 structure parser.
+* `acpi <libs/acpi>`_: An ACPI parsing utility.
+* `elf <libs/elf>`_: An ELF file format parser.
 
 Semester & Bachelor's Thesis Opportunities
 ------------------------------------------
@@ -154,10 +155,12 @@ Conversely, user space isolation requires page table management and hardware pri
 These projects should be approached sequentially or as a joint effort:
 
 1. **Kernel Multitasking (Cooperative and Preemptive)**:
+
    - *Scope*: Design a Thread Control Block (TCB) and Process Control Block (PCB) structure. Implement low-level stack setup and context switching in assembly for the active CPU.
    - *Extension*: Develop a task scheduler (e.g., Round-Robin, Priority-based, or Multi-Level Feedback Queue) utilizing the local APIC timer for preemptive multitasking.
 
 2. **User Mode Isolation and System Call Interface**:
+
    - *Prerequisite*: A basic multitasking or thread control subsystem.
    - *Scope*: Implement user-kernel privilege transitions (Ring 3 to Ring 0) utilizing platform-specific instructions. Configure page tables to separate user space virtual memory from the higher-half kernel mapping.
    - *Extension*: Establish a system call dispatcher routing file and memory operations from user space to the corresponding `kapi/ <kapi>`_ implementations.
@@ -169,9 +172,11 @@ TeachOS currently targets only 64-bit x86 (`x86_64`).
 To validate the platform-independence of the `kapi/ <kapi>`_ interface, ports to other 64-bit targets are highly encouraged:
 
 3. **ARM64 (AArch64) Port**:
+
    - *Scope*: Implement the platform-defined KAPI interfaces for a 64-bit ARM target (e.g., QEMU `virt` board or Raspberry Pi 4). This includes writing the boot startup assembly, configuring the translation table (MMU paging), handling the Generic Interrupt Controller (GIC), and implementing timer ticks.
 
 4. **RISC-V 64-bit (RV64G) Port**:
+
    - *Scope*: Port TeachOS to the RISC-V 64-bit architecture. This involves implementing boot assembly, configuring page table mappings (Sv39/Sv48), setting up the Core Local Interruptor (CLINT) and Platform-Level Interrupt Controller (PLIC), and managing supervisor/user mode transitions.
 
 Memory Management Subsystem Extensions
@@ -181,12 +186,15 @@ The current memory management uses a basic bitmap page frame allocator and a fir
 There are significant opportunities to implement standard production-grade memory management schemes:
 
 5. **Buddy Page Allocator**:
+
    - *Scope*: Replace the current `bitmap_frame_allocator <kernel/kernel/memory/bitmap_allocator.hpp>`_ with a Buddy Allocator system. This manages memory allocations in power-of-two page sizes, significantly reducing external fragmentation and improving allocation speed.
 
 6. **Slab/Slub/Slob Object Allocator**:
+
    - *Scope*: Implement a slab allocator on top of the physical page allocator. This caches kernel objects of identical size (such as inodes, file descriptors, and thread control blocks) to avoid constant heap fragmentation and overhead from the general-purpose `block_list_allocator <kernel/kernel/memory/block_list_allocator.hpp>`_.
 
 7. **Advanced Virtual Memory (Copy-on-Write, Demand Paging)**:
+
    - *Prerequisite*: A basic thread multitasking subsystem.
    - *Scope*: Implement a page fault handler that dynamically loads executable segments only when touched (demand paging), or implement copy-on-write page table sharing (crucial for implementing Unix-like `fork` semantics).
 
@@ -197,15 +205,19 @@ The Virtual File System (VFS) is designed to host multiple concurrent filesystem
 Project opportunities here include implementing new drivers or core VFS caching features:
 
 8. **Ext2 Write Support and Dynamic Allocation** (already available in experimental stage):
+
    - *Scope*: Extend the read-oriented `ext2 <kernel/kernel/filesystem/ext2/filesystem.hpp>`_ driver to support full write operations. This requires managing free inode and block bitmaps, updating directories, allocating data blocks dynamically, and maintaining superblock consistency.
 
 9. **New Filesystem Drivers (e.g., FAT32, ISO 9660)**:
+
    - *Scope*: Implement new filesystem drivers from scratch (such as FAT32 or ISO 9660 for CD-ROMs), allowing TeachOS to interoperate with standard virtual media and flash drives.
 
 10. **Unified Page Cache and Directory Entry Cache**:
+
     - *Scope*: Develop a page caching subsystem that intercepts read/write VFS calls, caching recently accessed filesystem blocks in physical memory frames, and optimize pathname lookup times using a dynamic directory entry (dentry) cache.
 
 11. **Virtual Filesystems (e.g., procfs, sysfs)**:
+
     - *Scope*: Create virtual filesystems that dynamically generate contents from current kernel data structures, providing userspace with debugging and configuration access interfaces.
 
 Hardware Buses and Device Drivers
@@ -215,11 +227,14 @@ Currently, block storage is simulated via RAM disks loaded as boot modules.
 Real hardware interaction requires expanding driver support:
 
 12. **PCI/PCIe Bus Discovery**:
+
     - *Scope*: Develop a PCI/PCIe bus driver that scans configuration spaces, detects connected devices, and registers them to the virtual root bus using the `kapi::devices <kapi/kapi/devices.hpp>`_ interface.
 
 13. **Storage Controller Drivers (AHCI/SATA or NVMe)**:
+
     - *Prerequisite*: PCI bus discovery.
     - *Scope*: Write a driver for SATA controllers (AHCI) or modern NVMe drives, routing block read/write operations from the VFS to actual physical disks.
 
 14. **Network Stack and Driver Integration**:
+    
     - *Scope*: Interface with a network adapter (e.g., Intel e1000 or VirtIO-net), and develop a lightweight network stack (ARP, IPv4, UDP) to allow TeachOS to send and receive raw network frames.