The Joy of Using SECST Markup

Semantic, Extensible, Computational, Tagged (SECST) markup provides a new way to rapidly create technical guides, training materials, and other interactive documents with far more expressive power than Markdown and less complexity than HTML. No jumping through hoops, no drudgery, just joy!

Why Another Markup Language

Markdown is a well established means of rapidly creating documents with a moderate amount of formatting for web delivery. Over the years (it was first created in 2004), more and more features have been added to the language. However, due to its non-uniform approach to formatting instructions, it is reaching the limits of possibility for expressive power without resorting to inline HTML. HTML is verbose and makes documents hard to read in raw form.

And, neither Markdown or HTML have intrinsic navigational support for large documents. Yet, conventional word processors such and MS Word and Google Docs that provide the expressive power authors often seek, fail to produce portable and accessible web content.

Additionally, platforms like Jupyter, which meets the needs of many data scientists, are ultimately hamstrung by the limits of Markdown while also requiring special hosting.

SECST provides an alternative consistent markup syntax making it easy to use, learn and remember while also supporting:

• attribute based configuration of tags,
• automatic table of contents generation, navigation link generation, and footnote numbering,
• built in computation capability, e.g. :value[2 + 2] = 4or even :value[derivative('x²+x','x')] = 2 * x + 1 ,
• Static or dynamic data import for use in computations,
• JSON-LD for content generation as well as SEO,
• Static media embedding for images, audio, and video,
• easy extensibility, new tags to support things like LaTeX, ABC music notation, and even REPL’s based on third party libraries can be added in minutes.

In this article, we focus on just the simple, easy to learn, easy to remember aspects of SECST.

When To Use SECST

If you only need basic Markdown, then SECST is probably not for you.

If you need extended Markdown, then SECST may be a good option.

If you are writing a long document or need more than Markdown, then SECST may be your only option short of HTML, CSS, and JavaScript.

Simple, Easy to Learn, Easy to Remember

Here is the code for Markdown bold and italic.

**bold text**
*italic text*

Here is the SECST code for the same result.

:b[bold text]
:i[italic text]

You can also use full words, which is a little easier to remember.

:bold[bold text]
:italic[italic text]

But, we recommend the below because it is semantic. It drives the consistent use of bold and italic to convey meaning and is useful for assistive technologies.

:strong[important text]
:em[emphasized text]

SECST has a tag equivalent for almost every semantic HTML tag, i.e. tags that have meaning beyond layout and formatting, e.g. <div>is not semantic but <p> is semantic. This has the following advantages:

• Far more can be expressed in a SECST document than a Markdown without resorting to HTML, e.g. direct support for [:kbd[]], [:del[]], and [:ins[]].
• Existing documentation about HTML can be used to understand SECST.
• CSS style sheets can be effectively applied to output documents.
• Output documents support assistive and automated analysis technologies.

SECST also supports a few common non-semantic tags, e.g. :bold[] and :italic[], to make it easier to learn.

SECST is not quite as terse as Markdown, but it is far more terse and easier to read than HTML. It also has some Markdown like shortcuts.

Here is the Markdown for an ordered list starting with 2.

2. item two
2. item three
2. item four

Or,

2. item two
3. item three
4. item four

Here is the same list in SECST.

:ol[
  2. item two
  - item three
  - item four
]

You may note there is a subtle advantage in the SECST tagging. In Markdown you either have to repeat the starting number (which looks odd in a source document) or number items properly yourself. With SECST, you only have to provide a number to the first line.

Additionally, in a Markdown document it is not straightforward to have a series of lines starting with a dash or number. With SECST, you simply do not wrap them with :ol[] or :ul[] .

And, when you reach the point where you need complex content inside a list item you can use or mix and match :li[].

:ol[
  :li[item one]
  - item two
  - item three
]

SECST also supports alternative numbering.

:ol({type:"a"}) [
  - item one
  - item two
  - item three
]

a. item one

b. item two

c. item three

In the last example, the use of attributes was introduced. These are entirely optional and are provided in the form of a JSON object inside parentheses before the square braces. Almost every attribute available to an underlying HTML tag is available. However, this topic and more are for future articles.

If you would like more insight now, check out the ALPHA documentation at https://sects.org.

We would love to get your feedback either here or on GitHub.

Featured Photo by Taylor Heery on Unsplash.