The Joy Of Computational Markup

In The Joy of Using SECST Markup, I introduced SECST (Semantic, Computational, Styled, Tagged) markup, a more expressive alternative to- and partial superset of- Markdown. Although it does not cover in detail the Markdown compatibility of SECST, you may want to read it first to get a basic grasp of SECST syntax. In this article, I introduce the power of SECST computational markup.

Readers who know about Jupyter and Observable will be familiar with computational notebooks based on Markdown. These platforms are primarily focused on data professionals, and they are quite frankly awesome!

But, what if …

You are not a data professional and just want some math in your document and need to ensure the values for formulas are correct!
You are a teacher who needs to write a math tutorial.
You are a data scientist, but you sometimes need something lighter weight that does not require special hosting or a subscription.

Then, you may get joy from SECST's computational capabilities.

Basic Computations

At their most basic level, SECST computations are no more complex than simple Excel formulas.

:value[2 * 2] will render as 4

The result will have code styling (usually in monospace font with a grey background) to indicate to readers the value is computed. However, you can provide plaintext as an option, e.g.

:value(plaintext)[2 * 2] will render as 4.

SECST also has the full expressive power of Excel and more when it comes to math formulas. Here are all the types of computations available:

Algebraic
Arithmetic
Bitwise
Combinatorics
Complex
Geometry
Logical
Matrix
Probability
Relational
Set
Special
Statistics
String
Trigonometry
Unit
Utility

To be fair, this is just because SECST makes use of the MathJS library. But, SECST authors do not need to worry about how to include the functionality. It is just there, so things like this are possible:

:value(plaintext)[derivative('x^2 + x', 'x')] renders as 2 * x + 1.
:value(plaintext)[simplify('x^2 + x + 3 + x^2')] renders as 2 * x ^ 2 + x + 3.
:value(plaintext)[solve('Math.pow(r,2)',{r:3})}] renders as 9.
:value(plaintext)[multiply([[1,2],[3,4]],[[5,6],[1,1]])] renders as [[7,8],[19,22]].

Unit conversions like this are also possible:

:value[2 inch to cm] = 5.08 cm
:value[90 km/h to mi/h] = 55.92340730136006 mi / h
:value[90 km/h to m/h] = 9000 m / h m / h is meters per hour
:value[(1 week + 1 day) to days] = 8 days
:value[cos(45 deg)] = 0.7071067811865476
:value[8.314 m^3 Pa / mol / K] = 8.314 (m^3 Pa) / (mol K)

Advanced Computations

You can name values so they can be used in other value expressions. And, it is possible to have readers edit content for use in formulas.

Here is an example that covers both cases:

The derivative of :value(#formula literal editable)[x^2 + x]
for :value(#variable literal editable)[x]
is :value[derivative($(#formula),$(#variable))]

will render as:

The derivative of [ x^2 + x ] for [ x ] is 2 * x + 1

Unless the user modifies the formula to be x^3 + x, in which case the result will be 3 * x^2 + 1.

This is obviously a bit more complex than the unit conversion, so here is the explanation …

Value tags provide the user with an edit box when configured as editable.
Values can be named using #ids. Above we name the formula to be entered #formula and the variable to solve for #variable.
By default, the content between the square braces for a :value[] tag is considered to be an expression that can be evaluated. So, in the above, SECST is instructed to treat the content as a literal.
Finally, named variables can be accessed in :value expressions using the syntax $(#<variable-name>). Hence, the final step above is to evaluate derivative using the formula and variable entered by the reader.

Interactive Questions

SECST even has the ability to render questions and check answers.

:question({type:"number",showanswer:true})[
  :text[What is the :code[sqrt(4)]?]
  :answer[2]
]

will render as

What is the sqrt(4)? [ ____ ] ✓

If the user enters the wrong answer, the question will be boxed in red and the correct answer will be shown because the attribute showanswer is set to true.

What is the sqrt(4)? [ 3 ] ✓ Correct Answer: 2

If you are a teacher, I am sure at some point you have provided the wrong answer in a tutorial. SECST can help avoid this. The :answer tag can take an expression just like the :value tag. Replace the above question with:

:question({type:"number",showanswer:true})[
  :text[What is the :code[sqrt(4)]?]
  :answer[sqrt(4)]
]

More Info

Not yet available, but just days away, are REPLs. See the article, How To Host A REPL for a preview. I will post a SECST-specific story when it is ready.

The SECST language and transpiler are currently in ALPHA under an AGPL v3.0 license.

There is more to explore at https://secst.org.

Be joyful! Make yesterday jealous!

I would love your feedback here or on GitHub.

Featured Photo by Bekka Mongeau on Pexels