Teletype docs enhancements (docs and cheatsheet live)


#141

That’s the problem, I don’t know and can’t find it though I have stumbled across it before.


#142

ok, one search did it.

the short answer, it doesn’t really work. don’t expect it to until there’s a firmware update.


#143

Sorry for some absence here (it’s been a wild couple of work months), but I’ve been slowly trying to get some doc improvements into the quickstart/overview section. I found it kind of tricky to break the gist of the original doc up much differently so this is mostly insertions, revisions, tweaks and a lot of @jlmitch5 coaching me on using git through the command line.

Anyway, I think I’ve been working on this in my own head for a little too long, so I’d like to solicit any feedback or suggestions for further revisions. Thanks!

@sam i know you are probably swamped w/ parenthood, but I knew on the OPs docs you gave me some pointers regarding formatting, I tried to apply these here, but would appreciate a glance as I’m sure I’m still missing some best practices


#144

Awesome!

I think that somewhere, your diagrams went missing. If you add them back in, commit and push (no need to use force as you aren’t rewriting history), it should be good!


#145

Whooops, I’m thinking these are hopefully still on my work computer. Otherwise I have the illustrator files and I can spit them back out again!


#146

on my branch as well if you need them


#147

Guys I’m pretty new to all this, but I was looking at the diagrams and thought, “Ah new shortcuts I can try to commit to memory.” Problem is on the Github repository and the navigation.png I see that Alt+F1-8 certainly chooses the correct script, but when I try Alt+F9 I go to the Metro Script prompt and Alt+F10 takes me to Init Script. I’m on firmware 2.2 Alpha 8 if that makes a difference. BTW, as I said I’m new, I think they are Metro and Init due to the M at the prompt and the I at the prompt - I suppose you could tell me M is for Init and I for Metro. Please clarify.


#148

Looks like just a typo on the png…docs currently state the key bindings are F9 = metro, F10 = Init

Good catch!


#149

I think it looks okay, I’m afraid I haven’t had time to read them, the basic problem is that the baby keeps smiling when I play with him, which makes it really hard to do anything else.

The only issue that might come up is with how you’ve used the blockquote format (indent by 4 spaces), instead of backtick code blocks. I think it’s more a case of seeing how the HTML and PDF comes out rather than one being more correct than the other.

Are you able to generate the PDF locally? If not I can pull your changes and make one for you.


#150

ok, diagrams are back in my branch! thanks @jlmitch5

@unity2k i’ve updated the diagram, thanks for giving that a try. please shoutout w/ any more feedback.

@sam totally understandable with regards to a smiling child! i was previously able to generate .pdfs & .html files for the last set of docs. but am running into an error here. I can copy paste the error if it’d be any help, or i’d accept one if you had a minute to generate. I have no problem revising this w/ backtick code blocks though, I had just been using the formatting from the original doc.

thanks!


#151

It should only take a few minutes for me to pull your changes and make the PDF. Will do so as soon as I’m near my computer again

edit: Poop, I’m getting an error relating to the changes in Pandoc 2.0, will need to dig a little deeper.


#152

Right, one trivial issue with Pandoc 2.0 (need to use --pdf-engine=xelatex instead of --latex-engine=xelatex), but it’s also rejecting one of the changes that makes fonts smaller in the tables. It’s possible that might be a bug in Pandoc itself, but fixed in master, going to compile my own Pandoc and see what happens.

Here is a PDF with @tambouri’s changes (but big fonts in the tables):

teletype.pdf (451.5 KB)


#153

do we have the process to update docs documented somewhere? the readme shows how to build them but not what files to update / guidelines on formatting.


#154

@tambouri what version of Pandoc do you have installed (pandoc --version), if it’s 2.0 then I think I’ve got your issue fixed.

As far as I know brew and Arch Linux have Pandoc 2.0, and it looks like Chocolatey is pending an update to 2.0 real soon now™.

The above commit forces 2.0 on everyone, if we’re happy with that I can open up a PR, otherwise someone else will need to take it up and tweak the Python code to be happy with 1.x and 2.0. I don’t have the time to try to get both versions of Pandoc installed so that I can test.

Not really no, if someone wants to volunteer to do a write up for a docs/README.md file I can brain dump.

It’s not that complex. The Markdown is whatever flavour that Pandoc calls markdown (it has several flavours of Markdown built into it).


#155

no problem, i’ll take a look at some PRs to get an idea.


#156

My pandoc is 1.19.2.1 so I’ll get on finding an update shortly.

Looking through your .pdf it doesn’t appear like it caught my update, not sure what might have caused that, but let me know if there’s anything i can provide or do to assist!


#157

That’s probably my bad. I think I must have got wrapped up in try to fix the compile bugs and forgot which branch I was on. I’ll try and upload another PDF tomorrow.


#158

Here you go: teletype.pdf (512.4 KB)


#159

Were the Visual Glitches, mentioned in the Known Issues section, fixed in 2.1? If so, Is the “Known Issues” section needed anymore?


#160

I don’t know if this is the right place to put this? The cheat sheet says CTRL-(1–8) will trigger scripts, but in fact the function keys F1–8 are what does this.

Happy to fix this myself if someone can point me in the right direction.