-
Notifications
You must be signed in to change notification settings - Fork 15
A brief introduction
Use markdown. Each heading is a new heading block (hblock) and can be referenced by using _"title". This substitution has more features, documented below.
Within each hBlock, one can write free form markdown explanatory text, directives, code lines, or initiate a new code block (cblock).
- hblock is initiated by number signs at the beginning of a line. seText style works too. See markdown syntax.
- Directive is initiated by a markdown link syntax with "dir:..." as part of the title.
- A new cblock is initiated with a non-directive link at the beginning of a line.
- cblock lines are recognized by 4 spaces (not tabs).
To reference a cblock, the full precise name, a cblock name, is "litprodoc :: hblock : cblock.ext" where all but hblock is optional. Also hblock.ext grabs the unnamed extension relevant to it.
To use a cblock, use the substitution command _"cblock name | commands ..." where commands can do stuff on the code text and each pipes into the next.
Examples: _"Great:jack|marked", _"Great:.md" or "Great.md", _"Great|marked", _"Great:jack.md", ":jack" will load the internal block named jack
The save directive is used to save a file: [file.ext](#heading-name "save: cblock | commands")
If the heading name is missing, it uses the current hblock.
- Setup an hblock as a body of code, such as a function. Use multiple cblocks to break that body into manageable chunks. Use new hblocks for new functions or for very important behavior.
- Write function blocks without ending (semicolon, comma) punctuation so that they can be inserted in multiple ways. Put the punctuation after the substitution quote.
- Use this for getting a good overview of flow control. Strip out the complicated, but easily identifiable chunks and focus on how the code flows.
You can run JavaScript code while compiling in at least two ways. One is, within a cblock, use _`some code` on a single line. The other way is to have a cblock and reference it with a pipe command that evals it, such as the eval command.
The eval output (last evaluated value) is what is placed in the code to replace the backtick call.
There may be need to run substitutions after a first pass or more. For example, markdown segments could have snippets that need to be inserted after the markdown parser has run. See logs.md for an example.