development tutorial transcript mode

[aryairani]

Walkthroughs of Unison app development are super valuable for teaching and promotion.

Unfortunately, for writing up such a walkthrough, it turns out that neither the scratch file nor the transcript is very convenient.

The scratch file is too mutable: If you want to show multiple iterations of development, you must throw away (or manually archive) early versions of the application as you work, or keep them in separate sub-namespaces and never use the update command. Neither option is very good.

The transcript isn't nice for this purpose either. Your code isn't syntax-highlighted either in the editor or in the output (I assume this could be improved, through the Unison vscode plugin). You have to manually add after each unison buffer, which creates unnecessary clutter for the author and for the reader. Unless you're trying to demonstrate details of the type checker, you always want to add/update every code stanza. On the plus side, you can run them and verify the result before publishing the tutorial, but each run is manual instead of interactive like the scratch file.

Unison Docs are almost a good option here — it's great that they can hyperlink to Unison code easily—but again, they are a clumsy tool for illustrating multiple iterations of an application, and there's no way to test them for correctness.

Describe the solution you'd like

Option 1: interactive extended transcript mode + syntax highlighting

(Syntax highlighting is already released now via unisonweb/vscode-unison#21 thanks to @dfreeman.)

Syntax:

Hi I'm writing a new application!

```ucm :hide branch=project/main autoupdate=true
> lib.install @unison/base
> lib.install @unison/http
> lib.install @unison/cloud
```

Each command is assumed to be in a branch specified by the most recent `branch` attribute. 
The default is `scratch/main`.  The output transcript can include the active branch in the prompt.

Here we've skipped `project.create` and just manually `> lib.install @unison/base`. 
This seems okay for the moment.

```unison
foo = "new code" 
```

Because of the active `autoupdate=true`, code blocks are automatically added/updated into the branch.
`:hide` is implied when `autoupdate=true`; we're not trying to teach how to use `ucm` here.

```unison
foo = "newer code" 
```

Blah blah blah, now `foo` is much better.

Behavior:

The file watcher watches this file (possibly activated with some kind of load or watch command. The file parsed and executed stanza by stanza in a temporary branch until the end is reached or until an error is encountered. Errors are reported with the corresponding line number in the markdown file in the output and in LSP. (Not the line number relative to the start of the stanza.)

The syntax highlighter highlights the markdown and the Unison.

Note: because we don't have a syntax for Shown :: Hidden, there's no conflict currently between that and autoupdate=true implying HideOutput.

Option 2: An extended scratch file mode + syntax highlighting

It's a mode where if there are duplicate-named definitions in the file, they're all type checked, but later ones replace earlier ones. This lets you draft multiple versions of the application in the scratch file, utilizing the file watcher, interactive type checker, language server.

Maybe easier to implement (could it be something with just incrementing the symbol numbers?); but to splice the results together into a blog post once finished is extra manual work.

[sellout]

tl;dr

Build on transcripts. AFAICT, the changes needed for an MVP are (in order)

1. add “watch” functionality to the transcript runner,
2. choose and implement an autoupdate approach (I describe two I think are better below), and
3. support omitting the branch from UCM commands.

the long version

Overall, I think transcripts are the best starting place. They allow you to interleave the prose with the definitions you’re writing, and the unison blocks are explicitly the series of scratch files that you would iterate through. You mention Doc, and I do imagine Doc being able to describe transcripts at some point, but yeah, I don’t think it’s the answer for this yet¹.

adding new info string fields

If we add fields, like branch and autoupdate (more on those specific ones later), I think it might be time to overhaul the entire info string format.

autoupdate info string field

Since autoupdate affects all future stanzas, I don’t think adding it to the info string is the right place. We could use some form of metadata for things that span blocks. E.g., link reference definitons seem to be an accepted way to fit metadata into valid CommonMark/GFM documents. The syntax is slightly awkward (the <> is for an empty link destination), but not too bad.

[_unison:autoupdate]: <> "true"

```ucm :hide branch=project/main
> lib.install @unison/base
```

```unison
foo = "new code" 
```

```unison
foo = "newer code" 
```

One shortcoming is that they’re global – you can’t do [_unison:autoupdate]: <> "false" later in the document to switch it off – the first definition is the one that’s used.

However, at least CMark seems to give us no way to directly access these references (it makes sense, they’re only reflected in the output when links reference them). In which case, I think we could tack on a list that enumerates all of the metadata we’re aware of, like

- [_unison:autoupdate]
- [_unison:some-other-var]

before handing the text to CMark, then pop that block off for separate processing.

Alternatively, we could add a new kind of active stanza, say

``` transcript
autoupdate: true
```

Also valid Markdown, and it could be used multiple times, updating the runner state from that point on. Or piggyback off an existing language:

``` dhall :transcript
{autoupdate = True}
```

Ok, so maybe you don’t want Dhall … but YAML, TOML, whatever.

“branch” info string field

I wonder if this carries its weight. I do think that using > should be allowed in order to mean “whatever project/branch we’re already on”, and that we should default to scratch/main.

You can currently achieve the same thing with

project/main> lib.install @unison/base
> lib.install @unison/http
> lib.install @unison/cloud

and I’m pretty sure that this will also work

project/main>
> lib.install @unison/base
> lib.install @unison/http
> lib.install @unison/cloud

But in tutorials, it might be helpful to be explicit in what you’re doing, like

> project.create my-project
> lib.install @unison/http

Hidden/autoupdate conflict

If we do change the info string syntax like I said earlier, then there probably would be a syntax for Shown (say, a key show with options none (currently :hide-all), input, (currently :hide), and all (no current syntax), But I don’t think that causes a problem – one of the effects of autoupdate is to change the default value for show from all to input, and then a block could still use ``` unison {show=all} to override autoupdate’s hide behavior on that block.

But, with my other suggestions, we might not need to update the info string syntax, so we could still achieve this just by adding a :show tag (or :hide-none?).

And just for clarity: it’s only unison blocks that default to :hide when autoupdate is on, right?

other comments

Errors are reported with the corresponding line number in the markdown file in the output and in LSP. (Not the line number relative to the start of the stanza.)

I think the current transcript runner does a good job with this (#5387), and I don’t see anything in the description that isn’t covered by “automatically re-run the transcript runner on save”.

However … I can imagine another level of interactivity, where the user can page though the tutorial, stanza by stanza, stopping and editing blocks as they go (maybe actually using a scratch file to populate the current block on save), with some key bindings for like “next stanza”², “copy stanza to scratch file”, “revert stanza to original”, etc.

And perhaps a “run to next input step”, which would require some way to mark stanzas as requiring edits before moving forward – I use :incomplete for that here:

Given what we’ve discussed thus far, complete the following definition:

``` unison :incomplete
parseValue :: Text -> Optional Value
parseValue = todo "implement me"

test> tutorial.tests.parseNum = check (parseValue "4" == Some (Number 4))
test> tutorial.tests.parseArray = check (parseValue "[1, 2]" == Some (Array [Number 1, Number 2]))
test> tutorial.tests.parseObject = check (parseValue "{x: 4}" == Some (Object (Map.fromList [("x", Number 4)])))
test> tutorial.tests.invalidObject = check (parseValue "{x: 4]" == None)
```

(I originally had the tests in a separate stanza, but then I realized that it would be hard to rewind the state doing that. This way, it errors before autoupdate happens, and allows further editing of the definition.)

Footnotes

1. Doc would need to have support for running UCM commands (say, using a Codebase ability 😜), and a bunch of other stuff. ↩

2. This implies the existence of a “prev stanza” binding, but that probably requires some rewinding of state. Other options are having “prev stanza” only being allowed to move through “inactive stanzas”, so the user can scroll back through paragraphs, or to separately track the view (maybe simply through scrolling) and the active stanza (which can only move forward). ↩

[aryairani]

Overall, I think transcripts are the best starting place.

Yeah, I'm convinced.

adding new info string fields

If we add fields, like branch and autoupdate (more on those specific ones later), I think it might be time to overhaul the entire info string format.

Mayyyybeeee. I kinda want to skip this just to get the immediately useful parts ready faster.

autoupdate info string field

Since autoupdate affects all future stanzas, I don’t think adding it to the info string is the right place.

Well... I do buy this argument, but the alternatives seem kind of bad?

We could use some form of metadata for things that span blocks. E.g., link reference definitons seem to be an accepted way to fit metadata into valid CommonMark/GFM documents. The syntax is slightly awkward (the <> is for an empty link destination), but not too bad.

It sounds like this is conceptually cleaner, but won't it just be useless noise in the HTML rendering, or do we manually delete these before going .md to .html?

One shortcoming is that they’re global – you can’t do [_unison:autoupdate]: <> "false" later in the document to switch it off – the first definition is the one that’s used.

This sounds like a downside, but it's conceivable that this won't be needed in practice.

Alternatively, we could add a new kind of active stanza, say

autoupdate: true

Also valid Markdown, and it could be used multiple times, updating the runner state from that point on.

This seems better to me than the link reference does, but again it's a bummer that it would show in the HTML by default. Maybe that's good in some cases, to answer "what exactly am I looking at?" but worse IMO for the motivating use case, my Unison tutorials ;-)

We could write our own HTML renderer, but there are so many ugly ones out there that I'm not confident we can commit to not being another of them.

“branch” info string field

I wonder if this carries its weight. I do think that using > should be allowed in order to mean “whatever project/branch we’re already on”, and that we should default to scratch/main.

You can currently achieve the same thing with

project/main> lib.install @unison/base
> lib.install @unison/http
> lib.install @unison/cloud

and I’m pretty sure that this will also work

project/main>
> lib.install @unison/base
> lib.install @unison/http
> lib.install @unison/cloud

But in tutorials, it might be helpful to be explicit in what you’re doing, like

> project.create my-project
> lib.install @unison/http

The current merge process and the upcoming update process in ucm allow ucm to switch branches for you, which also relates to this, since a transcript currently would have to be written carefully to avoid undoing that auto-switch. Having the branch name be implicit would probably help here; or: removing the feature that the prompt in a transcript implicitly switches branches, making an explicit project.create or switch necessary.

Hidden/autoupdate conflict

And just for clarity: it’s only unison blocks that default to :hide when autoupdate is on, right?

Yeah that was the idea. I was split on "should 'default to :hide' be a separate option? That would be cleaner, but honestly I think you want ``` unison :hide most of the time for advanced usage, even in today's transcripts.

Maybe :hide/input should be the default in general, and :show-typechecking-result or whatever should be the opt-in. Like what does the type checking output get you if you know everything type checked?

And yeah to your other comment https://discord.com/channels/@me/1225814649958826065/1392604008425853148 we could sidestep this question by having it be a "tutorial" mode initially, and maybe we'll learn more with some dog-fooding, about what things should be called or what their defaults should be.

other comments

Errors are reported with the corresponding line number in the markdown file in the output and in LSP. (Not the line number relative to the start of the stanza.)

I think the current transcript runner does a good job with this (#5387), and I don’t see anything in the description that isn’t covered by “automatically re-run the transcript runner on save”.

Oh I forgot about this, great. In that case maybe a format that can be parsed by vscode would be good somewhere, so you could just click through from the error to the code.

However … I can imagine another level of interactivity,

Future work ❤️

---

So — thanks to the excellent above discussion, I think I'm realizing that adding any way to enable "auto-update + auto-hide" is the primarily helpful feature here, with probably the implicit branch syntax being next, and LSP support or file watching, is third. Did I miss anything?

[sellout]

So — thanks to the excellent above discussion, I think I'm realizing that adding any way to enable "auto-update + auto-hide" is the primarily helpful feature here, with probably the implicit branch syntax being next, and LSP support or file watching, is third. Did I miss anything?

Sounds good. Re: autoupdate, it’s also easy to add the logic with no mechanism, and then add the mechanism in a separate commit, so we can easily try a different one if the first one is too clunky.

We could use some form of metadata for things that span blocks. E.g., link reference definitons seem to be an accepted way to fit metadata into valid CommonMark/GFM documents.

It sounds like this is conceptually cleaner, but won't it just be useless noise in the HTML rendering, or do we manually delete these before going .md to .html?

Those won’t get rendered in HTML. They’re just shorthands for links, so

[foo]: <https://foo.com> "some foo thing"

Talking about [foo]. And here I go mentioning [foo] again.

becomes

Talking about [foo](https://foo.com "some foo thing"). And here I go mentioning [foo](https://foo.com "some foo thing") again.

before an HTML renderer gets its hands on it, which is why it makes a decent metadata encoding.

One shortcoming is that they’re global – you can’t do [_unison:autoupdate]: <> "false" later in the document to switch it off – the first definition is the one that’s used.

This sounds like a downside, but it's conceivable that this won't be needed in practice.

Yeah, who knows.

Alternatively, we could add a new kind of active stanza,

This seems better to me than the link reference does, but again it's a bummer that it would show in the HTML by default. Maybe that's good in some cases, to answer "what exactly am I looking at?" but worse IMO for the motivating use case, my Unison tutorials ;-)

Yeah, this would show up in the HTML, but I’d say in this case it’s a good thing – if you switch the behavior of unison blocks partway through the doc, you want a heads-up that that’s happening. So, maybe a selling point for the link reference definitions – not appearing in HTML (and that being ok, because it’s static).

The current merge process and the upcoming update process in ucm allow ucm to switch branches for you, which also relates to this, since a transcript currently would have to be written carefully to avoid undoing that auto-switch. Having the branch name be implicit would probably help here; or: removing the feature that the prompt in a transcript implicitly switches branches, making an explicit project.create or switch necessary.

Ah, I’ve thought about this even without the merge and update complications, that the implicit switching might be too magical.

Maybe :hide/input should be the default in general, and :show-typechecking-result or whatever should be the opt-in. Like what does the type checking output get you if you know everything type checked?

Yeah, I think switching the default for unison makes sense. Maybe call it :show-result or something – we use the same tags on api and ucm, so even though it’s the default there, I think the name of the Shown case should make sense across all of them.

[aryairani]

Sounds good. Re: autoupdate, it’s also easy to add the logic with no mechanism, and then add the mechanism in a separate commit, so we can easily try a different one if the first one is too clunky.

👍

Those won’t get rendered in HTML. They’re just shorthands for links,

Oh, ok.

They still look a little weird, as you said, with the empty links, but maybe it's okay.

Alternatively, we could add a new kind of active stanza,

Maybe we could start with the links, and if we want to change a setting partway through we add support for the new kind of active stanza? idk.

Yeah, I think switching the default for unison makes sense. Maybe call it :show-result or something – we use the same tags on api and ucm, so even though it’s the default there, I think the name of the Shown case should make sense across all of them.

Oh and then one more thing I forgot to include in my list is that it's currently kind of a pain to find the actual error after a transcript failure. Maybe the interactive watcher would handle this? Or maybe just changing how the errors are printed so that it's printed more nicely, at the end of the output. Maybe even pretty-printed.

WDYT?

[dfreeman]

We could use some form of metadata for things that span blocks. E.g., link reference definitons seem to be an accepted way to fit metadata into valid CommonMark/GFM documents.

While not part of CommonMark or GFM themselves, there's fairly widespread de facto practice of attaching metadata as "YAML front matter" at the beginning of Markdown documents. Many tools that employ Markdown for document authoring use it, like GitHub Docs, Obsidian, and any number of other publishing/blogging platforms.

Some (many?) Markdown syntax highlighters even recognise it out of the box as embedded YAML:

It does still share the limitation with the link suggestion of being global in scope, but has the advantage of pretty widespread adoption/support as a format.

[sellout]

@dfreeman You’re right – that’s the simplest approach, and also supported by GitHub (despite not being a part of GFM somehow), so that’s what I used. Thanks.

[zetashift]

Oh fun! Literate programming a la org-babel, I wish I had stumbled on this thread sooner.

I also think transcript are the way to go,, I would like to add as reference, that livebook, uses "magic" HTML comments(which is part of the CommonMark spec(HTML comments that is, not the magic part)) to add special stuff to blocks:

e.g.

<!-- livebook:{"file_entries":[{"name":"portal-drop.jpeg","type":"attachment"},{"name":"portal-list.jpeg","type":"attachment"}]} -->

Everything after the colon(:) is actually Elixir code. This makes using it in your editor a bit rougher, but since most people(if not all) docs are usually made through their web interface, it doesn't end up being a problem. Not saying that Unison should also go this route, but it's a nice to know, I think.