Teletype docs enhancements (redesign in progress)

jlmitch5 · 2018-11-02T02:26:58.369Z

Ah gotcha, yes it’s awesome how many ops there are!

Also glad y’all pushed for putting this back in a table. I think it works really well for a quick reference laid out like this–I can see myself referring back to this now.

Leverkusen · 2018-11-02T05:38:15.491Z

Hm, seems to be somehow broken - when I try it on the iPad I get this:

image.png1536×2048 140 KB

Unfortunately, tapping on the links does nothing.

jlmitch5 · 2018-11-02T13:16:19.103Z

Hmm this looks to be like the JavaScript isn’t running to transform those links, I’ve ran into this before. It works on iOS (iPhone) for me—just tested it. Can you double check a refresh doesn’t fix this @Leverkusen

scanner_darkly · 2018-11-02T17:06:11.644Z

thank you, the new alphabetical list looks great!!

jlmitch5:

I think it could slightly be improved with a docs rewrite of the grid ops

yeah as i was looking at it i thought the left column could be narrower, and sure enough the reason is grid ops. i agree it would be good to shorten them somehow, but maybe we could find a way to do so without affecting readability. my concern with non descriptive names is it will mean jumping back and forth between the op and the description a lot, which is especially bad for ops with lots of parameters.

maybe i could shorten them a bit without affecting readability? so instead of:

G.FDX id x y w h type level script columns rows

it could be

G.FDX id x y w h typ lev scr col row

also would be good to split jf/telex descriptions into short and long descriptions - something like JF.QT x takes a lot of space in the alphabetical list right now. perhaps somebody could volunteer to go over them and change?

alanza · 2018-11-02T17:10:20.999Z

I can do this! I’ll have some time this weekend.

scanner_darkly · 2018-11-02T17:16:24.208Z

excellent! ping me whenever if you need help with anything, i’m doing a coding marathon this weekend so will be at computer most of the time (excluding evenings).

jlmitch5 · 2018-11-02T17:29:32.237Z

awesome, let me know if you want things built to that staging link or anything.

Leverkusen · 2018-11-02T19:47:21.408Z

I am not sure what you mean by refresh. Just tested it again with iPad and iPhone and it is the same on both devices, just the blue list and tapping one of the links brings me back to the very same page.

I am pretty sure it worked with the previous version though. I just cannot find a working previous version now. Are the links from this thread all the same?

jlmitch5 · 2018-11-02T21:44:43.138Z

@Leverkusen should be. link is https://teletype-docs.now.sh

alanza · 2018-11-03T00:10:11.195Z

okay Git hygiene question; is editing whatever version of the 3.0 docs okay, or is there a particular branch I should fork from?

scanner_darkly · 2018-11-03T02:11:00.866Z

heads up, i’ve just merged @alphacactus’s PR which includes new doc for J and K variables, if you use master branch make sure to pull the latest!

alanza · 2018-11-03T04:13:39.419Z

@jlmitch5 I just noticed, the table has left column label "OP includes set notation and aliases". The latter part of that should (a) not be bolded (my goto here would be smaller font, italics and parentheses but maybe that’s overkill) and (b) maybe something should be done so it doesn’t increase the width of the left column quite so severely.

You guys I am learning so much Git by doing this it’s great. And once I’m actually up and editing I’ll learn so much more Teletype!

alanza · 2018-11-03T14:35:29.890Z

is it all right if I also editorialize away from x y z for OP argument letters in some instances? Especially in cases where another letter or short string would be more descriptive, I think this will help the documentation’s legibility.

I say “is it all right”, but I’m going ahead and making that change on my branch xD

EqualTemperament · 2018-11-03T15:22:03.969Z

Seems to me like there’s already a precedent for doing this - at least in the cheat sheet / command reference. Grid ops don’t really follow the x y z pattern. E.g.

G.BTX id x y w h type level script columns rows

I think it would make some of them more readable.

scanner_darkly · 2018-11-03T16:55:01.238Z

alanza:

Especially in cases where another letter or short string would be more descriptive

this would be great, as it would also improve consistency between different ops.

EqualTemperament:

Grid ops don’t really follow the x y z pattern

for grid ops x and y specifically mean the x/y control coordinates, so made sense to name the parameters accordingly (and i thought w and h are pretty self explanatory in this context too).

alanza:

once I’m actually up and editing I’ll learn so much more Teletype!

i had more than one occasion of “oh didn’t know there was an op for that!” while looking at the code

jlmitch5 · 2018-11-03T18:53:13.374Z

@tehn PR up! I can fix PDF building as part of this PR or right after, whichever works. Let me know if you need anything.

@alanza thanks for the feedback, I fixed the header, I think:

Screen Shot 2018-11-03 at 2.40.52 PM.png1005×438 37.5 KB

EqualTemperament · 2018-11-03T19:06:20.762Z

Thanks a ton for your efforts here!

Leverkusen · 2018-11-03T21:53:19.096Z

jlmitch5:

@Leverkusen should be. link is https://teletype-docs.now.sh

I still can’t use this on neither my iPhone nor the iPad. I am on iOS 9 on both of them and I am sure there was a previous version, that worked though.

jlmitch5 · 2018-11-03T22:08:00.156Z

I’ll see if I can pull up a cross browser testing tool and check iOS 9. Latest does work on iOS 12 for sure.

I removed all newer style js I was using when I cleaned up the code, so I’m puzzled as to what it could be.

If you have the ability to pull up the console on safari and tell me if you see any error messages, that would be helpful.

47C608C8-D893-4655-9EC6-16A74ED498B9.jpg1125×2436 376 KB

jlmitch5 · 2018-11-04T00:14:36.572Z

actually, pretty sure I know what’s wrong—need to convert forEach to standard for loops. I moved that code from an isolated script tag to the main area, which is why it would have worked before and stopped working once I made that change. I’ll let you know when I’ve made that update