computable-pandoc/man/locales/en.md

Test 1

With Literate Pandoc you can write code as you write everything else! For example, this is a function declaration: f() = (+ 1 2 3).

Every function declaration has:

1. A function name consisting in:
   1. One or more alphanumeric characters following by a opening parenthesis (i.e. %w+().
   2. Optional arguments (args).
   3. Closing parenthesis ()).
2. A function assignment indicated with the equal sign (=).
3. A function body composed by Lisp code between parentheses.

Any function can be called at any time by is function name, for example now we call f()! This also apply for function that haven't been defined, like foo(1).

The functions can contain args, for example:

• foo(n) = (* #n #n) is a function declaration with the arg n; any arg can be used in the function body if it is prefixed with a hashtag (#n).
• They can contain more args like bar(a, b) = (- a b).
• For a variable number of args the ... symbol is used: baz(...) = (.. #...). You can call baz() or baz('hello', ' ', 'world!').

All args can be treated as keyword args (kwargs), so foo(3) can be foo(n: 3), or bar(2, 1) can be bar(b: 1, a: 2).

With kwargs you can declare args in any order and makes args more readable. The trade-off is that they are verbose. Also, ... arg can't be use as kwarg!

Calling f(), foo(2), bar(4, 3), baz(':', ')') will evaluate the functions and will print the output during Pandoc conversion, but, what if we want to...

1. ...write the evaluation result instead of the function call? For example, see 6 instead of f(), or :) instead of baz(':', ')').
2. ...remove the function call? So you don't see f() anymore.
3. ...avoid evaluation?
4. ...write the evaluation result to a file?
5. ...write the evaluated code to a file?
6. ...write Lisp code as Lua code to a file?

Well, we can do that with reserved kwargs. All reserved kwargs are optional (you don't declare them) and start with underscore (_):

• _action: indicates action to perfom with the function call; can be:
  • 'flip': puts its evaluation result instead;
  • 'wipe': deletes it from source document but still calls it;
  • 'skip': doesn't perform call;
  • 'kill': doesn't perform call and deletes it from source.
• _eval: saves evaluation to file; takes file path string as value.
• _code: saves code to file; takes file path string as value.
• _lua: converts Lisp code to Lua and saves it to file; takes file path string as value.

With reserved kwargs, we can finally replace f() by its evaluation result like this: f(_action: 'flip'); or skip its evaluation: f(_action: 'skip').

We can also save different files:

• The avaluation results of foo(4, _eval: 'results.txt') and bar(5, 4, _eval: 'results.txt').
• The code of foo(4, _code: 'code.lisp') and bar(5, 4, _code: 'code.lisp').
• The Lua code of foo(4, _lua: 'code.lua') and bar (5, 4, _lua: 'code.lua').