#21

Interesting. My .bash_profile is a mess (for a variety of quotidian day-job reasons) so it’s possible that it’s just me. In which case, sorry for the noise!

1 Like
#22

I had the same issue, but had already installed xelatex before I saw your comment.

that being said, this got me working

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

@sam-
I downloaded your repository and got my dependencies installed & with the above extra line was able to generate a .html and .pdf !

I think I jumbled some thoughts together. In your initial post you said that helping out wouldn’t necessarily mean using git/github. I was clumsily saying that if it would be easier or helpful for me to be using git/github I’d give that a try. But to get going I downloaded

1 Like
#23

Sending a TOML file in is the biggest time saver.

If you want to do the whole git/GitHub thing I can help you out, and it’s definitely the biggest ‘transferable skill’ you’ll take away from this.

GitHub themselves have some great resources:

https://guides.github.com/activities/forking/

https://try.github.io/levels/1/challenges/1

I might put something to this effect on the README if lots of people have the same issue.

OSX users, if you have something as follows in your .bashrc / .zshenv it will do it for you in an “Apple approved” manor.

# set up OS provided path on OSX
if [[ -x "/usr/libexec/path_helper" ]]; then
    eval `/usr/libexec/path_helper -s`
fi
1 Like
#24

The downside is that the documentation is autogenerated from this database, and thus micromanaging the formatting is very tricky.

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.

I’m happy to take a look at this in a couple weeks…finishing up a web project (that actually does a lot of these things) ~next week and then I should have some more free time.

Based on what I’m seeing in your repo, if you/the community was interested in this, the TOML/md formatting you currently are using should work well without needing any sort of massaging*. There would probably need to be a phony make target to copy the TOML files to a data dir, and the md files to a content dir, but that would be easy enough.

EDIT: Also if anyone else wants to look at this, I’m totally happy to help, feel free to @ me or PM me here.

#25

Have added a: Guide: “I can generate the documents locally and want to make a TOML file” section to the top post, seeing as that’s the way most people are going.

#26

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!

#27

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

1 Like
#28

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!

Agreed.

1 Like
#29

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

2 Likes
#30

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

#31

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 :slight_smile:

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

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

1 Like
#32

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.

#33

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”).

#34

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

#35

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.

#36

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

#37

@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

#38

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

#39

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.

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.

1 Like
#40

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)

1 Like