Make transcript output runnable as a transcript

[sellout]

Having to provide both a transcript and its output when describing a problem is frustrating. If you can run transcript output directly, this duplication becomes unnecessary.

There are a few things that need to change to allow this:

• the parser needs to ignore unison:added-by-ucm blocks;
• the ucm blocks added by the pretty-printer after unison blocks need a similar suffix so the parser can ignore them;
• the ucm block parser needs to be able to skip over command output;
• pretty-printed blocks need to preserve their :-separated flags;

and probably more.

Also, this can’t be expected to work with transcripts that use :hide:all.

[aryairani]

Seems reasonable, but how would you actually use this runnable output file?

Does the file get overwritten in place when you run it, or does it get another .output spliced into the filename?

I guess it would simply be the input file, and parts of it would be ignored.

[sellout]

Yeah, I don‘t think any of the transcript-running stuff has to change[^1]. Mostly this is so transcripts included in bug reports can be transcript outputs and just work.

[^1]: I wouldn’t be opposed to an --in-place flag or something, and that could eliminate like 99% of the .output.md files in the repo, but I think that’s a separate issue.

[aryairani]

Yeah, I'm starting to feel this. i.e. just let the outputs be usable as inputs.

[aryairani]

• the parser needs to ignore unison:added-by-ucm blocks;

we have a setting when we write a scratch file in ucm, as to whether ucm should immediately parse try to typecheck the newly-written file or ignore it. it's "skip" for edit but "normal" for update. it might be good if the transcript parser could do the same; I'm not sure yet what we could call the two flags though. maybe unison:added-by-ucm (gets parsed) and unison:skip or unison:ignored or unison:ignore (doesn't get parsed?)

or unison:ignore:added-by-ucm and unison:added-by-ucm

• the ucm blocks added by the pretty-printer after unison blocks need a similar suffix so the parser can ignore them;
• the ucm block parser needs to be able to skip over command output;

Maybe we can do something like: if the line starts with a prompt, then it's a command; if it starts with whitespace, then it gets ignored

• pretty-printed blocks need to preserve their :-separated flags;

yeah

[sellout]

• the parser needs to ignore unison:added-by-ucm blocks;

we have a setting when we write a scratch file in ucm, as to whether ucm should immediately parse try to typecheck the newly-written file or ignore it. it's "skip" for edit but "normal" for update. it might be good if the transcript parser could do the same; I'm not sure yet what we could call the two flags though. maybe unison:added-by-ucm (gets parsed) and unison:skip or unison:ignored or unison:ignore (doesn't get parsed?)

or unison:ignore:added-by-ucm and unison:added-by-ucm

I hadn’t connected them in my mind, but another feature I want is to be able to tag a code block in an (input) transcript as “skip” or something, so that ```unison:skip is entirely ignored by the transcript runner, and is only used to highlight via GH or whatever. So, whatever the flag is, I think it’d be good to think of a name that also makes sense when written by a user (as skip and ignore both do).

But … what are the cases where we want do ucm to immediately process the block? When a user writes a transcript, they’ll do

```ucm
scratch/main> builtins.merge
```

```unison:hide
foo = 2 + 2
```

```ucm
scratch/main> add
scratch/main> edit foo
```

When run, `ucm` inserts its `unison:added-by-ucm scratch.u` block here, and
we want it to be skipped, right? Since it gets explicitly loaded afterward? Or
am I just writing my transcripts wrong?

```ucm
scratch/main> load scratch.u
```

Can you show me a transcript where we want unison:added-by-ucm to be used and treated differently than unison:skip:added-by-ucm?

---

And I noticed that the unison:added-by-ucm scratch.u block gets output after the load if we have a transcript like

```ucm
scratch/main> add
scratch/main> edit foo
scratch/main> load scratch.u
```

Would it be better to split the original ucm block into two, and insert the unison:added-by-ucm block between them, like in my earlier example?