Code Block References and Titles #1
Description
The Problem
Currently, if you want to have a code block, you can do something like this:
<<Count to Ten>>=
for (int i = 0; i < 10; i++) {
System.out.println("Number " + i);
}
@
Here we count to the number 10, which incidentally is humanity's most beloved number.
<<*>>=
public static void main(String[] args) {
<<Count to Ten>>
}
In this case we can see "Count to Ten" is both the name of the code block (to reference later in the main code block as a sort of "include") and the title of that code block when rendered as documentation (e.g. the heading in markdown). In a recent commit, I made it so the names of the code blocks render in Title Case, but that may be too prescriptive. I started to think that the code block name is a bit overloaded - it's trying to do too much at once. Even in addition to being the way of referencing the block and outputting the title, the code block name is used to specify the type of code for style formatting (e.g. by using language-literate in Atom) . To modify the above example, really someone would do something like this:
<<java: Count to Ten>>=
for (int i = 0; i < 10; i++) {
System.out.println("Number " + i);
}
@
Here we count to the number 10, which incidentally is humanity's most beloved number.
<<java: Example.java>>=
public static void main(String[] args) {
<<java: Count to Ten>>
}
Now we are making it hard to have the default, root code block to just be named *, because we want it to also to be styled as Java in our code editors. Maybe that's OK, but now the references to those code blocks are increasingly unwieldy: now you not only have to know the title of the code block, but you also need to know whether it has the formatting prefix and what that prefix is before you can reference the code block, so you essentially have to look up the code block name each time as opposed to being able to guess and autofill the codeblock name like you may with a variable.
Additionally, the parser, to accommodate the language tagging in the code block name, needs to know to look for possible tags like java: and exclude them from the title when rendering the documentation. This is making me think that too much is going on with the code block name, and it makes writing literate code more difficult.
Possible Solutions
The aim of this issue is to attempt to address this problem. My primary solution right now is to introduce alternative syntax on top of the existing syntax for the code block name that would let you establish a code block internal name (e.g. something short and memorable, like a variable name) as separate from the code block's external name (e.g. for documentation headlines). Using the above example, perhaps it could look like this:
<<java: countToTen | Count to Ten>>=
for (int i = 0; i < 10; i++) {
System.out.println("Number " + i);
}
@
Here we count to the number 10, which incidentally is humanity's most beloved number.
<<java: * | Example.java>>=
public static void main(String[] args) {
<<countToTen>>
}
In the above example, we still have the language tag (java: ), but now we have the code block name in two parts: an internal "variable" name that is a unique identifier for that code block (e.g. countToTen), and the intended title for the documentation (e.g. Count to Ten). Notice that the intention is that we could go back to using the * as the root name by using it as the internal name, so part of solving this issue will include excluding the possible language tags / prefixes (like java: ) from the code block name when you reference it within the lesen file, and also when you use the command line interface. I should also clarify that the intention is that the internal name is the de facto code block name except for the documentation side of things; so, when you reference the code block via the command line interface, you would use the internal code block name.
Potential problems of course include the possibility that | is a desired part of the documentation title, so we may need a better way of specifying the headline in addition to the internal code block name.