Oh man... Safari threw away my long draft comment when I changed SPA tabs, sad 😞

• docs/branchless.md has had its leading horizontal rules changed from 3 to 5 hyphens, to avoid triggering the frontmatter parser. 5 hyphens is what cmark outputs anyway, so it’s slightly more consistent, too.

I think I sometimes type 3 hyphens... does it give an okay error message if one does that? Otherwise I can learn to not do that.

• The output of .github/ISSUE_TEMPLATE/bug_report.md had previously incorrectly included the frontmatter (interpreting the separators as horizontal rules). Now, that frontmatter is removed (although it could alternatively be preserved if we decide to preserve unknown frontmatter contents).

I think we probably want to preserve it, in case we're creating markdown output to feed into something else, like a blog? It's not urgent at the moment though.

the output includes a path to a temporary directory, which changes on every run

Yeah this has bitten us before, and I don't remember why it wasn't currently an issue.

One idea off the top of my head would be to add an --redact-watcher-hint or something, which is set to True in bin/transcripts, which gives you:

  There's nothing for me to add right now.

  Hint: I'm currently watching for definitions in .u files under
        the <redacted> directory.  Make sure you've updated something 
         there before using the `update` command, or use `load` to load
        a file explicitly.  

or just redact it when running a transcript, without exposing an explicit option.

And one minor loose end: since the getHidden behavior is represented as a function (to be able to change the handling only for certain stanzas), we can’t represent it in YAML. So it’s not configurable directly, but only as part of a transcript type (like “tutorial”).

I didn't understand what this one refers to?

• docs/branchless.md has had its leading horizontal rules changed from 3 to 5 hyphens, to avoid triggering the frontmatter parser. 5 hyphens is what cmark outputs anyway, so it’s slightly more consistent, too.

I think I sometimes type 3 hyphens... does it give an okay error message if one does that? Otherwise I can learn to not do that.

It’s only a problem if

1. three hyphens is the first line in the file,
2. there is another three-hyphen-only line somewhere else in the file, and
3. what’s in between those two lines parses as YAML.

Otherwise, it’s fine.

If you do hit that particular case (which I’m not sure that docs/branchless.md even does, because I don’t think I had implemented the third condition when I changed that), then that block will just disappear from the output, as the ISSUE_TEMPLATE/bug_report.md case does.

Basically, frontmatter never errors – if it’s not valid YAML, we assume it’s markdown; if it is valid YAML, we either process it as transcript settings or discard it (we’re a bit lax – if you have transcript settings mixed with other stuff, we’ll handle the transcript settings and discard the rest).

I think we probably want to preserve it, in case we're creating markdown output to feed into something else, like a blog? It's not urgent at the moment though.

Yeah, that’s reasonable. I think it’s easy enough to change. We’ll just hold Aeson.Value in the AST, and only use Transcript.Settings locally.

the output includes a path to a temporary directory, which changes on every run

Yeah this has bitten us before, and I don't remember why it wasn't currently an issue.

One idea off the top of my head would be to add an --redact-watcher-hint or something, which is set to True in bin/transcripts, which gives you:

  There's nothing for me to add right now.

  Hint: I'm currently watching for definitions in .u files under
        the <redacted> directory.  Make sure you've updated something 
         there before using the `update` command, or use `load` to load
        a file explicitly.  

or just redact it when running a transcript, without exposing an explicit option.

Yeah, this seems reasonable.

And one minor loose end: since the getHidden behavior is represented as a function (to be able to change the handling only for certain stanzas), we can’t represent it in YAML. So it’s not configurable directly, but only as part of a transcript type (like “tutorial”).

I didn't understand what this one refers to?

So, in the Haskell, we have a type like

data Behaviors = {
  autoupdate :: Bool,
  getHidden :: ProcessedBlock -> Hidden,
}

getHidden takes the current stanza and returns HideOutput/HideAll/Shown. It does it this way because the “tutorial” type only hides output by default on unison blocks, not ucm or api.

Internally, it’s easy to define the Tutorial transcript type with a function that does the right thing.

And while autoupdate is just a bool, so it’s easy to map it to

---
autoupdate: true
---

in the frontmatter, we can’t put

---
getHidden: \stanza -> if type stanza == "unison" then HideOutput else Shown
---

and expect anything reasonable to happen.

So, maybe getHidden should be split into three settings – one for each stanza type … or maybe there’s another solution.

the output includes a path to a temporary directory, which changes on every run

Yeah this has bitten us before, and I don't remember why it wasn't currently an issue.

I fixed this, and then when merging trunk, I noticed that @ChrisPenner solved the same issue on the MCP side of things, so I unified the two.

So, maybe getHidden should be split into three settings – one for each stanza type … or maybe there’s another solution.

Ah, ok I think I get it. Honestly I don't think we'll find we want to configure the defaults all of these; but if we do, then I think splitting it into three settings would make sense.

Auto-hiding the unison block output makes sense to me (at the moment), because it's reasonable to author a transcript where you're implying that all the code type checks at least.

For auto-hiding the ucm block output I guess I'm not sure about. I'm not sure what the point of a transcript that runs a bunch of ucm commands in a throw-away codebase and also doesn't show you the output of the commands would be. I'm not sure there's not a use case for it, but it's not jumping out at me.

And then for auto-hiding api block output, I'd defer to @ChrisPenner, I guess it have to be some transcript where you use API calls to set up a bunch of data before manually :showing something? I'm not sure how often that comes up.

tl;dr: I think this is good as-is for now. (:

So, maybe getHidden should be split into three settings – one for each stanza type … or maybe there’s another solution.

Ah, ok I think I get it. Honestly I don't think we'll find we want to configure the defaults all of these; but if we do, then I think splitting it into three settings would make sense.

Ah, that’s a good point. We could expose a single hide-unison-output: Bool setting or something, and not worry about the other two yet. But yeah, that’s a minor¹ change, so fine to defer.