Plans for Camus 2

Camus is a document markup language I designed for my own use. The first version is completed in December 2021 and I've been using it for my blog ever since.

Update 2022.11.28: new underline, highlight, superscript, subscript and footnote ref grammars are now implemented in version 0.4.0; also, it turns out Camus 1 already has anchor tag that also works in headings (e.g. {#anchor-name}) but the grammar conflicts with global state flags...

Changes of syntax in Camus 2

Advanced headers

The header of a blogpost is just as important as the content; there are times I would like a more sophisticated header. It's easy to make any kind of header you want when you're writing raw HTML; not so much if you're restricted to a markup language. I decided to add the following new header constructs to Camus 2:

=^ Top title: for series names & alike
=  Main title: for the main article title
=_ Bottom title: for sub-titles

e.g.:

=^ History of Cantonia, Part 6
=  Cantonia Clique & The First Independent Cantonia Provincal Government
=_ ...and the feud between Can Gwingming and Sun Yat-sen

Consequtive lines of level 1 headers arranged in such a fashion should be converted into one sigle <h1> element, e.g. something like this:

<h1>
    <div class="header top-title">History of Cantonia, Part 6</div>
    <div class="header main-title">Cantonia Clique & The First Independent Cantonia Provincal Government</div>
    <div class="header subtitle">...and the feud between Can Gwingming and Sun Yat-sen</div>
</h1>

I'm not sure if it would be useful for other levels of header to have this feature but it's probably better to implement it anyway.

New reference semantics & anchors

In Camus 1 the interpretation of reference tags are up to the backends; now I would like to properly define its semantics. In Camus 2, reference tags:

Anchor is used to mark positions within documents; its syntax is {anchor:anchor-name}. When an anchor is referenced, its name is appended after the file name, separated with a hash symbol #.

Namespace-qualified references

This is for those who wants to write more than one kind of thing with Camus, e.g. blog post and wiki; with this kind of references one can refer to their wiki with something like {wiki/ref:ecosystem-straightjacket} and their blog something like {blog/ref:my-painful-ride-with-a-clean-code-codebase}. How to interpret namespaces and the reference path under the namespaces are up to the backends.

A reserved namespace is extern, used for referring external (normally not on the local disk) Camus documents.

Metadata block

Blocks with the type metadata denotes a metadata block; the content within is used to control camus-cli's behavior and normally won't be combined as part of the generated output. The content of metadata blocks are key-value pairs with each line containing one such pair. The key and the value are separated by a single colon :, for example:

#{metadata
    title: I tried to implement Algorithm W
    tags: language,plt,type-system,type-checking
    first-version: 2022.11.23
    last-update: 2023.1.2
#}

Multiple-reference footnote

Currently footnotes in Camus 1 only supports one reference at a time. In Camus 2 it would be possible to write something like {footnote@1,3} or {footnote@1,SomeReference2}.

Superscript & subscript

I don't remember if I've implemented superscript & subscript in Camus 1 but I'm definitely adding them in Camus 2. The grammar would be like the one in LaTeX: ` starts a superscript and ` starts a subscript. To put multiple characters in a superscript/subscript they have to be enclosed in braces.

Underline & highlighting

The subscript grammar above conflicts with the underline one in Camus 1; the underline grammar in Camus 2 is thus adjusted to be enclosed within double underscore __ ... __.

Inspired by Djot: https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/master/doc/syntax.html#highlighted

Highlighted texts are enclosed within {= ... =}. These corresponds to the <mark> tag in HTML.

One could also force underlines & highlights to generate the same code through configurations in metadata or global state flags (described below) because they are kinda similar in terms of actual functionality.

Global state flags

Global state flag commands are used to control the backend's behavior when generating output. The syntax is {#flag-name=flag-value#}. The supported flag names are listed as follows:

One can set multiple global state flags inside one command, separated with ;. e.g. {#ordered-list-style=number,right-paren;marking-style=underline-only;smart-punctuation=enabled#}:

Global state flags do nothing except changing flags; they do not show up as content in the output. But they have to follow the indent rules. e.g.:

+ This list item starts an indent block with 2 spaces.
  
  This line is still within the list item because it's within the 2-space indent block.
  {#smart-punctuation=enabled#}
  The GSF above does not break the indent block, and thus this line is still inside the list item.
{#smart-punctuation=disabled#}
  This line is not inside the list item because the GSF above does not have the required indent (and thus ending the list item above).

Global state flags also "takes" one newline character before and after them (if such newlines exist), thus the following examples are essentially the same:

abcdefg...{#smart-punctuation=disabled#}...hijklmn

abcdefg...{#smart-punctuation=disabled#}
...hijklmn

abcdefg...
{#smart-punctuation=disabled#}...hijklmn

abcdefg...
{#smart-punctuation=disabled#}
...hijklmn

They all produces abcdefg......hijklmn; but this example won't:

abcdefg...

{#smart-punctuation=disabled#}

...hijklmn

This will produce abcdefg...[empty line]...hijklmn

New features for camus-cli

Support for long content

Smart punctuation

When enabled:

LaTeX backend

Yes.

The "competitor" I had in mind when I started this project in 2016 was emacs org-mode because Markdown was too primitive and HTML-centric for me.

Raw HTML & LaTeX

Supports inserting raw HTML/LaTeX inside a Camus 2 document. Raw HTML blocks will not do anything when the LaTeX backend is used, and vice versa.

#{=html
    <h1>Directly write HTML here</h1>
#}

#{=latex
    \textit{Directly use LaTeX here}
#}

Built-in syntax highlight engine (!)

I had enough of being forced to use GNU source-highlight through cygwin console. I was also planning to write a lexer & parser generator so this would be fitting.

Custom indexes

Combining with metadata one can freely create new indexes for any subset of documents that has a common or related theme: tags, categories, series, etc. (and custom RSS feed as well so viewers can "subscribe" to a specific topic or series).

Things that I will NOT add in Camus 2 and all future versions