Format of exportable worksheets

[ckipp01]

If you had the ability to export the contents of an evaluated worksheet, how would you like those to be formatted. For example, lets say we have the following:

case class LongThing(a: String, b: String, c: String, d: String)

val longThing1 = LongThing("one", "two", "three", "four")
val longThing2 = LongThing("one", "two", "three", "four")
val longThing3 = LongThing("one", "two", "three", "four")
val longThing4 = LongThing("one", "two", "three", "four")
val longThing5 = LongThing("one", "two", "three", "four")

val myListOfThings =
  List(longThing1, longThing2, longThing3, longThing4, longThing5)

myListOfThings.map(_.copy(c = "now I'm five"))

[ckipp01]

Option A aka more concise:

case class LongThing(a: String, b: String, c: String, d: String)
val longThing1 = LongThing("one", "two", "three", "four") // : LongThing = LongThing("one", "two", "three", "four")
val longThing2 = LongThing("one", "two", "three", "four") // : LongThing = LongThing("one", "two", "three", "four")
val longThing3 = LongThing("one", "two", "three", "four") // : LongThing = LongThing("one", "two", "three", "four")
val longThing4 = LongThing("one", "two", "three", "four") // : LongThing = LongThing("one", "two", "three", "four")
val longThing5 = LongThing("one", "two", "three", "four") // : LongThing = LongThing("one", "two", "three", "four")
val myListOfThings =
  List(longThing1, longThing2, longThing3, longThing4, longThing5)
// myListOfThings: List[LongThing] = List(
//   LongThing("one", "two", "three", "four"),
//   LongThing("one", "two", "three", "four"),
//   LongThing("one", "two", "three", "four"),
//   LongThing("one", "two", "three", "four"),
//   LongThing("one", "two", "three", "four")
// )
myListOfThings.map(_.copy(c = "now I'm five"))
// res0: List[LongThing] = List(
//   LongThing("one", "two", "now I'm five", "four"),
//   LongThing("one", "two", "now I'm five", "four"),
//   LongThing("one", "two", "now I'm five", "four"),
//   LongThing("one", "two", "now I'm five", "four"),
//   LongThing("one", "two", "now I'm five", "four")
// )

The short evaluations that can fit on the same line are on the same line, and the long ones underneath.

[ckipp01]

Option B aka more consistent:

case class LongThing(a: String, b: String, c: String, d: String)

val longThing1 = LongThing("one", "two", "three", "four")
// longThing1: LongThing = LongThing("one", "two", "three", "four")
val longThing2 = LongThing("one", "two", "three", "four")
// longThing2: LongThing = LongThing("one", "two", "three", "four")
val longThing3 = LongThing("one", "two", "three", "four")
// longThing3: LongThing = LongThing("one", "two", "three", "four")
val longThing4 = LongThing("one", "two", "three", "four")
// longThing4: LongThing = LongThing("one", "two", "three", "four")
val longThing5 = LongThing("one", "two", "three", "four")
// longThing5: LongThing = LongThing("one", "two", "three", "four")

val myListOfThings =
  List(longThing1, longThing2, longThing3, longThing4, longThing5)
// myListOfThings: List[LongThing] = List(
//   LongThing("one", "two", "three", "four"),
//   LongThing("one", "two", "three", "four"),
//   LongThing("one", "two", "three", "four"),
//   LongThing("one", "two", "three", "four"),
//   LongThing("one", "two", "three", "four")
// )

myListOfThings.map(_.copy(c = "now I'm five"))
// res0: List[LongThing] = List(
//   LongThing("one", "two", "now I'm five", "four"),
//   LongThing("one", "two", "now I'm five", "four"),
//   LongThing("one", "two", "now I'm five", "four"),
//   LongThing("one", "two", "now I'm five", "four"),
//   LongThing("one", "two", "now I'm five", "four")
// )

All the evaluations are underneath the expression they belong to.

[olafurpg]

I vote for option B because I find it easier to skim over the code and see the evaluation when it's always formatted at the start of the line. Worksheets display the evaluation on a single line in the right-hand side because multi-line decorations make the code jump up and down, which can be distracting and annoying.

[svalaskevicius]

I don't have a strong opinion, but would be leaning towards more consistent for exporting.. (need to think of reasons why though, so maybe +0.1 for option b :D)

How would they be used? Blog posts?

[eloots]

Would be very useful for blog posts indeed.

[ckipp01]

Yea exactly, the could be for used for blog posts, posting questions, or just sharing evaluated output.

[arosien]

I have an alternative proposal: make mdoc a valid worksheet format! That is, evaluate the code snippets within scala mdoc fences. As @ckipp01 mentioned on twitter, worksheets are implemented in mdoc already.

I think this might be a better solution, since mdoc already is the definition of how to format output.

Then to integrate, you could have a trivial .worksheet.sc to .mdoc operation.

[ckipp01]

I'm not sure I fully see the use case you're referring to. From my experience most of the time someone is using a worksheet is to quickly demo something, explore an API, or maybe illustrate something. So they may want a quick way to export the evaluated worksheet. That would be the use case for this.

As you said, yes, the full evaluated worksheet is indeed coming back from mdoc, so mdoc would basically be providing all of this. Just on the Metals side we'd put it together for the user.

As for exporting to an mdoc fence, can you explain what the use case would be? Since these exports would already have the evaluations, so there would be no need to run mdoc on them.

[arosien]

I completely see where you are coming from: people have a worksheet and want to export the evaluation. I'm musing about exporting the worksheet to other formats.

In your examples above, the .worksheet.sc file would be evaluated and the output written as Scala code, suitable for inclusion in something like a fenced Scala block in markdown. That sounds fine.

As someone who writes lots of documentation with code, it's a common situation for me to take some Scala code, written in .scala or .worksheet.sc files, and embed (some of) it into some markup like markdown. I'd like to

1. prototype code in a worksheet;
2. export the worksheet to mdoc (just add a fence block);
3. add amazing words to the mdoc, and also customize the evaluation output via mdoc:silent, etc.; then
4. export/evaluate the mdoc to .md.

But that gave me the idea that I could have the IDE evaluation functionality of a .worksheet.sc file in an mdoc file directly. Then I could see the evaluation like a worksheet, but only have to perform steps 3 and 4.

[ckipp01]

🤔 I think I'm following. If I'm not mistaken the old mdoc LSP server that used to be part of mdoc would be perfect for this use case. Then you could just be writing in your markdown file, have an mdoc block and in real time get evaluations depending on the modifier and the block of Scala code. If I'm not mistaken I think it was just determined that having a browser open while having mdoc watch the files was basically just as fast.