# 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

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:

• only links to (1) a Camus document or (2) an anchor inside a Camus document.
• should not require the .cm extension for file names. e.g. {ref:some_other_file} should refer to some_other_file.cm, while {ref:some_other_file.cm3} should refer to some_other_file.cm.cm.

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.

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 __ ... __.

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:

• smart-punctuation:
• enabled: from this point on, enable smart punctuation.
• disabled: from this point on, disable smart punctuation.
• ordered-list-style: the next complete ordered list will have the specified bullet style. The value for this flag consists of two parts: the numbering and the punctuation. The two parts are separated by a single comma ,.

For the numbering:

• number: all the bullets use numbers, e.g. 1., 2., 3.
• lower-alpha: all the bullets use lowercase alphabets, e.g. a., b., c.
• upper-alpha: all the bullets use uppercase alphabets, e.g. A., B., C.
• lower-roman: all the bullets use lowercase roman numerals, e.g. i., ii., iii., iv.
• upper-roman: all the bullets use uppercase roman numerals, e.g. I., II., III., IV..

for the punctuation:

• period: the bullet is followed by a single period, like in 1., ii., c..
• right-paren: the bullet is followed by a single right parenthesis, like in 1), ii), c).
• full-paren: the bullet is wrapped inside a pair of parentheses, like in (1), (ii), (c).
• marking-style:
• highlight-only: both __ ... __ and {= ... =} denote highlighting.
• underline-only: both __ ... __ and {= ... =} denote underlining.
• both: __ ... __ denotes underlining and {= ... =} denotes highlighting. The default option.

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#}:

• set ordered-list-style to number,right-paren
• set marking-style to underline-only
• set smart-punctuation to 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

• One-file vs. Multiple-file generation (à la emacs org-mode)

### Smart punctuation

When enabled:

•  would be translated to “
• '' would be translated to ”
•  would be ‘
• ' would be ’
• -- would be – (en dash)
• --- would be — (em dash)

### 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

• Shorthand for HTML attributes, simply because Camus isn't designed only for generating HTML files.