#81

I’ve started working on the OPs reference / cheatsheet. It will be automatically generated using the toml data files, and the short description field. I can work on it a bit the beginning of this week, and I’ve pencilled in a big block of time on Friday to get it finished.

This one will be done directly to a Latex template, not via Markdown / Pandoc1. So I should be able to make it very compact, and generally have a lot more control over the layout. It will be PDF only.

Most likely it will be multi-columned. I’ll decide on the number of columns, etc once I’ve got I’ve got something working. We might be able to get Latex to spit out a foldable booklet.

1 Technically I do need to use Pandoc to convert each short description to Latex, but they are only fragments, all the structural elements of the document will be done directly in Latex.

You could do something like that for the key reference? That’s not going to be something that changes frequently. I think for the cheatsheet automated is the way to go.

#82

Yes sure, whatever makes most sense!

#83

Output success!

cheatsheet.pdf (46.6 KB)

But definitely needs more work… :flushed:

edit: improving…

cheatsheet.pdf (61.2 KB)

6 Likes
#84

Is this being done in TeX? Looks good!

Maybe something can be done to prevent operators and their description from being broken across columns?

1 Like
#85

Yeah, I will most likely set up a minipage environment for each OP and it’s description to keep them together.

Just trying to get the build process sorted before I start fiddling with the looks.

2 Likes
#86

excellent update sheet!

#87

Update looks fantastic! Ideas

  • TT version at the top

  • I had a suggestion for the external ops to all be separate and last…but they already are. I didn’t catch the labels when I opened the cheat sheet on my phone…there’s so many external ops they take up multiple pages (which is awesome)

#88

@sam do you have a branch this is on? I’m curious to poke around and see how you’ve did this.

#89

No branch yet. It’s all unstaged in my repo.

I haven’t quite figured out the best way to build it. But at the moment it’s:

A master cheatsheet.tex file. Which then \inputs another Latex file that I have been generated with a Jinja template from the toml files. The cheatsheet.tex file sets up the fonts and the columns, etc, etc.

Each of the short descriptions from the toml files has been run through Pandoc to turn the Markdown into a snippet of Latex. That’s was actually really slow, so I have used the Python multiprocessing code to run it in parallel.

Before I commit it, I’ll get the included Latex file to be built automatically via Makefile dependencies.

Today’s task is to switch to using a Latex macro to render each OP, and for those to be rendered within a minipage which should stop them being split over columns.

I also need to get a handle on the fonts, and in particular the font sizes.

The ordering of sections is the same as the main docs, though the list is currently duplicated.

The ordering of OPs within each section is based on the order within the toml file (like the main docs). Looking at them, there are a few that could do with re-ordering.

Yeah, the main docs need this too. A nice picture for the front page wouldn’t go amiss either…

1 Like
#90

Ditched Jinja for the cheatsheets. Trying to work with it and the curly braces that Latex uses was driving me crazy. The content being generated by Python is so minimal that I’m just doing it with string manipulation instead.

This is an example of the content:

\group{Variables}

\begin{op}{A / A x}
get / set the variable \texttt{A}, default \texttt{1}
\end{op}

The op macro is super basic (and totally indecipherable):

\NewDocumentEnvironment{op}{o m}{
  \fontsize{9.0pt}{9.4pt}\selectfont
  \begin{minipage}[t]{\linewidth}
    \textbf{\texttt{#2}}
    \\
}{
  \end{minipage}
}

Anyway, it’s looking a lot better now: cheatsheet.pdf (58.4 KB)

Need to add the aliases in.

I’m thinking that I might put a page break in before the WW/ES/MP/Orca/Ansible/JF OPs start, and then another one before the Telex ones.

The JF OPs need splitting into “short” and “long” descriptions.

The other experiment I would like to try is using a narrow monospace font for all the text, something like Iosevka.

8 Likes
#91

Wow, yeah new version looks fantastic!

1 Like
#92

This is great ! It looks really nice

1 Like
#93

The new version looks really great! This is going to be incredibly helpful for me. :smile:

1 Like
#94

This is really great, thankyou

1 Like
#95

This is great and easy to read. Sadly, it also reminds me I only use a handful of commands and need to step my game up.

4 Likes
#96

Love the cheat sheet!
Thank you all for all the awesome work on the firmware updates and documentation!
Really amazing work!

1 Like
#98

Thanks for the nice comments everyone. Sorry it’s taken me so long to get the cheat sheet sorted, I originally intended to get it out alongside the 2.0 release. Anyway it’s nice to show some tangible benefits to the (slightly) obtuse documentation system I came up with.

I’ve got the build system up and running nicely, developers when the PR comes in, you can inspect the Makefile in the docs directory to see your options. Also running make in the project root spits out a zip file with the firmware, the flashing scripts, the PDF and HTML docs, and the cheat sheet.

There is no Teletype version listed in any of the docs. Sorting that out will require fiddling with the way that the firmware is built so that we can specify the version in a single place. I’d rather not do that while the 2.1 release is brewing.

Here are 4 variations on the cheat sheet PDF:

  • Variation 1: variation_1.pdf (63.1 KB)
    Uses the same Roboto and Roboto Mono fonts as the main docs. Has underlined headings, no divider lines, and no page breaks

  • Variation 2: variation_2.pdf (62.7 KB)
    As variation 1, but with divider lines between the columns, and no underline on the headers

  • Variation 3: variation_3.pdf (46.9 KB)
    As variation 1, but uses a customised build of the Iosevka font, sized slightly smaller. (The custom build is one I made for use on my computer.)

  • Variation 4: variation_4.pdf (63.4 KB)
    As variation 1, but with page breaks after the built in OPs, and before the TELEX OPs.

The page break variation is a bit uneven, but more OPs are about to be added (turtle, and then timeline). It has the big advantage that the internal OPs can be printed double sided on a single sheet of paper.

The page is set for A4 size (sorry Americans…) and has tiny margins, your printer should be able to take care of outputting it correctly.

If a strong consensus emerges on what variation or combination of variations works best I will implement it and open up a PR. If there isn’t a consensus I’ll just pick myself.

6 Likes
#99

Wow, what a great work! Thanks a lot for doing this and providing different versions for the discussion! :heart:

I like the lines between the columns for better readability and the page breaks between built in OPs, Ansible/Trilogy i2c OPs and TX OPs.

The small font is a bit hard to read for me and my eyes. If I had to choose between lines between columns and page breaks I would definitely vote for page breaks cause they give a nice thematic structure that fits how I search for OPs and makes the whole document less overwhelming.

:grinning::+1:

1 Like
#100

these look great! i think my preference will be for #1. i do like vertical dividers too though.

one thing to keep in mind is there will be grid ops too eventually (hopefully), and i would love to see a lot more remotes for all trilogy modules and ansible modes (i’ll open a proper discussion on this at some point and will be happy to do the dev work but thought i’d mention it now). so from this perspective page breaks make sense so that it’s easy to print only what is of interest for you, although i prefer no page breaks myself. would it be difficult to have 2 versions?

#101

I’m with @scanner_darkly on this liking the horizontal and vertical lines. Could you output a version with both?

Also agree with @Leverkusen about font size on variation 3 and 4 - too small for me.