Anthony Bullard (Jan 24 2025 at 00:52): Anthony Bullard (Jan 24 2025 at 00:52):Can I propose we move tutorial examples that are full programs out into their own code files and transclude them programatically?
Anthony Bullard (Jan 24 2025 at 00:55):It would:
roc check on them Sam Mohr (Jan 24 2025 at 00:56):I'm okay with it, it cleans up the code for now, and we'll be rewriting the tutorial in 6 months anyway
Luke Boswell (Jan 24 2025 at 00:57):Can we make them roc-lang/examples and then "import" them somehow?
Anthony Bullard (Jan 24 2025 at 01:05):They are pretty boring for roc-lang/examples
Luke Boswell (Jan 24 2025 at 01:06):We don't have to put them in the examples/ folder, maybe we make a tutorial_bits/ or something -- they won't be published to the website then, but we'll still catch them in CI and upgrades
Anthony Bullard (Jan 24 2025 at 01:11):We can extend the www roc program to transclude them
Anthony Bullard (Jan 24 2025 at 01:11):That part is easy
Anthony Bullard (Jan 24 2025 at 01:12):And we don’t need them in the examples on the website
Luke Boswell (Jan 24 2025 at 01:17):You're thinking about putting them in the roc-lang/examples right? we don't want to re-introduce an external dependency in roc-lang/roc
Anthony Bullard (Jan 24 2025 at 01:18):External?
Anthony Bullard (Jan 24 2025 at 01:18):No I was going to put it in a subfolder of www in roc-lang/roc
Luke Boswell (Jan 24 2025 at 01:18):We removed all the basic-cli and other platform examples out of roc because it complicates the breaking changes a lot
Sam Mohr (Jan 24 2025 at 01:18):I think Anthony is talking about stuff like:
add_and_stringify = \num1, num2 ->
sum = num1 + num2
if sum == 0 then
""
else
if sum < 0 then
"negative"
else
Num.toStr sum
Barely a file
Luke Boswell (Jan 24 2025 at 01:19):I guess that stuff is ok -- I'm concerned about anything with a header that references a URL platform release
Sam Mohr (Jan 24 2025 at 01:19):Agreed
Anthony Bullard (Jan 24 2025 at 01:20):I think we should have a placeholder platform that’s built with the release
Anthony Bullard (Jan 24 2025 at 01:20):I’m not as worried about running them
Anthony Bullard (Jan 24 2025 at 01:20):But I’m worried about being able to format and check them
Anthony Bullard (Jan 24 2025 at 01:21):And take about 1000 LOC out of the tutorial
Anthony Bullard (Jan 24 2025 at 01:21):I can leave that for after this release
Notification Bot (Jan 24 2025 at 01:22):22 messages were moved here from #compiler development > breaking changes by Luke Boswell.
Luke Boswell (Jan 24 2025 at 01:23):We've talked about moving the whole website out of roc-lang/roc... maybe we could revisit that discussion. I'm not sure where we got to with that.
But if we did, then that would resolve this problem I think.
Richard Feldman (Jan 24 2025 at 01:27):regarding /examples, I think we should treat that folder as essentially a public website
Richard Feldman (Jan 24 2025 at 01:28):because a common thing people do when visiting a repo is to go into the /examples folder and look at the examples in there
Anthony Bullard (Jan 24 2025 at 01:28):That’s why I don’t want to put these code snippets there
Richard Feldman (Jan 24 2025 at 01:28):so we should only put things it in there because we think they'll be good examples for newcomers to read
Luke Boswell (Jan 24 2025 at 01:28):I'm referring to roc-lang/examples/examples/ ... our roc-lang/roc/examples/ folder just contains a README pointing to the website.
Anthony Bullard (Jan 24 2025 at 01:29):I want to put them somewhere nested in www
Anthony Bullard (Jan 24 2025 at 01:29):And then just transclude them based on some kind of grepable comment string in the code block
Anthony Bullard (Jan 24 2025 at 01:42):As an example this block appears like 3 times:
```roc
app [main!] { pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.18.0/0APbwVN1_p1mJ96tXjaoiUCr8NBGamr8G8Ac_DrXR-o.tar.br" }
import pf.Stdout
import pf.Stdin
import pf.Arg exposing [Arg]
main! : List Arg => Result {} [Exit I32 Str]
main! = |_args|
Result.mapErr(my_function!({}), |err|
when err is
StdoutErr(_) -> Exit(1i32, "Error writing to stdout.")
StdinErr(_) -> Exit(2i32, "Error writing to stdin.")
EndOfFile -> Exit(3i32, "End of file reached.")
)
```
I'd like to replace it with
```roc
## TRANSCLUDE:/path/to/some/file_with_unique_name.roc
```
Or something like that
Richard Feldman (Jan 24 2025 at 01:42):that seems fine to me if they're just there for the website
Anthony Bullard (Jan 24 2025 at 01:43):Just the tutorial yes
Richard Feldman (Jan 24 2025 at 01:43):having it in a separate repo would make it annoying to coordinate updating the tutorial :sweat_smile:
Anthony Bullard (Jan 24 2025 at 01:43):Yes, in www/tutorial-snippets or something
Anthony Bullard (Jan 24 2025 at 01:43):And then we can have a shell script that can check them all with cargo run --bin roc -- check
Anthony Bullard (Jan 24 2025 at 01:43):And we could add that to CI eventually
Anthony Bullard (Jan 24 2025 at 01:45):Even could make sure they are formatted correctly
Anton (Jan 24 2025 at 09:16):We already have a transclude feature
Anton (Jan 24 2025 at 09:17): Anton (Jan 24 2025 at 09:17): Anthony Bullard (Jan 24 2025 at 11:36):I see something that looks like transclusion here, but I have no idea what is doing anything
Anthony Bullard (Jan 24 2025 at 11:36):Oh I see now, that happens in roc-lang/roc in the www build script
Anton (Jan 24 2025 at 12:26):The core functionality is in basic-ssg: https://github.com/lukewilliamboswell/basic-ssg/blob/de3b8ad535d1aaf767cce904e8994373d15ec088/crates/ssg/src/lib.rs#L323
Last updated: Jul 06 2025 at 12:14 UTC