Teletype 2.0 documentation

(I’m starting this thread as an offshoot from the main Teletype 2.0 beta thread.)


Intro

This thread is for anyone that would like to contribute towards filling in the new Teletype documentation. This differs from the existing documentation by being stored alongside the source code on GitHub, in the hopes that it will be easier to keep up to date.

Ultimately the documentation is what we make it.

Technical bits

We can generate documentation in the following formats, PDF, HTML and Markdown. (It’s possible that the Markdown file will work on the current Jekyll based documentation site as is…)

The documentation is broken down into 2 parts:

  • some Markdown files that are used for freeform content (currently this consists of the key bindings). Can also be used for tutorials if someone wishes to write one, and maybe an updated ‘Teletype studies’ series of posts.
  • a Markdown file and a TOML file per group of OPs (e.g. variables.md and variables.toml).
    • the Markdown file is for the introduction to the section (e.g. the section on variables could be used to describe the difference between retrieving a value and setting it).
    • the TOML is used as a database, it contains the name of the OP, a short description of how to use it, and an optional longer description.

Why TOML? Well, I wanted a database like format for the OP documentation for a few reasons

  • it let’s us print out which OPs are missing an entry
  • we can have a topical listing of OPs and an alphabetical list
  • (in the future) we can create a very compact printable cheatsheet to keep near your Teletype
  • (maybe…) we can covert to text and include it in the Teletype firmware

The downside is that the documentation is autogenerated from this database, and thus micromanaging the formatting is very tricky. Furthermore for the time being I’m trying to avoid getting bogged down in formatting discussions, instead I’m trying to get the organisation and the content up to speed first. (However… if you happen to be a Latex/Pandoc witch or a CSS wizard then please get in touch!)

Show me the bits

This is where the files are at the moment.

Want to contribute?

As it says in the title, all technical abilities are welcome.

Rather than try to write out instructions for every ability, I was wondering if those interested in helping could reply below. Pertinent info would be, what OS you’re on, can you code at all, and do you know how to use git / GitHub. So long as you can use TextEdit.app or Notepad.exe you can help.

For those of you that would like to learn how to use git / GitHub, I can try to offer as much assistance as I can. As a bonus, you’ll show up on the list on contributors.

Guide: “I can generate the documents locally and want to make a TOML file”

If you’re able to build either the HTML and PDF documentation locally, the best way to contribute is by creating a pair of files in the ops directory.

The names of the 2 files should be:

  • <section>.md
  • <section>.toml

(where <section> is the name of the section you’re creating)

The Markdown file is the introductory text, for now just place a header in it (see variables.md), the TOML file contains structured format like so:

[D]
prototype = "D"
prototype_set = "D x"
short = "get / set the variable `D`, default `4`"

[D]
prototype = "D"
prototype_set = "D x"
short = "get / set the variable `D`, default `4`"

[DRUNK]
prototype = "DRUNK"
prototype_set = "DRUNK x"
short = """changes by `-1`, `0`, or `1` upon each read saving its state,
setting will give it a new value for the next read"""
description="""
Changes by `-1`, `0`, or `1` upon each read, saving its state. Setting `DRUNK`
will give it a new value for the next read, and drunkedness will continue on
from there with subsequent reads.
Setting `DRUNK.MIN` and `DRUNK.MAX` controls the lower and upper bounds
(inclusive) that `DRUNK` can reach. `DRUNK.WRAP` controls whether the value can
wrap around when it reaches it's bounds.
"""

["DRUNK.MIN"]
prototype = "DRUNK.MIN"
prototype_set = "DRUNK.MIN x"
short = "set the lower bound for `DRUNK`, default `0`"

(excerpt from variables.toml)

Each entry starts with the name of the OP in square brackets. Important: if the OP name contains a . in it, then enclose the name in double quotes (see DRUNK.MIN).

Then you set four variables:

  • prototype (required), the name of the OP and the parameters it requires. e.g. for the Euclidean rhythms OP which takes 3 parameters, fill, length and index, I might use ER f l i as the prototype. Capitalise the OP and use lower case letters for the parameters.

  • prototype_set (optional), as prototype but used for OPs that can be ‘set’ too. (Only use prototype_set for OPs that have both set and get, otherwise just use prototype. Boring technical reason is that the ‘set’ here doesn’t refer to what you’re doing, but how the OP works internally.)

  • short (required), a short one line description of the OP and if needed the parameters.

  • description (optional) a longer, more in depth discussion of the OP (only if needed).

  • aliases (optional) an array of the aliases of that OP.

In a TOML file, single lines of text are enclosed in double quotes, but multi-line text is enclosed in triple double quotes. For more info see the TOML website.

Status

OPs

OPs have been broken down into the following sections (this is based on how it is broken down in code)

If you wish to claim a section to do, let me know and I will give you the list of OPs that it contains.

4 Likes

I’d like to help with this. I’m on OSX, can code in Python & C, and have a basic understanding of git.

Edited to add, I’ll volunteer for the WW section as a starting point.

1 Like

Excellent!

If you can fork and clone my Teletype repo, then checkout the docs branch (git checkout docs ).

There is a section on the documentation in the README on the docs branch.

If you’re able to try and follow along and see if you can build a pdf that would be the place to start. I find it hard when I’m in the thick of it to always write the best instructions, so please let me know of any issues that you have.

If you don’t want to install MacTex, you could just do the HTML version instead.

On it. Need to sort out a python3.6 env first. I’ll probably stick to the HTML version to start with.

1 Like

A little fun and games getting the dependencies sorted in a new Python3.6 Anaconda env, but I’ve just built the HTML version. Next step, read up on TOML.

1 Like
[D]
prototype = "D"
prototype_set = "D x"
short = "get / set the variable `D`, default `4`"

[DRUNK]
prototype = "DRUNK"
prototype_set = "DRUNK x"
short = """changes by `-1`, `0`, or `1` upon each read saving its state,
setting will give it a new value for the next read"""
description="""
Changes by `-1`, `0`, or `1` upon each read, saving its state. Setting `DRUNK`
will give it a new value for the next read, and drunkedness will continue on
from there with subsequent reads.
Setting `DRUNK.MIN` and `DRUNK.MAX` controls the lower and upper bounds
(inclusive) that `DRUNK` can reach. `DRUNK.WRAP` controls whether the value can
wrap around when it reaches it's bounds.
"""

["DRUNK.MIN"]
prototype = "DRUNK.MIN"
prototype_set = "DRUNK.MIN x"
short = "set the lower bound for `DRUNK`, default `0`"

The one gotcha I’ll warn you about, if the ops name (a.ka. a key in a TOML dictionary) has a . you need to quote it, otherwise you get a nested dictionary, see DRUNK.MIN above.

Also. Python 3.6 is pretty great, it’s the first version I’d definitely choose over 2.7 if I can. Formatting strings are lovely and pathlib is so much nicer to use than os.path

@GoneCaving here is your list of White Whale ops…

  • WW.PRESET
  • WW.POS
  • WW.SYNC
  • WW.START
  • WW.END
  • WW.PMODE
  • WW.PATTERN
  • WW.QPATTERN
  • WW.MUTE1
  • WW.MUTE2
  • WW.MUTE3
  • WW.MUTE4
  • WW.MUTEA
  • WW.MUTEB

(I’m trying to fight the urge to merge the mute ops into one…)

Count me in for the telex expanders!

1 Like

I’d also like to help! I’m on OSX, light html and javascript experience. new-ish to github beyond using it to download module firmwares

As a start, I’d volunteer to grab the meadowphysics section

Do you want to try generating the documentation locally? And then fill in a TOML file yourself. Or I can get you to supply a simplified version of the data as plain text that I will be able to easily convert to the TOML file.

Awesome!

Quick question for the github ninjas. I’ve already got a fork of the teletype repo which seems to preclude me forking @sam’s. Any thoughts on process (short of deleting my pre-existing repo)?

Cool, I’m at work, but in my moments of free time I’ll try and get all the dependencies installed and give this a shot.

Out of curiosity would this be easier in github? I have no problem trying to get that working as well

cd teletype
git remote add samdoshi https://github.com/samdoshi/teletype.git  # or use SSH URL
git fetch samdoshi
git checkout ....
1 Like

Don’t quite understand… GitHub and git the command tool are related but not the same thing.

Meadowphysics ops:

  • MP.PRESET
  • MP.RESET
  • MP.SYNC
  • MP.MUTE
  • MP.UNMUTE
  • MP.FREEZE
  • MP.UNFREEZE
  • MP.STOP

i’ll do the orca section :slight_smile:

1 Like

Docs are great! One snag I hit was a missing xelatex link:

RuntimeError: Pandoc died with exitcode "41" during conversion: b'pandoc: xelatex not found. xelatex is needed for pdf output.\n'

Adding this to my .bashrc:

export PATH=/Library/TeX/texbin:$PATH

did the trick.

:beers:


EDIT: removed reference to superfluous tex download; I think linking is all that was needed.

I have no idea about that download. I’ve always used MacTex and the official TexLive.

It’s more than probably that you’ll need more than just xelatex, there’s a ton of other TeX scripts included in TexLive/MacTex.

Any chance you can retry with MacTex?

If MacTex installs /Library/TeX/texbin then we’re good to go and all (some) folks may need is to update their $PATH. I’ll redact above. Thanks!

As for testing w/o an extra install, I don’t know how to reliably undo it so it’s probably best to see if anyone else hit’s a snag with a vanilla install and go from there.

MacTex usually installs a file to /etc/paths.d/TeX which is read by /usr/libexec/path_helper, and for most OSX users that works fine. It depends on what you’ve done to your .bashrc (or ZSH equivalents).