commit 4f9507e1fb888b47415a20bb35e6ae2143e43bd0
Author: spesk <spesk@pm.me>
Date: Mon Mar 21 14:57:09 2022 -0400
Updated README
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..756b22f
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+*.svg
diff --git a/README.md b/README.md
index bd5a9a0..1fdb91b 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,140 @@
-# modmark
-Modular synth patch markup lang
\ No newline at end of file
+# Table of Contents
+
+1. [Modmark](#org0b1d179)
+ 1. [Current Status and Goals](#orgd73848c)
+ 2. [Purpose](#orgb91e197)
+ 3. [Syntax](#org899a6d3)
+ 1. [A Module File](#org1c23079)
+ 2. [A Patch](#orgd896ed4)
+
+
+<a id="org0b1d179"></a>
+
+# Modmark
+
+This repo encapsulates an attempt to develop a markup language for describing modular synth patches.
+
+In future, this scope may be expanded to make available a language for describing arbitrary audio and
+data routing across a wide array of devices.
+
+
+<a id="orgd73848c"></a>
+
+## Current Status and Goals
+
+This software is currently a prototype. Right now the "compiler" is a Perl script that translates a
+`.modmark` file into a flowchart via Graphviz.
+
+A rough road map looks something like:
+
+- [X] Prototype compiler in Perl
+- [ ] Test and stabilize syntax/grammar
+- [ ] Implement modmark as a source-to-source compiler in Racket ( "Real" implementation )
+- [ ] Develop libraries for as many modules as possible
+
+
+<a id="orgb91e197"></a>
+
+## Purpose
+
+In the past I've found it difficult to discuss discrete details of modular patches on the internet. This
+arises, I believe, from the large amount of effort and time it takes to describe the intricacies of a modular
+patch in long form plain English. This prototype language is an attempt to address that problem.
+
+By specifying a concise syntax that favors brevity over absolute human-readability, the hope is to get more
+modular synth users to document their patches and enable more knowledge sharing across the community.
+
+I know of one other attempt to solve this problem: <https://github.com/SpektroAudio/Patchbook>
+
+My problem with Patchbook is that it still requires a lot of "boilerplate", in that you have to specify
+modules yourself. Modmark aims to offload this task by having the community describe modules in a Library format
+(`.module` files) that can then be imported. In this way, we can specify a module *once* and then not have
+to do that work again the next time we'd like to use it in a patch.
+
+
+<a id="org899a6d3"></a>
+
+## Syntax
+
+
+<a id="org1c23079"></a>
+
+### A Module File
+
+ # A module spec
+ Manufacturer: MakeNoise
+ Module: Maths
+ Revision: null
+ - Input: Slew1
+ - Input: Slew2
+ - Input: Trig1
+ - Input: Trig2
+ - Input: Attenuveter1
+ -- Position: [1-12]
+ - Input: Attenuveter2
+ -- Position: [1-12]
+ - Input: Attenuveter3
+ -- Position: [1-12]
+ - Input: Attenuveter4
+ -- Position: [1-12]
+ - Input: Rise1
+ -- Position: [1-12]
+ - Input: Rise2
+ -- Position: [1-12]
+ - Input: Both1
+ - Input: Both2
+ - Input: Fall1
+ -- Position: [1-12]
+ - Input: Fall2
+ -- Position: [1-12]
+ - Input: Cycle1
+ - Input: Cycle2
+ - Knob: LogExp
+ -- Position: [1-12]
+ - Button: Cycle1
+ - Button: Cycle2
+ - Output: 1f
+ - Output: 1
+ - Output: 2
+ - Output: 3
+ - Output: 4
+ - Output: 4f
+ - Output: Or
+ - Output: Sum
+ - Output: Inv
+ -- Position: [1-3]
+
+
+<a id="orgd896ed4"></a>
+
+### A Patch
+
+See the below example of a "Hello World" type patch:
+
+ # A comment
+
+ # The title of the patch
+ Title: Foo
+
+ # The directory to look for module files
+ ModuleDir "/home/swatson/Repos/modmark/"
+
+ # Modules to use in this patch
+ import Module::Foobar::FooMod
+ import Module::MakeNoise::Maths
+
+ # Sets. These are used to indicate setting
+ # particular module attriubtes in accordance with
+ # the module definition
+ set Maths.Cycle1 = on
+ set Maths.Rise1.position = 7
+ set Maths.Fall1.position = 1
+ set Maths.LogExp.position = 5
+
+ # Connects. These are used to indicate data flow.
+ # Connects are always defined left to right. The
+ # below line connects the Function1 output of Maths
+ # to a FooInput on FooModule, as imported above
+ connect Maths.1f FooMod.FooInput
+
diff --git a/README.org b/README.org
new file mode 100644
index 0000000..02a65d4
--- /dev/null
+++ b/README.org
@@ -0,0 +1,113 @@
+
+* Modmark
+
+ This repo encapsulates an attempt to develop a markup language for describing modular synth patches.
+
+ In future, this scope may be expanded to make available a language for describing arbitrary audio and
+ data routing across a wide array of devices.
+
+** Current Status and Goals
+
+ This software is currently a prototype. Right now the "compiler" is a Perl script that translates a
+ =.modmark= file into a flowchart via Graphviz.
+
+ A rough road map looks something like:
+ - [X] Prototype compiler in Perl
+ - [ ] Test and stabilize syntax/grammar
+ - [ ] Implement modmark as a source-to-source compiler in Racket ( "Real" implementation )
+ - [ ] Develop libraries for as many modules as possible
+
+** Purpose
+
+ In the past I've found it difficult to discuss discrete details of modular patches on the internet. This
+ arises, I believe, from the large amount of effort and time it takes to describe the intricacies of a modular
+ patch in long form plain English. This prototype language is an attempt to address that problem.
+
+ By specifying a concise syntax that favors brevity over absolute human-readability, the hope is to get more
+ modular synth users to document their patches and enable more knowledge sharing across the community.
+
+ I know of one other attempt to solve this problem: https://github.com/SpektroAudio/Patchbook
+
+ My problem with Patchbook is that it still requires a lot of "boilerplate", in that you have to specify
+ modules yourself. Modmark aims to offload this task by having the community describe modules in a Library format
+ (=.module= files) that can then be imported. In this way, we can specify a module /once/ and then not have
+ to do that work again the next time we'd like to use it in a patch.
+
+** Syntax
+*** A Module File
+ #+BEGIN_SRC
+# A module spec
+Manufacturer: MakeNoise
+Module: Maths
+Revision: null
+- Input: Slew1
+- Input: Slew2
+- Input: Trig1
+- Input: Trig2
+- Input: Attenuveter1
+-- Position: [1-12]
+- Input: Attenuveter2
+-- Position: [1-12]
+- Input: Attenuveter3
+-- Position: [1-12]
+- Input: Attenuveter4
+-- Position: [1-12]
+- Input: Rise1
+-- Position: [1-12]
+- Input: Rise2
+-- Position: [1-12]
+- Input: Both1
+- Input: Both2
+- Input: Fall1
+-- Position: [1-12]
+- Input: Fall2
+-- Position: [1-12]
+- Input: Cycle1
+- Input: Cycle2
+- Knob: LogExp
+-- Position: [1-12]
+- Button: Cycle1
+- Button: Cycle2
+- Output: 1f
+- Output: 1
+- Output: 2
+- Output: 3
+- Output: 4
+- Output: 4f
+- Output: Or
+- Output: Sum
+- Output: Inv
+-- Position: [1-3]
+ #+END_SRC
+
+*** A Patch
+ See the below example of a "Hello World" type patch:
+ #+BEGIN_SRC
+# A comment
+
+# The title of the patch
+Title: Foo
+
+# The directory to look for module files
+ModuleDir "/home/swatson/Repos/modmark/"
+
+# Modules to use in this patch
+import Module::Foobar::FooMod
+import Module::MakeNoise::Maths
+
+# Sets. These are used to indicate setting
+# particular module attriubtes in accordance with
+# the module definition
+set Maths.Cycle1 = on
+set Maths.Rise1.position = 7
+set Maths.Fall1.position = 1
+set Maths.LogExp.position = 5
+
+# Connects. These are used to indicate data flow.
+# Connects are always defined left to right. The
+# below line connects the Function1 output of Maths
+# to a FooInput on FooModule, as imported above
+connect Maths.1f FooMod.FooInput
+ #+END_SRC
+
+# LocalWords: modmark
diff --git a/ideas.org b/ideas.org
deleted file mode 100644
index 0453893..0000000
--- a/ideas.org
+++ /dev/null
@@ -1,27 +0,0 @@
-
-Ideas for markup language that can describe modular patches.
-
-Ideally, output is a conceptual flow chart of patches. Additionally,
-patch construction can be done in an interactive shell, or via a patch file
-that provides intuituve shorthand for patch markup.
-
-Use cases:
-- random patch generation
-- patch "type checking"
-- brevity in expressing/sharing LARGE patches
- - the trade off being you have to learn the language
-
-Idea is to place burden of patch notation on module notation, as opposed
-to connection notation. It's inconvinent to specific the module, but this can be
-community sourced and then should be trivially easy to do patch notation. See
-below example.
-
-
-
-Syntax would look something like:
-
-[[file:~/Repos/modular-markup/example.modmark][Kick Drum Example]]
-
-#+BEGIN_SRC lisp
-
-#+END_SRC