{"action":"created","issue":{"url":"https://api.github.com/repos/MichaelHatherly/Documenter.jl/issues/37","repository_url":"https://api.github.com/repos/MichaelHatherly/Documenter.jl","labels_url":"https://api.github.com/repos/MichaelHatherly/Documenter.jl/issues/37/labels{/name}","comments_url":"https://api.github.com/repos/MichaelHatherly/Documenter.jl/issues/37/comments","events_url":"https://api.github.com/repos/MichaelHatherly/Documenter.jl/issues/37/events","html_url":"https://github.com/MichaelHatherly/Documenter.jl/issues/37","id":147783140,"number":37,"title":"Writing a user guide (or how to include benchmarks)","user":{"login":"lbenet","id":5237744,"avatar_url":"https://avatars.githubusercontent.com/u/5237744?v=3","gravatar_id":"","url":"https://api.github.com/users/lbenet","html_url":"https://github.com/lbenet","followers_url":"https://api.github.com/users/lbenet/followers","following_url":"https://api.github.com/users/lbenet/following{/other_user}","gists_url":"https://api.github.com/users/lbenet/gists{/gist_id}","starred_url":"https://api.github.com/users/lbenet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lbenet/subscriptions","organizations_url":"https://api.github.com/users/lbenet/orgs","repos_url":"https://api.github.com/users/lbenet/repos","events_url":"https://api.github.com/users/lbenet/events{/privacy}","received_events_url":"https://api.github.com/users/lbenet/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":1,"created_at":"2016-04-12T15:13:21Z","updated_at":"2016-04-12T15:48:48Z","closed_at":null,"body":"I've been playing a little bit with `Documenter.jl`, and like it a lot. In particular I like the possibility of injecting results through `{example}` as well as using DocTests in script and REPL mode. \r\n\r\nFor a user guide, I like the idea of illustrating how to use the package with code in a REPL-like session, which separates clearly what you type from what you get; then, using the REPL (or script) blocks seems the way to go, which implies DocTests (unless you disable them completely, which is what I'm currently doing). Yet, DocTests are inconvenient for benchmarks (using `@time ...`) because of the intrinsic time variations; the way to go seems to be with `{example}`, which does not insert the julia prompt \"julia> \" to clearly separate the input from the output. This is clearly circular.\r\n\r\nSo, I suggest to have the functionality of `{example}` with the possibility of inserting the \"julia> \" prompt after parsing. I guess the easy way to go is to introduce the block `{example-repl}` which executes the code and provides \"julia> \" for the input. Another possibility, following #5 (which I like a lot), is to have something like\r\n```\r\n    ```julia-repl-example\r\n        @time whatever()\r\n    ```\r\n```\r\n\r\nIncidentally, the keyword `julia-repl` could be used to only type julia code (without explicitly using \"julia> \"), but getting it once the file is parsed."},"comment":{"url":"https://api.github.com/repos/MichaelHatherly/Documenter.jl/issues/comments/208972404","html_url":"https://github.com/MichaelHatherly/Documenter.jl/issues/37#issuecomment-208972404","issue_url":"https://api.github.com/repos/MichaelHatherly/Documenter.jl/issues/37","id":208972404,"user":{"login":"MichaelHatherly","id":6144086,"avatar_url":"https://avatars.githubusercontent.com/u/6144086?v=3","gravatar_id":"","url":"https://api.github.com/users/MichaelHatherly","html_url":"https://github.com/MichaelHatherly","followers_url":"https://api.github.com/users/MichaelHatherly/followers","following_url":"https://api.github.com/users/MichaelHatherly/following{/other_user}","gists_url":"https://api.github.com/users/MichaelHatherly/gists{/gist_id}","starred_url":"https://api.github.com/users/MichaelHatherly/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/MichaelHatherly/subscriptions","organizations_url":"https://api.github.com/users/MichaelHatherly/orgs","repos_url":"https://api.github.com/users/MichaelHatherly/repos","events_url":"https://api.github.com/users/MichaelHatherly/events{/privacy}","received_events_url":"https://api.github.com/users/MichaelHatherly/received_events","type":"User","site_admin":false},"created_at":"2016-04-12T15:48:48Z","updated_at":"2016-04-12T15:48:48Z","body":"> So, I suggest to have the functionality of `{example}` with the possibility of inserting the `\"julia> \"` prompt after parsing.\r\n\r\nYes, sounds like a good addition.\r\n\r\nThe implicit meaning of the `{...}` syntax is that it denotes generated content, whereas doctest blocks only compare results without creating anything new. Following that approach would indeed lead to implementing this with a `{example-repl}`, or perhaps just `{repl}`, rather than as a `.language` name.\r\n\r\n(Switching over to #5 is *possible*, but at this point there's already quite a lot of code out there using the current syntax, so I'm not sure whether changing would be all that beneficial.)\r\n\r\nRegarding some more specific concerns about a possible `{repl}` syntax:\r\n\r\n- Would `julia> ` be added infront of every toplevel expression, or would it be possible to group several like you can do with `alt-return` in the real REPL?\r\n- Semi-colons would presumably hide output as usual?\r\n"}}