Update documentation

README.md

@@ -52,7 +52,7 @@ $ ireal-musicxml test/data/jazz.txt --songs=Blues --validate
 ```
 
 # Theory of operation
-This module parses an iReal Pro URI or playlist file, and transforms each song it finds to a MusicXML lead sheet. The [iReal Pro format](doc/irealpro.md) does not feature melody lines, only chords and backing styles. The conversion tries to produce a high-fidelity replica of the source sheet by recreating the following aspects of the iReal Pro format:
+This module parses an iReal Pro URI or playlist file, and transforms each song it finds to a MusicXML lead sheet. The conversion process tries to produce a high-fidelity replica of the source sheet by recreating the following aspects of the [iReal Pro format](doc/irealpro.md):
 
 ## Harmonic information
 The chords found in the iReal Pro song are translated to their MusicXML representation. Because the chords supported by iReal Pro are a subset of the [harmonic expressivity of MusicXML](https://www.w3.org/2021/06/musicxml40/musicxml-reference/elements/harmony/), this translation is exact. [More information can be found in this blog post](https://blog.karimratib.me/2020/11/30/ireal-musicxml.html#emitting-correct-chord-information).

doc/irealpro.md

@@ -4,10 +4,9 @@
 - [iReal Pro File Format](https://www.irealpro.com/ireal-pro-file-format)
 - [`ireal-renderer`](https://github.com/daumling/ireal-renderer)
 
-## Application model and playback algorithm
-
+## Application model
 - iReal Pro sheets are made of rows of cells
-- Each cell can contain a chord and other music annotations such as barlines, time signature, repeats, etc.
+- Each cell can be empty or can contain a chord and other music annotations such as barlines, time signature, repeats, etc.
 - A row contains exactly 16 cells and barlines can be placed on any cell - one cell does NOT correspond to one beat!
 - The iReal Pro sequencer generates a playback sequence and detects illegal input (e.g. too many chords in a bar)
 
@@ -95,56 +94,53 @@
   - Virtual Funk
 
 ## Key signatures
-- C, Db, D, Eb, E, F, Gb, G, Ab, A, Bb, B
-- A-, Bb-, B-, C-, C#-, D-, Eb-, E-, F-, F#-, G-, G#-
+- Major: C, Db, D, Eb, E, F, Gb, G, Ab, A, Bb, B
+- Minor: A-, Bb-, B-, C-, C#-, D-, Eb-, E-, F-, F#-, G-, G#-
 
 ## Cells
-
-- T44 - time signature 44
-- (N1|N2|N3)chord - first and second house (represents ONE BAR ONLY, see _I Got Rhythm_, _Like Someone in Love_, _On the Sunny Side of the Street_, _Misty_)
-- XyQ - blank space for row alignment
-- x - repeat previous bar (see _Butterfly_)
-- Kcl or XyQKcl - also repeat previous bar (see _Besame Mucho_, _Butterfly_, _Solar_)
-- r - repeat previous 2 bars (see _Mas Que Nada_)
-- () - alternative chord written in small (above actual chord)
-- " - represents a chord separator
-- , - equivalent to space, especially for whole notes in 44
-- <stuff here> - Comments and repeat directives (can start with *yy to denote a vertical offset of yy units, see _La Fiesta_)
-- *A - section A (could be *B, *C, *i, *v, etc.)
-- S - segno (see _Butterfly_)
-- Q - coda (see _Butterfly_)
-- Y - vertical spacer (see _Nearness of You_, _Night in Tunisia_)
-- U - end (see _Mas Que Nada_, _Scrapple from the Apple_, _Triste_, _Wave_)
-- s - small chord (e.g. sC^7)
-- l - large chord (e.g. lC^7)
-- f - fermata (see _Butterfly_, _Summer Serenade_)
+- `T44` - time signature 4/4
+- `(N1|N2|N3)chord` - first and second house (represents ONE BAR ONLY, see _I Got Rhythm_, _Like Someone in Love_, _On the Sunny Side of the Street_, _Misty_)
+- `XyQ` - blank space for row alignment
+- `x` - repeat previous bar (see _Butterfly_)
+- `Kcl` or `XyQKcl` - also repeat previous bar (see _Besame Mucho_, _Butterfly_, _Solar_)
+- `r` - repeat previous 2 bars (see _Mas Que Nada_)
+- `()` - alternative chord written in small (above actual chord)
+- `"` - represents a chord separator
+- `,` - equivalent to space, especially for whole notes in 44
+- `<stuff here>` - Comments and repeat directives (can start with `*yy` to denote a vertical offset of yy units, see _La Fiesta_)
+- `*A` - section A (could be `*B`, `*C`, `*i`, `*v`, etc.)
+- `S` - segno (see _Butterfly_)
+- `Q` - coda (see _Butterfly_)
+- `Y` - vertical spacer (see _Nearness of You_, _Night in Tunisia_)
+- `U` - end (see _Mas Que Nada_, _Scrapple from the Apple_, _Triste_, _Wave_)
+- `s` - small chord (e.g. `sC^7`)
+- `l` - large chord (e.g. `lC^7`)
+- `f` - fermata (see _Butterfly_, _Summer Serenade_)
 
 ## Time signatures
-
-- 24 (2/4)
-- 34 (3/4)
-- 44 (4/4)
-- 54 (5/4)
-- 64 (6/4)
-- 74 (7/4)
-- 38 (3/8)
-- 58 (5/8)
-- 68 (6/8)
-- 78 (7/8)
-- 98 (9/8)
-- 12 (12/8)
-- 22 (2/2)
-- 32 (3/2)
+- `24` (2/4)
+- `34` (3/4)
+- `44` (4/4)
+- `54` (5/4)
+- `64` (6/4)
+- `74` (7/4)
+- `38` (3/8)
+- `58` (5/8)
+- `68` (6/8)
+- `78` (7/8)
+- `98` (9/8)
+- `12` (12/8)
+- `22` (2/2)
+- `32` (3/2)
 
 ## Barlines
-
-- [ - start double barline
-- ] - end double barline
-- { - start repeat
-- } - end repeat
-- LZ - normal barline
-- | - also normal barline (see _Au Privave_, _Stormy Weather_)
-- Z - end double barline (that has a bolded second line)
+- `[` - start double barline
+- `]` - end double barline
+- `{` - start repeat
+- `}` - end repeat
+- `LZ` - normal barline
+- `|` - also normal barline (see _Au Privave_, _Stormy Weather_)
+- `Z` - end double barline (that has a bolded second line)
 
 ## Comments and repeat directives
 - D.C. al Coda
@@ -165,32 +161,85 @@
 - 7x
 - 8x
 
-## Chords
-### Roots
+## Chord roots
 Cb, C, C#, Db, D, D#, Eb, E, F, F#, Gb, G, G#, Ab, A, A#, Bb, B
 
-### Inversions (aka bass notes)
+## Chord inversions (aka bass notes)
 /Cb, /C, /C#, /Db, /D, /D#, /Eb, /E, /F, /F#, /Gb, /G, /G#, /Ab, /A, /A#, /Bb, /B
 
-### Qualities
-
-- ^7, -7, 7, 7sus
-- ^, -, 7alt, sus
-- 6, -6, o7, ø7
-- ^9, -9, 9, 9sus
-- ^13, -11, 13, 13sus
-- 6/9, -6/9, -^7, -^9
-- ^7#11, ^9#11, -b6, -#5
-- ^7#5, add9, -7b5, ø9
-- 2, 5, +, o, ø
-- 7b9, 7#9, 7b5, 7#5
-- 7b13, 7#11, 9#11, 13#11
-- 11, 7b9sus, 7b13sus, 7add3sus
-- 9b5, 9#5, 13b9, 13#9
-- 7b9b13, 7b9#5, 7b9b5, 7b9#9
-- 7#9#5, 7#9b5, 7#9#11, 7b9#11
-
-### Other possible chord values
-- W - invisible chord (typically used to add a bass note, see _Butterfly_ ppsW/C)
-- n - N.C. (see _Butterfly_)
-- p - slash (repeat previous chord)
+## Chord qualities indicators
+- `^` - major
+- `-` - minor
+- `o` - diminished
+- `ø` - hald-diminished
+- `+` - augmented
+- `b` - flat
+- `#` - sharp
+
+## Chord qualities full list
+- `^7`
+- `-7`
+- `7`
+- `7sus`
+- `^`
+- `-`
+- `7alt`
+- `sus`
+- `6`
+- `-6`
+- `o7`
+- `ø7`
+- `^9`
+- `-9`
+- `-9`
+- `9sus`
+- `^13`
+- `-11`
+- `13`
+- `13sus`
+- `6/9`
+- `-6/9`
+- `-^7`
+- `-^9`
+- `^7#11`
+- `^9#11`
+- `-b6`
+- `-#5`
+- `^7#5`
+- `add9`
+- `-7b5`
+- `ø9`
+- `2`
+- `5`
+- `+`
+- `o`
+- `ø`
+- `7b9`
+- `7#9`
+- `7b5`
+- `7#5`
+- `7b13`
+- `7#11`
+- `9#11`
+- `13#11`
+- `11`
+- `7b9sus`
+- `7b13sus`
+- `7add3sus`
+- `9b5`
+- `9#5`
+- `13b9`
+- `13#9`
+- `7b9b13`
+- `7b9#5`
+- `7b9b5`
+- `7b9#9`
+- `7#9#5`
+- `7#9b5`
+- `7#9#11`
+- `7b9#11`
+
+## Other chord values
+- `W` - invisible chord (typically used to add a bass note, see _Butterfly_)
+- `n` - N.C. (see _Butterfly_)
+- `p` - slash (repeat previous chord)