{"action":"created","issue":{"url":"https://api.github.com/repos/tpolecat/tut/issues/69","labels_url":"https://api.github.com/repos/tpolecat/tut/issues/69/labels{/name}","comments_url":"https://api.github.com/repos/tpolecat/tut/issues/69/comments","events_url":"https://api.github.com/repos/tpolecat/tut/issues/69/events","html_url":"https://github.com/tpolecat/tut/issues/69","id":108883977,"number":69,"title":"Literate programming versus REPL-based tutorials","user":{"login":"non","id":218045,"avatar_url":"https://avatars.githubusercontent.com/u/218045?v=3","gravatar_id":"","url":"https://api.github.com/users/non","html_url":"https://github.com/non","followers_url":"https://api.github.com/users/non/followers","following_url":"https://api.github.com/users/non/following{/other_user}","gists_url":"https://api.github.com/users/non/gists{/gist_id}","starred_url":"https://api.github.com/users/non/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/non/subscriptions","organizations_url":"https://api.github.com/users/non/orgs","repos_url":"https://api.github.com/users/non/repos","events_url":"https://api.github.com/users/non/events{/privacy}","received_events_url":"https://api.github.com/users/non/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":1,"created_at":"2015-09-29T14:38:29Z","updated_at":"2015-09-29T14:42:59Z","closed_at":null,"body":"I feel like I've heard people ask whether Tut can support literate programming in Scala. And when I try to explain my (perennially-unreleased) sbt-plugin for literate programming (https://github.com/non/literati), people always say \"Oh, like Tut right?\"\r\n\r\nIt might be nice for me to try to fold my work into Tut (which people have heard about and seems to be getting some momentum) rather than having a totally separate plugin for something that seems very similar (at least on the surface).\r\n\r\nThe main difference between the two comes down to how the compiler is used.\r\n\r\nTut (AFAIK) wants to paste code into one (or more) REPL sessions to ensure that when a reader opens a REPL, the code examples all work as advertised (at least, with the right classpath). It also wants to (potentially) rewrite your Markdown to show the REPL output you'd expect to see.\r\n\r\nLiterati wants to transform your markdown file into a Scala file (whose line numbers match), and then run the standard compiler on that, producing bytecode, jars, and so on via *managed_src*. This ends up looking a lot like codegen. It doesn't transform the Markdown in any way, since the assumption is that the code is compiled, not run.\r\n\r\nI could imagine using a Markdown header, like Jekyll does, to \"configure\" Tut's behavior. This would be the current (default) behavior:\r\n\r\n```markdown\r\n---\r\nmode: repl\r\n---\r\n```\r\n\r\nand this might be a configuration for literate programming:\r\n\r\n```markdown\r\n---\r\nmode: compile\r\npackage: my.example.project\r\n---\r\n```\r\n\r\n(Other optional settings might include `object: TopLevelObject` or `app: TopLevelApp`, to optionally wrap the code in an object (or an object extending `App`).)\r\n\r\nThe nice thing is that we have one tool to do *Markdown-related* Scala programming. The downside is that these two modes will share almost no code -- their strategies are orthogonal.\r\n\r\nWhat do you think?"},"comment":{"url":"https://api.github.com/repos/tpolecat/tut/issues/comments/144081902","html_url":"https://github.com/tpolecat/tut/issues/69#issuecomment-144081902","issue_url":"https://api.github.com/repos/tpolecat/tut/issues/69","id":144081902,"user":{"login":"non","id":218045,"avatar_url":"https://avatars.githubusercontent.com/u/218045?v=3","gravatar_id":"","url":"https://api.github.com/users/non","html_url":"https://github.com/non","followers_url":"https://api.github.com/users/non/followers","following_url":"https://api.github.com/users/non/following{/other_user}","gists_url":"https://api.github.com/users/non/gists{/gist_id}","starred_url":"https://api.github.com/users/non/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/non/subscriptions","organizations_url":"https://api.github.com/users/non/orgs","repos_url":"https://api.github.com/users/non/repos","events_url":"https://api.github.com/users/non/events{/privacy}","received_events_url":"https://api.github.com/users/non/received_events","type":"User","site_admin":false},"created_at":"2015-09-29T14:42:59Z","updated_at":"2015-09-29T14:42:59Z","body":"One other argument against is that you'd probably want to put the \"tut\" files and the \"literate\" files in two different locations, to be clear on their different semantics. This might also mean that you don't need a `mode` parameter."}}