# Table of Contents

1.  [Modmark](#org18831d8)
    1.  [Current Status and Goals](#org926a523)
    2.  [Purpose](#org0463441)
    3.  [Syntax](#org004fef7)
        1.  [A Module File](#orgb5658bc)
        2.  [A Patch](#orgf298aea)


<a id="org18831d8"></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="org926a523"></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/prototype compiler
    -   [ ] Bug with connections where similar connection names are not resolved properly,
        resulting in duplicate or merged connections
    -   [ ] Clean up module naming, should support `-` chars, possibly other chars
-   [ ] Implement modmark as a source-to-source compiler in Racket ( "Real" implementation )
    -   [ ] Implement `import as` semantics for brevity
    -   [ ] Implement `import Module::MakeNoise::*` semantics for brevity
    -   [ ] Implement importing specific module revisions, ie: `import Module::MakeNoise::Wogglebug::Rev1`
    -   [ ] Standardize input/knob labeling semantics:
        
            - Input: Foo
            -- Position: [1,12]
            
            - Knob: Foo
            -- Position: [1,12]
            
            # Currently both of above "compile", and work as expected, in the case where a
            # module parameter has both a knob and an input. It may be better to only have one way?
-   [ ] Develop libraries for as many modules as possible


<a id="org0463441"></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="org004fef7"></a>

## Syntax


<a id="orgb5658bc"></a>

### A Module File

[Make Noise Maths](./module_lib/maths.module)


<a id="orgf298aea"></a>

### A Patch

[Example Patch](./patches/example.modmark)