rules.ab

# Inline and basics

## Basic
- Italic: `_italic_` or `{_italic_}` (the second is more explicit 
and covers edge cases, like `part{_italic_})
- Strong: `*strong*` or `{*strong*}
- Verbatime / code: `` `verbatim` ``
- Sub: H~2~O
- Sup: 10^-34^
- Highlighted: {=highlighted=}
- Underline: {+insert+}
- Deleted: {-deleted-}

## Escaping characters
Characters can be escaped using `\`. 
E.g. `\*not strong` will not produce a strong inline.
E.g. `\a` will just escape a, even if not needed in this context.

## Attributes
Generally, attributes can be specified with `{}`. These can have different behaviors
depending on the context.

Horizontal rule separation (with and without white-spaces before and after), more than two consecutive '-':
`---`

-----------------

# References

## Labels and refs
It is possible to labelize items and make reference to them. To labelize a header,
simply use the attribute `{l:my label}` in the right context.

### Refs

To make references, one uses the syntax `[[my label]]` (like wiki links in Markdown).
To make references to another document, one can use `[[document#label]]. If there is 
a document with the same name as a label in current document and one wishes to use the
current label, it is possible to solve the problem by specifying `[[#current label]]`
(# alone designates current document)

### Automatic enumeration
Some things that can be automatically enumerated:

- Chapters and headers
- Figures
- Tables
- Block code
- Drawings
- Citations

When making reference to them, the editor can take advantage of that.

## Bibliography and citation
It is possible to add a bibliography element and make reference to it by simply putting
in a new line:
```AB
I want to make a citation [[my citation]]

[c:my citation]: Foo bar, Markup languages proceedings, Volume 2, p.45, 2022
```

### Footnotes
It is also possible to do standard footnotes, like in markdown:
```AB
I want a footnote [^foot].

[^foot]: A note.

-----------------

# Links

```AB
<https://example.com>
A link inside [text](example.com).
Another link which is defined [later][link]

[link]: https://example.com
```

-----------------

# Images

```AB
![Image with title](image.png)
![Image defined later][image]

[image]: image.png
```

-----------------

# Definitions

A paragraph with the following regex ^\[.*\]: is considered as a definition.
We can have footnotes, links, images and citation definitions.


-----------------

# Headers

Header is a # followed by a space, with the number of # indicating the level (1-6)
```AB
# Simple header {l:with label}
```

```AB
## Second-level header
## with a second line
```

```AB
# Header
## Sub-header
```

-----------------

# Blocks

If there are more than 4 whitespaces, then everything that follows (the line) is counted as a paragraph,
except if we are in the case of a sub-list and list items.

-----------------

# Lists

Must be a list marker, preceeded by an optional space, and followed by a mandatory space.
To be still part of an item, one must align with the first char of the item.
You can have only one blank line in between.

```AB
- Item 1

  Still in item 1
- Item 2


  Not item item 2 (too many blank lines)
```

## List-markers

```AB
-   bullet
+   bullet
*   bullet

x.  ordered
x)  ordered
(x) ordered

x can be one of the following:
1   decimal-enumerated     (limited to 999999999)
a   lower alpha-enumerated (limited to zzz)
A   upper alpha-enumerated (limited to ZZZ)
i   lower roman-enumerated (limited to mmmcmxcix, i.e. 3999)
I   upper roman-enumerated (limited to MMMCMXCIX, i.e. 3999)
```

Different type of markers in list interrupt current lists and create new lists.

```AB
- item
1. item
i. item
```

creates three different lists with each one list item.

### Ambiguous cases

If one needs to start a paragraph with a list marker, one can simply escape the first char.
```AB
\I. wanted to start a simple paragraph and not a list.
```

If another alpha-enumerated item is in the list, and the list is not interrupted in between the two
items, then it is automatically alpha-enumerated.

Example:
```AB
i. Item
j. Item
```
produces an alpha-enumerated list.

To decide between ambiguous cases (alpha or roman?), if no other list items allow for the arbitration,
then the lowest decimal equivalent enumeration wins.

Example:
```AB
i. Item
```

In this case, in roman `i` corresponds to 1 and in alpha `i` corresponds to 9, 
so the list is roman-enumerated.


### Tasks
List markers can be followed by [ ], [x] or [v], thus creating tasks (empty, failed, succeeded)

## Sub-list
Lists can have lists in them (and any other blocks), which are called sublists. It is not possible
to start with sublists.
Sub-lists must have 4 spaces (or one tab) of indentation compared to the 
parent list item, i.e. a sub-list must be preceeded by 4 spaces, a sub-sub-list by 8 spaces, etc.

```AB
- Item 1
    a) Sub-list item
    b) Sub-list item
        i. Sub-sub-list item
    c) Sub-list item
- Item 2
```

It is not possible to begin with a sub-list, except if it is interrupted by a blockquote:
```AB
- - Not valid, the second dash is interpreted as text

- > - Okay
```
-----------------

# Block quotes

Block Quotes:

```AB
> First level
>> Second level
```

Block quotes do not allow lazy line continuation as in Markdown.

## Mixing block quotes and list items

```AB
> - Item 1
>   > Start blockquote
>   > continue blockquote
> i. > - Valid list in blockquote in list in blockquote
```

-----------------

# Paragraphs

To separate paragraphs, one must insert blank lines (can be with withespace).
Paragraph have the least precedence, so they can be interrupted by any other block.

```AB
My first paragraph

My second paragraph
with a second line.
# Interrupted by a header
```

-----------------

# Code blocks

Three or more consecutive backticks can start a code block, with markup information on the first line.
The closing consecutive backticks can't contain any chars except withespace beyond the line. \\ escape
chars do not work in code blocks.

````AB
```html
<p>html code</p>
```
````

````
```html
<p>html code</p>
```a               # Won't close the backticks
````

Code blocks are interrupted by the end of parents
````AB
> ```
> code block
Previous code block is interrupted by this paragraph
````

-----------------

# Raw blocks

One can have raw content, called raw blocks (like in djot):
````AB
```{=html}
<video width="320" height="240" controls>
   <source src="movie.mp4" type="video/mp4">
</video>
```
````

-----------------

# Latex Math

Inline is surrounded by $. E.g.: `$math$`
with escaped character: $f(x) \$ = x^2$, will give this LaTex string: `f(x) $ = x^2`
Any other \ is taken as is: `$\mathbf(x)$` (no need to escape \)

As a block:
```AB
$$
f(x) = x^2
$$
```

Same escaping rules:
```AB
$$
I write \$$
$$
```

-----------------

# Tables

TODO

-----------------

# Special Blocks

A special block starts with three consecutive : followed by a description on one line,
ends with three consecutive :.

```AB
::: name-of-block
content
:::
```

Special blocks can be inside quotes and list. A special block inside a quote or list not
closed will be closed when the parent block is closed.

Here are special blocks used by MathNotes:

## Figures

```AB
::: figure {ncols=2,nrows=3,center}
![title of my image](image.png) any text written here is ignored
![other image](image.png)

Any text written here is taken as legend
:::
```
One image per line. 

It is possible to specify number of cols with the attribute ncols.
Keywords center, left, right will align the images.