freeform mix of code and markdown

[CeylonMigrationBot]

[@gavinking] So I like this. I think it would be a very nice way to produce module and package documentation, and even blog posts. I love the idea of being able to write a file that mixes markdown and code, and both run the code and produce ceylondoc from it.

But how could we do it? Problems:

• Annotations annotate declarations, not arbitrary fragments of code. We could use comment blocks, but that seems pretty inconsistent.
• Fragments of code must belong to a method or class, we've never solved the "scripting" problem.

[Migrated from ceylon/ceylon-spec#564]

[CeylonMigrationBot]

[@gavinking] Well, I suppose both problems would be solved by the "scripting" syntax I've mooted before:

doc "Print a message to the console." 
void {
    print("hello");
}

But somehow I don't feel like that's as nice as it could be...

[CeylonMigrationBot]

[@jdpatterson] You have mentioned before the possibility of a white-space aware pre-processor in a discussion about using indentation rather than braces to delimit blocks. Could such a pre-processor be used here to handle scripting as well? It could use indentation level to decide if an input line was a comment (indent 0) or code (indent > 0) and output doc annotations and default class boiler plate.

On 28/01/2013, at 11:19 AM, Gavin King wrote:

Well, I suppose both problems would be solved by the "scripting" syntax I've mooted before:

doc "Print a message to the console." void { print("hello"); } But somehow I don't feel like that's as nice as it could be...

— Reply to this email directly or view it on GitHub.

[CeylonMigrationBot]

[@gavinking]

Could such a pre-processor be used here to handle scripting as well? It could use indentation level to decide if an input line was a comment (indent 0) or code (indent > 0) and output doc annotations and default class boiler plate.

Yes, it's an option, it would work. But I would prefer to have some sort of support as part of the native syntax of the language. Then it's even easier to layer a whitespace-aware preprocessor over the top of that.

[CeylonMigrationBot]

[@gavinking] So I've been thinking about it, and since this is a toplevel only construct, we could make it look as simple as:

"Print a message to the console:" 
{
    print("hello");
}

"Do something else:"
{
    doSomething();
    doSomethingMore();
}

But ... is this syntax actually appealing?

[CeylonMigrationBot]

[@gavinking] Proof that this concept has legs:

http://css.dzone.com/articles/literate-coffeescript

I personally find this stuff very appealing.

[CeylonMigrationBot]

[@simonthum] As an Org-mode user I like to view the problem the other way round, i.e. how to embed and link (tangle) snippets in different computing languages in prose.

http://orgmode.org/worg/org-contrib/babel/intro.html

While I probably would appreciate a babel-ceylon one day that does not mean it could profit from language-level features. As appealing as it is, solving the problem from the outside e.g. with an opt-in pre-processor might be preferable.

BTW the coffeescriptionados seem to go that route - only .litcoffee scripts are literate.

[CeylonMigrationBot]

[@ghost] +1 for the idea. But I'd say the only way to make this appealing is to actually do it as .litcoffee does (e.g. allow .litceylon or something). On the other hand ceylons doc annotation syntax is already as compact as can be (since you can even leave the 'doc'). It might make sense though to highlight the doc string in a special way in the IDE, so that it looks (almost) like literate programming.

Ah one thing: You could consider allowing annotations on anything using the doc syntax. I mean statements, expressions and all.

Also, I know it feels clean that doc is an annotation, but documentation has a significance that might justify exceptions from the rule.

[CeylonMigrationBot]

[@gavinking] Relates to #3306, of course.