Change #' to simply # and require ## for julia comments

[fredrikekre]

As discussed in https://discourse.julialang.org/t/ann-literate-jl/10651/9, using #' could be annoying, and julia comments are probably not as frequent as markdown input.

[Datseris]

Sounds like a good plan!

[KristofferC]

Agree that #' is a bit annoying. I think the # and ## would probably work well.

[piever]

I also think it'd be better! Writing markdown spanning multiple lines is probably much more common in these kind of files and it's good to be able to use the editor shortcut for that.

[aalexandersson]

The user-written Stata command markstat uses the simple "one tab or four spaces" rule to distinguish Stata and Markdown which works well. Stata code blocks are defined similar to Github code blocks like this

```s
  // Stata code goes here
```

I prefer a similar solution where I would not have to type a character such as # to get Markdown in Julia. Perhaps like the Stata approach above but with j or instead of s as an optional language identifier for Julia.

Caveat (in case it is not obvious): I do not know Julia at all, just starting to learn as prep for Julia 1.0.

[tshort]

How about including the multi-line comment field, too? It'd be even easier to include/format markdown there.

#=
# heading

Some *text*...
=#

Another option is to include something in the leading indicator like #=md.

[fredrikekre]

How about including the multi-line comment field, too?

I am not a big fan of multiline comments personally, It breaks syntax highlighting in some editors, complicates the quite minimal current syntax, and makes parsing of the source file more complicated. I think going with #4 is good enough, which should make it much simpler to comment-toggle the markdown lines, if you prefer to edit them without the leading # , and then toggle back.

[JeffreySarnoff]

Multiline comments provided limited literacy before it was fashionable. I still use them when, six months hence, l need to remember a subtle something.
Would there be a way to adapt Julia's block delimiters and use ##= .. #=# without requiring mensurable effort.

Either way, I am appreciative of the work. Maybe now, I can provide the sort of microtutorial others will utilize. Thank you.

[waldyrious]

Related to @aalexandersson's point above, and just for reference (I'm not convinced this would be preferable to # v.s ##), back in 2013 I filled jashkenas/docco#216, which suggests omitting the space after the comment marker to distinguish intentional documentation from (temporarily?) commented-out code. Thought I'd mention that option here, for completeness.