# [P]oker's M[a]de-up [M]arkup [L]anguage

{
PaML is a markup language based heavily on random Markdown flavours and my needs for easier editing of pokerfacowaty.com; it is intended to be used for rendering HTML.
}

{
At its current state, PaML elements have set classes for styling and the reason for the choice of classes is simply whatever names I'm using for pokerfacowaty.com's styling. I would like to have custom classes / ids in the future, but that's going to require a lot of additional work.
}

{
PaML can be converted to HTML using [paml2html](https://github.com/PokerFacowaty/paml2html).
}

{
You can also track the development of both the converter and the language on [this Vikunja page!](https://vikunja.pokerfacowaty.com/share/xSbQeLXtVLmTpqdniQhIjmzLUgdxJwtpUStgIbya/auth)
}

{
This entire website was initially written in PaML. Find its source [here](./docs.txt) (saved in .txt so that your browser can display it).
}

## Text decorations
- Links ``[text](link)``
- Bold ``**Text**``
- Italics ``__Text__``
- Inline code ``two ` backticks at the start and at the end``

## Headings

{
Headings in PaML use the Markdown convention. ``# Text`` becomes ``<h1>Text</h1>``, ``## Text`` - ``<h2>Text</h2>`` and so on up until ``<h6>``.
}

## Paragraphs
{
Paragraphs in PaML are surrounded by curly brackets ``{}``. The lines containing the opening and closing paranthesis **must** be separate from the rest of the text. Paragraphs can either be text-only or contain a single image on the side. Text can be indented, as whitespace at the beginning of every line is ignored. Since the paragraphs' text are simply ``<p>`` tags, multiple spaces are replaces with just a single one. New lines are replaced with as kept as ``<br>`` tags.
}

### Just text

```/* Example: */
{
    text
}
```

```/* HTML: */
<div class="paragraph">
  <p>text</p>
</div>
```

#### Result:
{
text
}

### With a picture on the left

```/* Example: */
{!l[alt text](image.png)
text
}
```

```/* HTML: */
<div class="paragraph">
  <img alt="alt text" src="image.png" class="img-half-left" />
  <p>text</p>
</div>
```

#### Result:
{!l[alt text](image.png)
text
}

### With a picture on the right

```/* Example: */
{!r[alt text](image.png)
text
}
```

```/* HTML: */
<div class="paragraph">
  <img alt="alt text" src="image.png" class="img-half-right" />
  <p>text</p>
</div>
```

#### Result:
{!r[alt text](image.png)
text
}

## Images
{
    Regular images are added the same way as in Markdown.
}

```
![alt text](image.png)
```


```/* HTML: */
<img alt="alt text" src="image.png" />
```

#### Result:
![alt text](image.png)

## Code
{
    Code as a separate element is split into code lines and code blocks. Code line is simply a code block that has only a single line. Separating the two allows for different styling in terms of e.x. text wrapping.
}
{
    Note: inline code is treated as text decorator and can be found at the top of this document.
}
{
**Important: The three backticks with optional comments at the start and the three backticks at the end of code have to be on separate lines.** Some examples below use three quotation marks instead of three backticks for presentation purposes.
}

###  Code line

```/* Example: */ /** The three quotation marks at the end should be replaced with three backticks **/
```/* Auto connect */ /** Connects, small comment **/
server add -ssl -auto -network {network} {link} {port}
'''
```

```/* HTML: */
<div class="line-code-box">
  <div class="line-code-comment">Auto connect</div>
  <div class="line-code-small-comment">Connects, small comment</div>
  <code class="line-code">server add -ssl -auto -network {network} {link} {port}</code>
</div>
```

#### Result:
```/* Auto connect */ /** Connects, small comment **/
server add -ssl -auto -network {network} {link} {port}
```

### Code block

```/* Example: */ /** The three quotation marks at the end should be replaced with three backticks **/
```/* break vs continue *//**Small block code comment **/
for x in "abcd":
    if x == "c":
        break
    print(x)  # a, b

for x in "abcd":
    if x == "c":
        continue
    print(x)  # a, b, d
'''
```

```/* HTML: */
<div class="block-code-box">
  <div class="block-code-comment">break vs continue</div>
  <div class="block-code-small-comment">Small block code comment</div>
  <code class="block-code">
    <pre>for x in "abcd":
    if x == "c":
        break
    print(x)  # a, b

for x in "abcd":
    if x == "c":
        continue
    print(x)  # a, b, d</pre>
  </code>
</div>
```

#### Result:
```/* break vs continue *//**Small block code comment **/
for x in "abcd":
    if x == "c":
        break
    print(x)  # a, b

for x in "abcd":
    if x == "c":
        continue
    print(x)  # a, b, d
```

## Lists

{
    Lists in PaML are made the same way as in Markdown. Note that Lists are currently the only object that reacts to a new line - a list will end whenever there is an empty line that would be skipped in other cases. **Lists currently only support formatted text.**
}

### Unordered lists

{
    Unordered lists are made with dashes ``-``.
}

```/* Example: */
- Element 1
- Element 2
- Element 3
```

```/* HTML: */
<ul>
  <li>Element 1</li>
  <li>Element 2</li>
  <li>Element 3</li>
</ul>
```

#### Result:
- Element 1
- Element 2
- Element 3

### Ordered lists

{
    Ordered lists are made with numbers.
}

```/* Example: */
1. Element
2. Element
3. Element
```

```/* HTML: */
<ol>
  <li>Element</li>
  <li>Element</li>
  <li>Element</li>
</ol>
```

#### Result:
1. Element
2. Element
3. Element

### Sublists
{
    You can make sublists by using indentation with spaces. Any consistent amount of spaces is fine.
}

```/* Example: */
- Element 1
    - Element 2
    - Element 3
- Element 4
```

```/* HTML: */
<ul>
  <li>Element 1</li>
  <ul>
    <li>Element 2</li>
    <li>Element 3</li>
  </ul>
  <li>Element 4</li>
</ul>
```

#### Result:
- Element 1
    - Element 2
    - Element 3
- Element 4

### Mixing list types

{
    List types can be freely mixed.
}

```/* Example: */
1. Element
    - 1
    - 2
2. Element
```

```/* HTML: */
<ol>
  <li>Element</li>
  <ul>
    <li>1</li>
    <li>2</li>
  </ul>
  <li>Element</li>
</ol>
```

#### Result:
1. Element
    - 1
    - 2
2. Element

## Tables

{
    **Tables currently only support formatted text.**
}

### Table with headers

{
    Headers are separated from the rest of the table with a row of cells containing only dashes ``-`` and spaces.
}

```/* Example */
| Head2 | 2Head |
| ----- | ----- |
| text  | text2 |
```

```/* HTML: */
<table>
  <tr>
    <th>Head2</th>
    <th>2Head</th>
  </tr>
  <tr>
    <td>text</td>
    <td>text2</td>
  </tr>
</table>
```

#### Result:
| Head2 | 2Head |
| ----- | ----- |
| text  | text2 |

### Table without headers

```/* Example: */
| a | b |
| c | d |
```

```/* HTML */
<table>
  <tr>
    <td>a</td>
    <td>b</td>
  </tr>
  <tr>
    <td>c</td>
    <td>d</td>
  </tr>
</table>
```

#### Result:
| a | b |
| c | d |

## Collapsibles
{
    Collapsibles are special containers that can be opened to reveal hidden content. PaML allows for creation of simple HTML collapsibles that do not need any JavaScript to work. Collapsibles are stored in "collapsible boxes" that are divs holding collapsibles of the same type together.
}
{
    Collapsibles are started with a ``>``, a letter indicating the type ``("f" - full, "l" - left or "r" - right)`` an optional desired collapsible icon and the collapsible's name e.x. ``>f➤ JavaScript`` for a collapsible with an icon and ``>r Python`` without one.
}
{
    Any content within a collapsible should be indented with any consistent amount of spaces.
}

### Half-width on the left

```/* Example *//** The three quotation marks should be replaced with three backticks **/
>l➤ irssi
    ![alt text](./image.png)
    ```/* Auto connect */ /** Connects, small comment **/
    server add -ssl -auto -network {network} {link} {port}
    '''
    ```/* Auto identify */
    /network add -autosendcmd "/msg nickserv identify {password} ;wait 2000" {network}
    '''
```

```/* HTML: */
<div class="collapsible-box-half-left">
  <details>
    <summary class="header"><span class="icon">➤</span> irssi</summary>
    <div class="entry">
      <img alt="alt text" src="./image.png" />
    </div>
    <div class="entry">
      <div class="line-code-box">
        <div class="line-code-comment">Auto connect</div>
        <div class="line-code-small-comment">Connects, small comment</div>
        <code class="line-code">server add -ssl -auto -network {network} {link} {port}</code>
      </div>
    </div>
    <div class="entry">
      <div class="line-code-box">
        <div class="line-code-comment">Auto identify</div>
        <code class="line-code">/network add -autosendcmd "/msg nickserv identify {password} ;wait 2000" {network}</code>
      </div>
    </div>
  </details>
</div>
```

#### Result:
>l➤ irssi
    ![alt text](./image.png)
    ```/* Auto connect */ /** Connects, small comment **/
    server add -ssl -auto -network {network} {link} {port}
    ```
    ```/* Auto identify */
    /network add -autosendcmd "/msg nickserv identify {password} ;wait 2000" {network}
    ```

### Half-width on the right

```/* Example *//** The three quotation marks should be replaced with three backticks **/
>r➤ irssi
    ![alt text](./image.png)
    ```/* Auto connect */ /** Connects, small comment **/
    server add -ssl -auto -network {network} {link} {port}
    '''
    ```/* Auto identify */
    /network add -autosendcmd "/msg nickserv identify {password} ;wait 2000" {network}
    '''
    ```

```/* HTML: */
<div class="collapsible-box-half-right">
  <details>
    <summary class="header"><span class="icon">➤</span> irssi</summary>
    <div class="entry">
      <img alt="alt text" src="./image.png" />
    </div>
    <div class="entry">
      <div class="line-code-box">
        <div class="line-code-comment">Auto connect</div>
        <div class="line-code-small-comment">Connects, small comment</div>
        <code class="line-code">server add -ssl -auto -network {network} {link} {port}</code>
      </div>
    </div>
    <div class="entry">
      <div class="line-code-box">
        <div class="line-code-comment">Auto identify</div>
        <code class="line-code">/network add -autosendcmd "/msg nickserv identify {password} ;wait 2000" {network}</code>
      </div>
    </div>
  </details>
</div>
```

#### Result:
>r➤ irssi
    ![alt text](./image.png)
    ```/* Auto connect */ /** Connects, small comment **/
    server add -ssl -auto -network {network} {link} {port}
    ```
    ```/* Auto identify */
    /network add -autosendcmd "/msg nickserv identify {password} ;wait 2000" {network}
    ```

### Full-width

```/* Example: *//** The three quotation marks should be replaced with three backticks **/
>f➤ Python
    ```/* break vs continue *//**Small block code comment **/
for x in "abcd":
    if x == "c":
        break
    print(x)  # a, b

for x in "abcd":
    if x == "c":
        continue
    print(x)  # a, b, d
    '''
```

```/* HTML: */
<div class="collapsible-box-full">
  <details>
    <summary class="header"><span class="icon">➤</span> Python</summary>
    <div class="entry">
      <div class="block-code-box">
        <div class="block-code-comment">break vs continue</div>
        <div class="block-code-small-comment">Small block code comment</div>
        <code class="block-code">
          <pre>for x in "abcd":
    if x == "c":
        break
    print(x)  # a, b

for x in "abcd":
    if x == "c":
        continue
    print(x)  # a, b, d</pre>
        </code>
      </div>
    </div>
  </details>
</div>
```

#### Result:
>f➤ Python
    ```/* break vs continue *//**Small block code comment **/
for x in "abcd":
    if x == "c":
        break
    print(x)  # a, b

for x in "abcd":
    if x == "c":
        continue
    print(x)  # a, b, d
    ```

### Nested collapsibles

```/* Example */
>r Python
    >r pathlib
        {
        is a fantastic library
        }
```

```/* HTML */
<div class="collapsible-box-half-right">
  <details>
    <summary class="header">Python</summary>
    <details>
      <summary class="header">pathlib</summary>
      <div class="entry">
        <div class="paragraph">
          <p>is a fantastic library</p>
        </div>
      </div>
    </details>
  </details>
</div>
```

#### Result:
>r Python
    >r pathlib
        {
        is a fantastic library
        }



### Commands
{
Commands are special objects designed mainly (but not exclusively) to be used inside collapsibles (e.x. for cheat sheets of key shortcuts). They consist of a command and optional comments of two sizes.
}

```/* Example: */
/Ctrl + E /* Clear the screen */ /** Small comment **/
```

```/* HTML: */
<div class="command-box">
  <span class="command">Ctrl + E</span>
  <span class="same-line-comment">Clear the screen</span>
  <div class="small-comment">Small comment</div>
</div>
```

#### Result:
/Ctrl + E /* Clear the screen */ /** Small comment **/

## Raw HTML

{
PaML provides the option to add raw HTML straight to the final doc. Open the raw HTML block with a ``<`` on a new line and end the block with a ``>`` on a new line.
}

```/* Example: */
<
<h1>U WANT TO DO IT RAW</h1>
>
```

```/* HTML: */
<h1>U WANT TO DO IT RAW</h1>
```

#### Result:
<
<h1>U WANT TO DO IT RAW</h1>
>