#162

yeah, it’s really outdated (v1.3). i don’t think there is a markdown file for it, i only see the actual pdf here: https://github.com/monome/docs/tree/master/docs/modular/teletype

all the latest docs are now generated from markdown files which are located in the teletype repository: https://github.com/monome/teletype/tree/master/docs

it should be probably replaced by https://github.com/monome/teletype/blob/master/docs/keys.md

i don’t know much about how the docs are generated - @jlmitch5 is it pretty straight forward to generate a pdf version?

1 Like
#163

I’m not actually entirely sure about the cheatsheet process. @sam would know.

It looks to use the same dependencies as generating the regular docs (pypandoc/latex), with the addition of latexmk as part of the make task.

Here’s the python file used to generate the body. This is called as part of a dependent makefile task to generate an include.tex, which is included with the latexmk command. See here for the definition of those two tasks.

1 Like
#164

awww man, if it’s LaTeX at the bottom I’m gonna be tempted to make it prettier

3 Likes
#165

Sounds good! All the deps needed to build are described in the readme at the root of the repo, and the python/pandoc stuff is really more or less glue for getting things into the templates as defined here.

2 Likes
#166

Can you tell me what version of pandoc you have installed?

pandoc --verison

There is difference between the command line options in version 1.x and 2.x. I need to submit a patch to fix it, but it would be nice to know if I need it to work with both 1.x and 2.x. (If you do have a 1.x version, can you update to get the latest?)

There is also a small bug in cheatsheet.py for escaping Latex strings, so I need to PR that too.

Here is the current cheatsheet.pdf with the ER-301, W/, and Fader ops added in, couldn’t see any docs for the grid ops. There are still one or two bugs in the output that need fixing.

cheatsheet.pdf (71.7 KB)

In general

cd teletype
make release        # builds a zip file with everything in it, very handy!
cd docs
make                # builds all the docs
make teletype.pdf   # builds just the PDF docs
make teletype.html  # ... you get the idea
make cheatsheet/cheatsheet.pdf

However, these won’t work for you until I get my PR in!

2 Likes
#167

i don’t actually have the doc toolchain set up, was going to ask for help with generating docs, but i really should get it set up so i can generate a proper release.

docs is the last remaining step, grid ops as you mentioned and a few other new ops / aliases / keyboard shortcuts. will likely finish it mid next week.

1 Like
#168

Are you going to do it in WSL? If so, can you get pandoc installed and let me know the version? Then I can submit a PR to fix a few of the bugs that have crept in over the last few months.

#169

yep, WSL. just installed it, i got 1.16.0.2
i did recently update WSL and it’s running Ubuntu 16.04.4 LTS which i think is the latest available for WSL

#170

Ubuntu 18.04 is available:

You should probably upgrade when you feel ready. It only has Pandoc 1.19 though.

I’ll prep a PR to add support for working with either Pandoc 1.x or 2.x, what branch should I base against?

#171

I tried building the docs based on @scanner_darkly fork today, and got warnings in the maths.toml from the |&~^ ops. This translates into LaTeX errors which prevent the PDF being built.

Edit: The warning comes from not finding those chars in the all_ops set. I think they need synonyms in src/ops/maths.c and in utils/common/init.py. I’ll try that.

1 Like
#172

that would be a separate distro though, right? so i’d need to reinstall all the toolchains i currently have. if it doesn’t make a difference to what versions of pandoc we have to support i’ll just wait for my distro to be updated. is it a lot of work to support both versions?

for a PR master branch probably best? and then i can merge into my branch.

re: doc errors - if somebody could find/fix/make a PR that’d be awesome, as i have very little knowledge of LaTeX etc. this one would need to be against my branch: https://github.com/scanner-darkly/teletype/tree/grid2

#173

Is there a discussion of how we decided on using pandoc? I understand the benefits of automating aspects of this step, but at the same time, typesetting seems like something that could use a closer eye.

Or I guess let me rephrase: I have a good amount of LaTeX knowledge and would enjoy helping to make the docs read better in PDF. What role could I play in that?

2 Likes
#174

Is there a discussion of how we decided on using pandoc?

Was part of the big 2.0 rehaul. It is useful in helping maintain both the html and pdf version of the doc. See this.

I have a good amount of LaTeX knowledge and would enjoy helping to make the docs read better in PDF. What role could I play in that?

Shouldn’t be difficult to do with pandoc. here’s the preamble you can edit. The body template is using the default (right now), let me figure out where I found the html one to customize…

EDIT: @alanza it’s here. To customize the html one, I just copied and pasted the html one from this repo into the templates directory and added the tweaks I wanted, and then include the custom --template parameter with pandoc. You could do the same thing for the pdf (latex-based) one I think.

Cheatsheet PDF creation is more custom, I believe. There was quite a bit of iterating on that to get the styles right earlier in this thread if I remember correctly.

1 Like
#175

Edit: Figured it out. Pull request submitted.

1 Like
#176

wow, that template is HUGE! All right, clearly I have some reading to do.

My bias is that actually editing the LaTeX directly could turn out to be much easier than this approach, although I understand the desire to standardize.

1 Like
#177

yeah the html template was not the cleanest thing but wasn’t too bad to hack on once I got in there. I’m a latex novice so I’m not really sure what the best way to approach.

Theoretically, you wouldn’t need to start with copy and pasting the default template, you could just use it as a sort of guide to see how to get the variables pandoc expects and start from something nice, custom and clean!

1 Like
#178

Ahh, yeah that’s a good suggestion and probably the approach I’ll take.

1 Like
#179

I can’t recall my exact reasoning, but it’s designed to be Markdown/CommonMark as everyone knows it already, plus toml files to act as a database.

That way we can:

  • generate HTML
  • generate PDF
  • generate a cheatsheet PDF
  • check that no OPs have missing docs (via some ‘funky’ Python scripts)

all from a single corpus of documentation. Ultimately the aim is to keep the workload down and make sure the documentation is incorporated with the source code so that it’s kept up to date.

Does that make sense?

Look and feel improvements are always welcome, but it needs to be part of the same automated process that makes the current docs. If you’re still interested I can try and pass on some tips to make experimenting easier.

Can I PR against the same branch as otherwise I’d have to make the same changes against master and it will start to get messy. (There is another bug with ~ not being escaped properly, as well as the Pandoc 1.x vs 2.x issues.)

#180

Im not sure what you mean? Won’t the grid2 branch get merged back into master? If not, then I might need slightly more explicit instructions.

#181

yeah, whatever makes sense, just thought it’s cleaner from history point of view if a PR is done against master. either way works for me! i’ve merged @GoneCaving PR already.