Improve relative / ordinal diagram in the docs

[MartinRykfors]

Checklist

• I have updated the docs and cheatsheet
• I have not broken the cheatsheet
• I have tested building the docs

Replace the hand-written diagram of relative / ordinal modifiers with one generated by LaTeX / tikz.

If it is necessary in the future to change this image, you can reuse and modify the below latex code to regenerate it.

\documentclass[tikz]{standalone}
\usepackage{tikz}
\usetikzlibrary{decorations.pathreplacing,calligraphy}

% to convert pdf -> png:
% convert -density 300 relative-ordinal.pdf -quality 100 -background white -alpha remove relative_ordinal.png

\begin{document}
\def\spacing{1.4cm}
\newcommand{\ibrace}[4]{
    \draw [decorate, decoration = {brace, amplitude=5pt}] (#2*\spacing, #1*0.8cm + 0.5cm) --  (#3*\spacing, #1*0.8cm + 0.5cm)
    node[above=5pt, pos=0.5, scale=0.8] {\texttt{"#4"}};
}
\newcommand{\bbrace}[4]{
    \draw [decorate, decoration = {brace, amplitude=5pt}] (#2*\spacing, #1*0.8cm + 0.5cm) --  (#3*\spacing, #1*0.8cm + 0.5cm)
    node[above=-20pt, pos=0.5, scale=0.8] {#4};
}
\newcommand{\funk}[3]{
    \draw[fill=black] (#1*\spacing,0) circle (0.1cm) node[below=#2, text width=1cm,align=left,scale=0.7] (F#1)
    {\texttt{"#3"}};
}
\begin{tikzpicture}[ultra thick]

\funk{0}{0pt}{first funk}
\funk{1}{0pt}{second funk}
\funk{2}{0pt}{third previous funk}
\funk{3}{0pt}{second previous funk}
\funk{4}{0pt}{previous funk}
\funk{5}{0pt}{funk}
\funk{6}{0pt}{next funk}
\funk{7}{0pt}{second next funk}
\funk{8}{0pt}{third next funk}
\funk{9}{0pt}{second last funk}
\funk{10}{0pt}{last funk}

\draw[latex-] (F5) -- +(0,-0.8cm) node[below=2pt,scale=0.8] {input target};

\ibrace{0}{6}{8}{next three funks};
\ibrace{0}{2}{4}{previous three funks};
\ibrace{1}{5}{7}{three funks};
\ibrace{2}{3}{5}{three funks backward};
\ibrace{0}{0}{1}{first two funks};
\ibrace{0}{9}{10}{last two funks};
\bbrace{-3}{10}{0}{iteration scope};
\end{tikzpicture}

\end{document}

[phillco]

Should we just check in the LaTeX code to the repo (and/or generate the PNG in CI)?

[pokey]

Ooh shiny ✨. I'm generally in favour of including raw source rather than generated output, but not sure it's worth the effort in this case. I'd be fine with either checking both latex and png in, or even just leaving it in the PR description as you've done, but either way it would be good to point to the diagram source the way we do here

[MartinRykfors]

I'll go with including the .tex file alongside the png in the repo, and link to it in the README.md file. Going to refactor the latex a bit and test to make sure the generated doc pages link properly to it.

[MartinRykfors]

Might do some experiments to see if it looks better if the dots are lined up vertically, which also would better match the way the funks are arranged when you see them in source code.

[MartinRykfors]

@pokey
I have tested running the site locally and it seems to work.
I had to settle with linking directly to the .tex file on github because using a relative link in the markdown would make it so that firefox would try to download the .tex file with an obfuscated name to disk.

[pokey]

well it's much prettier than my diagram 😄. but I fear it's less clear? idk @phillco @AndreasArvidsson wdyt? is it clear to you? any ideas how to make it clearer?

also, minor point, but I think I'd link to the source file on github rather than raw content. Then you'll get syntax highlighting and stuff. I wonder if our link checker will flag this one, as that link doesn't yet exist 🤔. We'll see. If it fails, I'm happy to just link to this PR, or just put a path there; prob won't be super often we'll want to click that link anyway looks like our link checker didn't flag it. Hmm. Will need to look into that, but for this PR that's fine. I'd still push for github source link tho to get syntax highlighting and stuff

also fwiw every PR has a deploy preview. Eg https://deploy-preview-1277--cursorless.netlify.app/docs/#syntactic-scopes

[MartinRykfors]

If you go back in the commit history you can see an earlier version where the funks were laid out horizontally. I gave up on that because I thought that the text would get all bunched up and look messy, but maybe it is still clearer than the vertical version?

I agree that the current version looks a bit busy. Maybe it could be split up into two different diagrams, one for forward references and one for backward ones. This would avoid the three layers of nesting for the braces. We could also elide some funks to avoid the 'from here forward' references neighboring the 'from last backward' references. So something like

                 O
                ...
            funk O (red)
     second funk O 
      third funk O
                ...
second last funk O
       last funk O 

together with braces for two funks, next two funks and last two funks, and then place the corresponding diagram for addressing funks above the target next to this one.

Happy to hear what you think.

[pokey]

Yeah splitting into multiple diagrams is a nice idea. I think including forward / backward in one diagram is ok. But I might have 3:

1. The relative exclusive ones
   • "next funk"
   • "second next funk"
   • "previous funk"
   • "second previous funk"
   • "next three funks"
   • "previous three funks"
2. The relative inclusive ones
   • "funk"
   • "three funks"
   • "three funks backward"
3. The ordinal / absolute ones
   • "first funk"
   • "second funk"
   • "first two funks"
   • "last funk"
   • "second last funk"
   • "last three funks"

I think your idea of using ellipses is nice as well, if that's easy to do. Could have ellipses at start and end of relative diagrams, and between red function and first / last in absolute diagram

One concern I have is that the problem may just be with using dots themselves. It's not immediately obvious that the dots correspond to functions in source code. I'd almost be tempted to have the diagram be labelling actual code 🤔

A simple thing to do would be to change the annotation at the bottom for the red dot to say "the function containing the input target"

@tararoys maybe you have some thoughts here? does this diagram make sense to you / any ideas for making it clearer?

[MartinRykfors]

Got some time over to work on this, the newest version can be seen here

[AndreasArvidsson]

That looks pretty good! :)

[pokey]

Wow that's awesome!