Improving formatting in documentation

info.yaml

@@ -30,93 +30,92 @@ documentation:
 
 # Longer description of how the project works. You can use standard markdown format.
   how_it_works: |
-      This Verilog implementation is a replica of a classical [SN76489](https://en.wikipedia.org/wiki/Texas_Instruments_SN76489) programmable sound generator.
-      The whole SN76489 fits on a **single** TinyTapeout **tile** and it consists of roughly a **1000** logic gates. Absolutely tiny by the modern standards!
+      This Verilog implementation is a replica of a classical **[SN76489](https://en.wikipedia.org/wiki/Texas_Instruments_SN76489)** programmable sound generator.
+      The whole SN76489 is roughly a 1000 logic gates and fits on a **single tile** in TinyTapeout - absolutely tiny by the modern standards!
 
-      The aims of this project are:
-      1. **closely** replicate the behavior and design of the original SN76489 chip
-      2. while being produced with the **modern fabrication** process.
+      ### Modern replica of a classic
+      The aims of this project are to closely **replicate** the behavior and **design of the original** SN76489 while leveraging the **modern fabrication** process.
 
       Additional goal is to provide a readable and well documented code for educational and hardware **preservation** purposes.
       Significant effort was put into a thorough **test suite** for regression testing and validation against the original chip behavior.
 
-      ## The future goals
+      ### The future goals
 
-      Incorporate analog OpAmp into the design to match the original SN76489 schematics.
+      The next stage is to incorporate analog OpAmp into the design in order to completely match the original SN76489.
 
       # Chip technical capabilities
 
       - **3 square wave** tone generators
       - **1 noise** generator
-      - 2 types of noise, **white** and **periodic**
+      - 2 types of noise: *white* and *periodic*
       - Capable to produce a range of waves typically from **122 Hz** to **125 kHz**, defined by **10-bit** registers.
       - **16** different volume levels
 
+      ### Module parametrization
+
+      The module is parameterized to replicate the behavior of several SN76489 variants by providing options for:
+
+      - noise tapped bits
+      - tone counter and noise LFSR shift register size
+      - variable clock divider
+
       # Historical use of SN76489
 
       SN76489 family of programmable sound generators was introduced by Texas Instruments in 1980. Variants of SN76489 were used in a number of home computers, game consoles and arcade boards:
 
-      - home computers: TI-99/4, BBC Micro, IBM PCjr, Sega SC-3000, Tandy 1000
-      - game consoles: ColecoVision, Sega SG-1000, Sega Master System, Game Gear, Neo Geo Pocket and Sega Genesis
+      - home computers: [TI-99/4](https://en.wikipedia.org/wiki/TI-99/4A), [BBC Micro](https://en.wikipedia.org/wiki/BBC_Micro), [IBM PCjr](https://en.wikipedia.org/wiki/IBM_PCjr), [Sega SC-3000](https://en.wikipedia.org/wiki/SG-1000#SC-3000), [Tandy 1000](https://en.wikipedia.org/wiki/Tandy_1000)
+      - game consoles: [ColecoVision](https://en.wikipedia.org/wiki/ColecoVision), [Sega SG-1000](https://en.wikipedia.org/wiki/SG-1000), [Sega Master System](https://en.wikipedia.org/wiki/Master_System), [Game Gear](https://en.wikipedia.org/wiki/Game_Gear), [Neo Geo Pocket and Sega Genesis](https://en.wikipedia.org/wiki/Sega_Genesis)
       - arcade machines by Sega & Konami and would usually include 2 or 4 SN76489 chips
       
-      The SN76489 chip family competed with the similar General Instrument AY-3-8910.
+      The SN76489 chip family competed with the similar [General Instrument AY-3-8910](https://en.wikipedia.org/wiki/General_Instrument_AY-3-8910).
 
-      # Module parametrization
-
-      The module is parameterized to replicate the behavior of several SN76489 variants by providing options for:
-      - noise tapped bits,
-      - tone counter and noise LFSR shift register size,
-      - variable clock divider
-
-      # Difference from the original hardware
+      # Differences from the original hardware
 
       This Verilog implementation being a completely digital and synchronous design has the following differences from the original SN76489 design.
 
-      ## Audio signal output
+      #### Audio signal output
 
       While the original chip had analog summation of the channels with integrated OpAmp and sported a single analog output, this implementation does digital signal summation and digital output.
       The module provides two alternative outputs for the generated audio signal:
       1. digital 8-bit audio output suitable for external Digital to Analog Converter (DAC)
       2. pseudo analog output on a single pin using Pulse Width Modulation (PWM)
 
-      ## Separate 4 channel output
+      #### Separate 4 channel output
 
       Outputs of all 4 channels are exposed along with the master output. This allows to validate and mix signals externally.
       In contrast the original chip was limited to a single audio output pin due to PDIP-16 package.
 
-      ## No DC offset
+      #### No DC offset
 
       This implementation produces unsigned output waveforms without DC offset.
 
-      ## **/OE** and **READY** pins are omitted for simplicity
+      #### **/OE** and **READY** pins are omitted for simplicity
 
       **/OE** control pin is omitted in this design. The behavior is the same as if **/OE** is tied *low* and chip is always enabled.
 
       Unlike the original SN76489 which took 32 cycles to update registers, this implementation updates registers in a single cycle and chip behaves as always **READY**.
 
-      ## Synchronous reset and single phase clock
+      #### Synchronous reset and single phase clock
 
       The original SN76489 design would internally employ 2 phases of the clock for the operation. As well asynchronous reset was employed.
       
       To make it easier to synthesize and test on FPGAs this implementation uses single clock phase and synchronous reset for all resisters.
 
-      ## Externally configurable clock divider
+      #### Externally configurable clock divider
 
       A configurable clock divider was introduced. Clock divider can be controlled through **SEL0** and **SEL1** control pins and allows to select between 3 chip variants:
 
-      1. the original SN76489 with the master clock divided by 16 internally. This chip was usually clocked with PAL and NTSC frequencies. In BBC Micro SN76489 was clocked at 4 MHz.
+      1. the original SN76489 with the master clock divided by 16 internally. This chip was usually clocked with PAL and NTSC frequencies. In [BBC Micro](https://en.wikipedia.org/wiki/BBC_Micro) SN76489 was clocked at 4 MHz.
       2. SN94624/SN76494 variants without internal clock divider. These chips were intended for use with 250 to 500 KHz clocks.
       3. high frequency clock configuration for TinyTapeout, suitable for a range between 25 MHz and 50 Mhz. In this configuration the master clock is internally divided by 128.
 
       # SN76489 reverse engineering
 
       This implementation is informed by the following reverse engineering efforts:
 
-      1. [Anotations and analysis](https://github.com/gchiasso/76489A-analysis) for the decapped SN76489A chip.
+      1. [Anotations and analysis](https://github.com/gchiasso/76489A-analysis) of the decapped SN76489A chip.
       2. Reverse engineered [schematics](https://github.com/emu-russia/SEGAChips/tree/main/VDP/PSG) based on decapping the Sega Mega Drive VDP chip which includes SN76496 variant.
 
-
       # Orginal datasheet and Programming Manual
       Original datasheet and programming manual can be found [here](https://ftp.whtech.com/datasheets%20and%20manuals/Datasheets%20-%20TI/SN76489.pdf).
 
@@ -148,14 +147,14 @@ documentation:
     - digital audio MSB
 # A description of what the bidirectional I/O pins do
   bidirectional:
-    - (in)  /WE inverted write enable
-    - (in)  SEL0 0 = clock div 16 (SN76489 mode), 1 = no divider (SN94624/SN76494 mode)
-    - (in)  SEL1 0 = clock div 16 (SN76489 mode), 1 = clock div 128
+    - (in)  **/WE** write enable
+    - (in)  **SEL0** 0 = clock div 16, 1 = no divider (SN94624/SN76494 mode)
+    - (in)  **SEL1** 0 = clock div 16, 1 = clock div 128
     - (out) channel 0 (PWM)
     - (out) channel 1 (PWM)
     - (out) channel 2 (PWM)
     - (out) channel 3 (PWM)
-    - (out) AUDIO OUT pseudo analog master output (PWM)
+    - (out) AUDIO OUT master output, pseudo analog (PWM)
 
 # The following fields are optional
   tag:          "psg, music, sound" # comma separated list of tags: test, encryption, experiment, clock, animation, utility, industrial, pwm, fpga, alu, microprocessor, risc, riscv, sensor, signal generator, fft, filter, music, bcd, sound, serial, timer, random number generator, calculator, decoder, counter, puzzle, multiplier, game, oscillator,