Teletype 2.0 documentation

[sam]

A static site could easily be built using the TOML (datafiles) + markdown (content pages) with Hugo. For PDF, a print-specific media query and just have the browser print prompt save to PDF could be a flow that works.

Could do. I use Hugo for my personal website. It’s very nice.

The python tool I wrote does a bit more than transform TOML to other formats, it also compares it against the source code to see which ops are missing documentation.

It’s also capable of spitting out Markdown itself:

cd utils
./docs.py teletype.md

And there is a decent chance that it could be directly imported into the Monome docs Jekyll site. That would probably be the first place to try to integrate it, if you wanted to have a go? (But not until 2.0 is out please!)

For now I’m happy that formatting can’t be played with. For a few reasons… 1. it’s far more sensible to deal with formatting once all the content is in place, and 2. formatting gets ‘bike shedded’ terribly, I’d rather the energy went into writing the docs!

[jlmitch5]

Sounds good! Agreed that trying to hook into the Monome Jekyll site would make the most sense–been a while sense I used Jekyll but I think it would probably be mostly the same (provided there’s TOML support EDIT: rereading, it might just be as easy as importing the fully built markdown your python tool exports).

Also totally understand that formatting could expand. I’ll see where things are at once this other project gets wrapped up and come here to make sure any work that I might end up doing is what you/the community is looking for.

I downloaded and took a look at the HTML docs*, and personally, I think the styling is sufficient at it’s current point (the TOC could be in it’s own column to the left of the docs if the browser width supports it to make finding sections easier, but that’s a bit nitpicky and also fairly trivial)…serving the docs somewhere would be the more important benefit I’d think (so you don’t have to download the docs files/have users looking at outdated versions they downloaded/etc.).

[sam]

Sounds good! Agreed that trying to hook into the Monome Jekyll site would make the most sense–been a while sense I used Jekyll but I think it would probably be mostly the same (provided there’s TOML support).

It would probably be easier to make the Python script spit out the correct Markdown for Jekyll, then make Jekyll do anything with the TOML.

edit: zing!

serving the docs somewhere would be the more important benefit I’d think

Agreed.

[jlmitch5]

It would probably be easier to make the Python script spit out the correct Markdown for Jekyll, then make Jekyll do anything with the TOML.

Ha, you beat me to the EDIT I just made

[tehn]

i’m not terribly concerned about jekyll-izing. i can link to static content from the main site, if it looks good

[tambouri]

Had success w/ producing a .pdf and .html of an initial test of my TOML file at work this afternoon. So that was pretty cool

At home now testing out these commands to ensure I know what I’m talking about, I’m noticing that not all of the Meadowphysics commands are working on (i believe to be) a current firmware module.

MP.PRESET, MP.RESET, MP.STOP work as expected

MP.SYNC, MP.MUTE, MP.UNMUTE, MP.FREEZE, MP.UNFREEZE don’t give an error, but don’t appear to do anything to meadowphysics

Cross referencing some of the meadowphysics threads this appears to have been acknowledged previously

New: meadowphysics (two)

I can get MP.PRESET, MP.RESET and MP.STOP to work, but none of the others. I cannot FREEZE or MUTE. I’ve been a little out of the loop on this, just returning to the fray, so I don’t know what MP.SYNC is supposed to do… is it supposed to apply to all tracks?

Meadowphysics 2.1

I think the freeze and mute commands are ditched since the meadowphysics 2.x fw works in a very different way. There are no more straight forward mapping of rows -> triggers. A row can trigger any trigger now so it’s ambiguous what a mute would mute, the trigger with that number or all the triggers trigged by the row with the number.

I’m guessing these may still work on the MP v1 firmware, but is this something we should be including?

[sam]

Good spot. Looking through the Meadow Physics source code I can see (as you say) it only responds to MP.PRESET, MP.RESET and MP.STOP.

@tehn is it worth remove the unused MP.* ops from the Teletype source code then? They’ll be easy enough to add back in when/if the features return.

[sam]

I’ve pushed new bits out to the docs branch. Shout out if you need help getting those changes into your local clone.

Included is the completed(ish) maths section, and I’ve updated the PDF at the top.

There are clearly some issues with the tables (e.g. see SCALE), and the table is definitely hard to read without horizontal lines. I’ve got ideas as to how to sort that all out, but I’d like to get all the content in first.

Also the python script now tries to validate the TOML files a bit so that errors can be spotted quicker. (I kept miss typing “prototype”).

[GoneCaving]

Is there an example of how to document a command that is set-only?

[sam]

There is no such thing really. I might need to come up with a better name than set.

The get / set division applies to OPs that when used as the first thing in a command can set a value, e.g.

X
X 0
CV 1
CV 1 1

Anyway, in short just use the prototype field.

[tehn]

@tehn is it worth remove the unused MP.* ops from the Teletype source code then? They’ll be easy enough to add back in when/if the features return.

i’d suggest yes. MP v1 i do consider musically inferior due to its much more limited range of configuration.

[tambouri]

@GoneCaving are you referring to the WW.PRESET ?

I realized last night that the MP.PRESET doesn’t have the get capability either

@sam
Cutting the no longer used MP ops, my list got real short, I did a quick draft pre-TOML

MP.PRESET
set Meadowphysics preset x (indexed from 0)

MP.RESET
reset countdown for channel x (0 = all, 1-8 = individual channels)

MP.STOP
stop countdown for channel x (0 = all, 1-8 = individual channels)

looking at Math and Variables, I’m kind of assuming these don’t need further description or examples as they are pretty to the point?

if examples were helpful i could add something like this, but it seemed like this would gratuitous to break all of these out per OP

MP.PRESET 0 - recalls preset 0 from meadowphysics memory

MP.RESET 3 - resets channel 3

MP.STOP 0 - stops all channels

let me know and I can get this in the TOML formatting

[GoneCaving]

@GoneCaving are you referring to the WW.PRESET ?

I realized last night that the MP.PRESET doesn’t have the get capability either

Yes that’s an example, but most of the WW ops are similar (POS/START/END).

[sam]

if examples were helpful i could add something like this, but it seemed like this would gratuitous to break all of these out per OP

The short versions look fine, I wouldn’t bother with the longer descriptions myself.

One recommendation, surround variables and numbers with backticks to make them appear in the monospaced font.

e.g.

["MP.PRESET"]
prototype="MP.PRESET x"
short="set Meadowphysics preset `x` (indexed from `0`)"

Also you can use the meadowphysics.md file for any preamble, which might be an alternative in some cases to filling in descriptions.

Yes that’s an example, but most of the WW ops are similar (POS/START/END).

I’ve tried to update the description of prototype_set in the first post.

Basically only use prototype_set when you need 2 versions of how to use an OP (e.g. CV 1 and CV 1 0).

The “set” in prototype_set has more to do with the semantics of the Teletype language than it does with what you’re actually doing.

If anyone would like to know more I can go into the technicalities of it.

[tambouri]

sweet, i was just about to ask about the backtick!

@sam here’s my first go at these, I think the formatting matches (and it looked correct when I built the .html & .pdf), but please let me know if I’m missing anything important

meadowphysics.md (163 Bytes)
meadowphysics.toml (329 Bytes)

[sam]

Looks solid to me, arguably you don’t need to backticks on the number 2 in the meadowphysics.md file as it’s not “code”. But it’s neither here nor there.

Good thinking to mention Ansible!

Do you want to have a go at opening a PR? Or would you like me to add the files for you?

[tambouri]

Yea i think I’m up for it!

I just did the quick github “Hello World” tutorial. If I followed correctly, do I make a branch of the teletype-docs, add my files to the docs folder, commit the change, and then open a pull request?

Did i miss something big, or is there a better way to do all that?

[sam]

That’s it. Make sure it’s from your own fork though.

The workflow is:

Fork my repo on GitHub, then…

git clone <your fork>
git branch meadowphysics-docs
git checkout meadowphysics-docs

Make your changes

git add <changed files> # multiple times if necessary
git commit              # warning this will open VIM... :wq
git push -u origin

Go on the GitHub website and open a PR

If you’re using the desktop client, hopefully the command line steps should correspond to what you do in the GUI.

[tambouri]

I think I follow, and it seemed pretty straightforward to do all that inside the github webpage

I opened a pull request in my branch in my fork. Let me know if I need to do anything else!

[sam]

Ah, you’ve opened a pull request to yourself…

Can you try editing the PR, and changing the base fork to “samdoshi:docs”, that way you’ll open one up to me.

If not, I can grab the commit myself (and you’ll still show up as the author).