Reorganize docs sections and split cheatsheet in two (#333)

* Initial split of music ops out of maths, and setup out of hardware

* Fix docs build

* Move things around a bit more

* remove unimplemented see_also props

* Compress TXo short descriptions, reorder i2c sections

* Tweak hardware section a bit more

* Update CHANGELOG and whats_new

* Fix calibration section heading level

* make clean in docs should be more effective

* tweak IJK short blurbs

* Keep original name for core cheatsheet

.gitignore

@@ -53,5 +53,5 @@ __pycache__/
 /docs/teletype.pdf
 /docs/teletype.html
 /docs/cheatsheet/*
-!/docs/cheatsheet/cheatsheet.tex
+!/docs/cheatsheet/cs-common.tex
 /docs/testServe/

CHANGELOG.md

@@ -35,6 +35,7 @@
 - **NEW**: apply VCV Rack compatibility patches, so branches off main can be used in both hardware and software
 - **FIX**: update Disting EX looper ops to work with Disting EX firmware 1.23+
 - **NEW**: new dual W/ ops: `W/.SEL`, `W/S.POLY`, `W/S.POLY.RESET`, `W/1`, `W/2`
+- **NEW**: split cheatsheets into separate PDFs for core ops and i2c
 
 ## v4.0.0
 

docs/Makefile

@@ -1,11 +1,11 @@
 .PHONY: build clean
 
-build: teletype.pdf teletype.html cheatsheet/cheatsheet.pdf
+build: teletype.pdf teletype.html cheatsheet/cheatsheet.pdf cheatsheet/cheatsheet-i2c.pdf
 
 clean:
 	rm -f teletype.pdf && \
 		rm -f teletype.html && \
-		rm -f cheatsheet/include.tex && \
+		rm -f cheatsheet/cheatsheet-*.* && \
 		cd cheatsheet && \
 			latexmk -xelatex -c && \
 			rm -f cheatsheet.pdf
@@ -18,8 +18,11 @@ teletype.html: $(wildcard *.md ops/*.md ops/*.toml) \
 		../utils/docs.py ../CHANGELOG.md $(wildcard ../utils/templates/*)
 	../utils/docs.py teletype.html
 
-cheatsheet/include.tex: $(wildcard ops/*.toml) ../utils/cheatsheet.py
-	../utils/cheatsheet.py "cheatsheet/include.tex"
+cheatsheet/cheatsheet-%.tex: $(wildcard ops/*.toml) ../utils/cheatsheet.py
+	../utils/cheatsheet.py $* "cheatsheet/cheatsheet-$*.tex"
 
-cheatsheet/cheatsheet.pdf: cheatsheet/cheatsheet.tex cheatsheet/include.tex
-	cd cheatsheet && latexmk -xelatex cheatsheet.tex
+cheatsheet/cheatsheet-%.pdf: cheatsheet/cs-common.tex cheatsheet/cheatsheet-%.tex
+	cd cheatsheet && latexmk -xelatex cs-common.tex -jobname=cheatsheet-$*
+
+cheatsheet/cheatsheet.pdf: cheatsheet/cheatsheet-core.pdf
+	cd cheatsheet && cp cheatsheet-core.pdf cheatsheet.pdf

docs/cheatsheet/cheatsheet.tex → docs/cheatsheet/cs-common.tex

@@ -59,7 +59,7 @@
 \begin{document}
 
 \begin{multicols}{5}
-  \input{include.tex}
+  \input{\jobname.tex}
 
   %% add a page break at the end to force the last column to not balance
   \pagebreak

docs/ops/calibration.md

@@ -0,0 +1 @@
+## Calibration

docs/ops/calibration.toml

@@ -0,0 +1,93 @@
+
+["DEVICE.FLIP"]
+prototype = "DEVICE.FLIP"
+short = "Flip the screen/inputs/outputs"
+description = """
+Flip the screen, the inputs and the outputs. This op is useful if you want to mount your Teletype upside down.
+The new state will be saved to flash. 
+"""
+
+["IN.CAL.MIN"]
+prototype = "IN.CAL.MIN"
+short = "Reads the input CV and assigns the voltage to the zero point"
+description = """
+    1. Connect a patch cable from a calibrated voltage source
+    2. Set the voltage source to 0 volts
+    3. Execute IN.CAL.MIN from the live terminal
+    4. Call IN and confirm the 0 result
+"""
+
+["IN.CAL.MAX"]
+prototype = "IN.CAL.MAX"
+short = "Reads the input CV and assigns the voltage to the max point"
+description = """
+    5. Set the voltage source to target maximum voltage (10V)
+    6. Execute IN.CAL.MAX from the live terminal
+    7. Call IN and confirm that the result is 16383
+"""
+
+["IN.CAL.RESET"]
+prototype = "IN.CAL.RESET"
+short = "Resets the input CV calibration"
+
+["PARAM.CAL.MIN"]
+prototype = "PARAM.CAL.MIN"
+short = "Reads the Parameter Knob minimum position and assigns a zero value"
+description = """
+    1. Turn the PARAM knob all the way to the left
+    2. Execute PARAM.CAL.MIN from the live terminal
+    3. Call PARAM and confirm the 0 result
+"""
+
+["PARAM.CAL.MAX"]
+prototype = "PARAM.CAL.MAX"
+short = "Reads the Parameter Knob maximum position and assigns the maximum point"
+description = """
+    4. Turn the knob all the way to the right
+    5. Execute PARAM.CAL.MAX from the live terminal
+    6. Call PARAM and verify that the result is 16383
+"""
+
+["PARAM.CAL.RESET"]
+prototype = "PARAM.CAL.RESET"
+short = "Resets the Parameter Knob calibration"
+
+["CV.CAL"]
+prototype = "CV.CAL n mv1v mv3v"
+short = "Calibrate CV output `n`"
+description = """
+Following a short calibration procedure, you can use `CV.CAL` to more
+precisely match your CV outputs to each other or to an external reference. A
+digital multimeter (or other voltage measuring device) is required.
+
+To calibrate CV 1, first set it to output one volt with `CV 1 V 1`. Using
+a digital multimeter with at least millivolt precision (three digits after
+the decimal point), record the measured output of CV 1 between tip and sleeve
+on a patch cable. Then set CV 1 to three volts with `CV 1 V 3` and measure
+again.
+
+Once you have both measurements, use the observed 1V and 3V values in
+millivolts as the second and third arguments to `CV.CAL`. For example, if you
+measured 0.990V and 2.984V, enter `CV.CAL 1 990 2984`. (If both your
+measurements are within 1 or 2 millivolts already, there's no need to run
+`CV.CAL`.)
+
+Measure the output with `CV 1 V 1` and `CV 1 V 3` again and confirm the values
+are closer to the expected 1.000V and 3.000V.
+
+Repeat the above steps for CV 2-4, if desired. The calibration data is stored
+in flash memory so you only need to go through this process once.
+
+Note: The calibration adjustment is made after `CV.SLEW` and `CV.OFF` are
+applied, and does not affect `CV.GET` or any other scene-visible values. It
+only affects the levels coming out of the DAC.
+"""
+
+["CV.CAL.RESET"]
+prototype = "CV.CAL.RESET n"
+short = "Reset calibration data for CV output `n`"
+description = """
+Clear the calibration data for CV output `n` and return it to its default
+behavior, with no calibration adjustment.
+"""
+

docs/ops/controlflow.toml

@@ -398,7 +398,7 @@ Does not affect the CV input (IN) or the Parameter knob (PARAM) values.
 
 ["INIT.P"]
 prototype = "INIT.P x"
-short = "clears pattern associated with pattern number x"
+short = "clears pattern number x"
 
 ["INIT.P.ALL"]
 prototype = "INIT.P.ALL"
@@ -422,7 +422,7 @@ short = "clear time on trigger x"
 
 ["INIT.TR"]
 prototype = "INIT.TR x"
-short = "clear all parameters on trigger associated with TR x"
+short = "clear all parameters on trigger x"
 
 ["INIT.TR.ALL"]
 prototype = "INIT.TR.ALL"

docs/ops/hardware.toml

@@ -18,8 +18,8 @@ output `x` to `y`.
 """
 
 ["CV.SET"]
-prototype = "CV.SET x"
-short = "Set CV value"
+prototype = "CV.SET x y"
+short = "Set CV value, ignoring slew"
 description = """
 Set the CV value at output `x` bypassing any slew settings.
 """
@@ -40,44 +40,13 @@ Get the slew time in ms associated with CV output `x`. Set the slew time
 associated with CV output `x` to `y` ms.
 """
 
-["CV.CAL"]
-prototype = "CV.CAL n mv1v mv3v"
-short = "Calibrate CV output `n`"
-description = """
-Following a short calibration procedure, you can use `CV.CAL` to more
-precisely match your CV outputs to each other or to an external reference. A
-digital multimeter (or other voltage measuring device) is required.
-
-To calibrate CV 1, first set it to output one volt with `CV 1 V 1`. Using
-a digital multimeter with at least millivolt precision (three digits after
-the decimal point), record the measured output of CV 1 between tip and sleeve
-on a patch cable. Then set CV 1 to three volts with `CV 1 V 3` and measure
-again.
-
-Once you have both measurements, use the observed 1V and 3V values in
-millivolts as the second and third arguments to `CV.CAL`. For example, if you
-measured 0.990V and 2.984V, enter `CV.CAL 1 990 2984`. (If both your
-measurements are within 1 or 2 millivolts already, there's no need to run
-`CV.CAL`.)
-
-Measure the output with `CV 1 V 1` and `CV 1 V 3` again and confirm the values
-are closer to the expected 1.000V and 3.000V.
+[V]
+prototype = "V x"
+short = "converts a voltage to a value usable by the CV outputs (`x` between `0` and `10`)"
 
-Repeat the above steps for CV 2-4, if desired. The calibration data is stored
-in flash memory so you only need to go through this process once.
-
-Note: The calibration adjustment is made after `CV.SLEW` and `CV.OFF` are
-applied, and does not affect `CV.GET` or any other scene-visible values. It
-only affects the levels coming out of the DAC.
-"""
-
-["CV.CAL.RESET"]
-prototype = "CV.CAL.RESET n"
-short = "Reset calibration data for CV output `n`"
-description = """
-Clear the calibration data for CV output `n` and return it to its default
-behavior, with no calibration adjustment.
-"""
+[VV]
+prototype = "VV x"
+short = "converts a voltage to a value usable by the CV outputs (`x` between `0` and `1000`, `100` represents 1V)"
 
 ["IN"]
 prototype = "IN"
@@ -102,51 +71,6 @@ Get the value of the PARAM knob. This returns a valuue in the range 0-16383.
 prototype = "PARAM.SCALE min max"
 short = "Set static scaling of the PARAM knob to between `min` and `max`."
 
-["IN.CAL.MIN"]
-prototype = "IN.CAL.MIN"
-short = "Reads the input CV and assigns the voltage to the zero point"
-description = """
-    1. Connect a patch cable from a calibrated voltage source
-    2. Set the voltage source to 0 volts
-    3. Execute IN.CAL.MIN from the live terminal
-    4. Call IN and confirm the 0 result
-"""
-
-["IN.CAL.MAX"]
-prototype = "IN.CAL.MAX"
-short = "Reads the input CV and assigns the voltage to the max point"
-description = """
-    5. Set the voltage source to target maximum voltage (10V)
-    6. Execute IN.CAL.MAX from the live terminal
-    7. Call IN and confirm that the result is 16383
-"""
-
-["IN.CAL.RESET"]
-prototype = "IN.CAL.RESET"
-short = "Resets the input CV calibration"
-
-["PARAM.CAL.MIN"]
-prototype = "PARAM.CAL.MIN"
-short = "Reads the Parameter Knob minimum position and assigns a zero value"
-description = """
-    1. Turn the PARAM knob all the way to the left
-    2. Execute PARAM.CAL.MIN from the live terminal
-    3. Call PARAM and confirm the 0 result
-"""
-
-["PARAM.CAL.MAX"]
-prototype = "PARAM.CAL.MAX"
-short = "Reads the Parameter Knob maximum position and assigns the maximum point"
-description = """
-    4. Turn the knob all the way to the right
-    5. Execute PARAM.CAL.MAX from the live terminal
-    6. Call PARAM and verify that the result is 16383
-"""
-
-["PARAM.CAL.RESET"]
-prototype = "PARAM.CAL.RESET"
-short = "Resets the Parameter Knob calibration"
-
 ["TR"]
 prototype = "TR x"
 prototype_set = "TR x y"
@@ -156,14 +80,12 @@ Get the current state of trigger output `x`. Set the state of trigger
 output `x` to `y` (0-1).
 """
 
-["TR.POL"]
-prototype = "TR.POL x"
-prototype_set = "TR.POL x y"
-short = "Set polarity of trigger output x to y (0-1)"
+["TR.PULSE"]
+prototype = "TR.PULSE x"
+aliases = ["TR.P"]
+short = "Pulse trigger output x"
 description = """
-Get the current polarity of trigger output `x`. Set the polarity of trigger 
-output `x` to `y` (0-1). When TR.POL = 1, the pulse is 0 to 1 then back to 0.
-When TR.POL = 0, the inverse is true, 1 to 0 to 1.
+Pulse trigger output x.
 """
 
 ["TR.TIME"]
@@ -182,12 +104,14 @@ description = """
 Flip the state of trigger output `x`.
 """
 
-["TR.PULSE"]
-prototype = "TR.PULSE x"
-aliases = ["TR.P"]
-short = "Pulse trigger output x"
+["TR.POL"]
+prototype = "TR.POL x"
+prototype_set = "TR.POL x y"
+short = "Set polarity of trigger output x to y (0-1)"
 description = """
-Pulse trigger output x.
+Get the current polarity of trigger output `x`. Set the polarity of trigger 
+output `x` to `y` (0-1). When TR.POL = 1, the pulse is 0 to 1 then back to 0.
+When TR.POL = 0, the inverse is true, 1 to 0 to 1.
 """
 
 ["MUTE"]
@@ -205,14 +129,6 @@ description = """
 Read the current state of trigger input `x` (0=low, 1=high). 
 """
 
-["DEVICE.FLIP"]
-prototype = "DEVICE.FLIP"
-short = "Flip the screen/inputs/outputs"
-description = """
-Flip the screen, the inputs and the outputs. This op is useful if you want to mount your Teletype upside down.
-The new state will be saved to flash. 
-"""
-
 ["LIVE.OFF"]
 prototype = "LIVE.OFF"
 aliases = ["LIVE.O"]

docs/ops/i2c2midi.toml

@@ -418,15 +418,15 @@ Set strumming of chord `x` (0..8) to `x` ms (0..32767). Strumming plays the note
 
 ["I2M.C.VCUR"]  
 prototype = "I2M.C.VCUR w x y z"  
-alias = ["I2M.C.V~"]
+aliases = ["I2M.C.V~"]
 short = "Set velocity curve for chord `w` (0..8) with curve type `x` (0..5), start value `y`% (0..32767) and end value `z`% (0..32767), use `w = 0` to set for all chords, use `x = 0` to turn off"   
 description = """
 Set velocity curve for chord `w` (0..8) with curve type `x` (0..5), start value `y`% (0..32767) and end value `z`% (0..32767). This will affect the velocity of the notes in the order they are defined in the chord. Start and end percentages refer to the velocity with which the chord is played via `I2M.C`. Use `x = 0` to turn velocity curve off. The following curves are available: 0) Off 1) Linear 2) Exponential 3) Triangle 4) Square 5) Random. Use `w = 0` to set velocity curve for all chords. Try a random curve with subtle values for a humanizing effect.
 """
 
 ["I2M.C.TCUR"]  
 prototype = "I2M.C.TCUR w x y z"  
-alias = ["I2M.C.T~"]
+aliases = ["I2M.C.T~"]
 short = "Set time curve to strumming for chord `w` (0..8) with curve type `x` (0..5), start value `y`% (0..32767) and end value `z`% (0..32767), use `w = 0` to set for all chords, use `x = 0` to turn off"   
 description = """
 Set time curve for chord `w` (0..8) with curve type `x` (0..5), start value `y`% (0..32767) and end value `z`% (0..32767). This will affect the time interval between the notes in the order they are defined in the chord. Start and end percentages refer to the current strumming setting of the chord, set via `I2M.C.STR`. Use `x = 0` to turn time curve off. The following curves are available: 0) Off 1) Linear 2) Exponential 3) Triangle 4) Square 5) Random. Use `w = 0` to set time curve for all chords. Try a square curve with similar values to create swing. Try a random curve with subtle values for a humanizing effect.