(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.
