# Contextline

## Naming / Why Contextline?

I need to com up with a proper name. There are already metalines, which enrich the normal text-lines. But these meta-lines are special. They are generated by wasot itself and not the user. They are like a namespace of reserved keywords. I don't like reserved keywords as they may collide with other systems I want to convert from/to, like XML or HTML. Thus I mark them with a marker. But how should I name them. Here is the result of a brain-storming

- Native Metaline
    - These lines are indigenous to the runtime environment. They are "first-class citizens" provided 
      directly by the underlying system or language implementation, rather than defined by an external 
      schema or user input.
    - Emphasizing that these properties are inherent to the language's ecosystem.
    - Notes: Native to what? 
    - Rank 5
- Managed Line
    - The lifecycle of this line is actively controlled (managed) by the system. It clearly communicates 
      to the user that while they can see the data, the responsibility for creating, updating, or 
      validating it belongs to the software, not the author.
    - Emphasizing the read-only or auto-generated nature of the data.
    - Notes: Quite nice, as the user can use it, but should not change it, because it is managed by something else
      Problem may be that it may happen in the future, that the user can write them himself and thus they are 
      not really managed. Like macros.
    - Rank 2: Would me my favourite, if ALL would be actually be managed, but the user may write them himself.
- Context Line
    - Creates a logical dichotomy between the "Content" (text-lines) and the "Context" (state, IDs, 
      environment). It suggests these lines define the situation or environment in which the content exists.
    - A clean conceptual separation between the document's payload and its metadata.
    - Notes: Provides context to the metalines. But maybe does other things as well in the future?
    - Rank 1: Because better than Managed Line because the user can change or write them himself in some cases
- Built-in Metaline or Built-in Line
    - A standard computer science term indicating functionality that is pre-packaged within the language 
      specification. It is the direct opposite of "user-defined."
    - Technical clarity and immediate understanding by developers.
    - Notes: Built-in is 2 words which I dont like and it is more a namespace than a component that is built in
    - Rank: 4
- Core Line
    - Suggests that these lines are the foundational, irreducible elements of a document. 
    - Brevity and implying that the document is invalid without them.
    - Notes: There is not really a core or kernel / user has maximal agency with wasot!
    - Rank: 5 

Ok, descision: Context-Line it is. So there are Text-Lines, Meta-Lines and Context-Lines (like a meta Meta-Line). For how contextlines fit into the overall [data model](./wasot_and_xml.md), see the data model documentation. For the [context](./the_context.md) system that contextlines interact with, see the context documentation.

## Marker

tldr; contextlines start with `./mytag`

As stated earlier, I want dont want to keep a list of reserved keywords like in programming languages like rust. 
I rather use a reserved keyword with a marker and make a line a contextline.
But which marker? 
I will start with a `.` followed by something else. Doing this does not constrain the text-lines - we already disable that 
the user can use lines with a dot in the first column.

We want to stay compatible with XML and HTML tags. Thus we use a symbol that is not a valid first character in a tag name. 
Thus I extracted a bit of knowledge from Gemini without further research about HTML and XML tag rules.


### English Rules (Syntactic Definition)

These rules describe a "well-formed" name according to the XML 1.0 standard, which is the strict superset often used for validating both XML and compliant HTML tokens.

1. **Start Character:** The first character must be a **letter** (uppercase or lowercase), an **underscore** (`_`), or a **colon** (`:`). It **cannot** be a number, a dot, or a hyphen.
2. **Subsequent Characters:** All characters following the first can be **letters**, **digits**, **underscores** (`_`), **hyphens** (`-`), **dots** (`.`), or **colons** (`:`).
3. **No Whitespace:** The name cannot contain spaces, tabs, or line breaks.
4. **No Special Symbols:** Characters like `!`, `@`, `#`, `$`, `%`, etc., are forbidden.

We can use special symbols except of an underscore or a colon. And we can not use a `.`, as `..` is already wasot syntax (second level block).

### Regular Expressions 

These patterns match the **name only** (e.g., `div` from `<div>` or `my-tag` from `<my-tag>`), with unicode.

```regex
^[\p{L}_:][\p{L}\p{N}_:.-]*$
```

HTML is more restrictive like this: `^[a-zA-Z][a-zA-Z0-9:.-]*$` thus we can use the regex above to test
Use regex101.com to test things out.

### Valid Tag Names (Examples)

* `section` (Standard alphabetical)
* `h1` (Alphanumeric)
* `user-profile` (Hyphenated)
* `_cache` (Underscore start)
* `soap:envelope` (Namespaced with colon)
* `config.sys` (Dot notation)
* `café` (Unicode/International characters)

### Invalid Tag Names (Examples)

* `404error` (Starts with a digit)
* `-nav` (Starts with a hyphen)
* `.container` (Starts with a period)
* `my tag` (Contains a space)
* `email@address` (Contains illegal symbol `@`)
* `price$` (Contains illegal symbol `$`)
* `item#id` (Contains illegal symbol `#`)

### Decision

We need a prefix and a special symbol. 

From above: We can use special symbols except of an underscore or a colon. And we can not use a `.`, as `..` is already wasot syntax (second level block).

Candidates are: 

- `.:mytag` i like the font level
- `.!mytag` ! often means command, which would be nice
- `.#mytag` bad! as this collides with markdown
- `.>mytag` Looks like a prompt or an arrow, whch is nice
- `.-mytag` Almost invisible, makes reading mytag easy and easy symbol non-programmers. But `-` is valid in tag-names in XML - just not in the first postion
- `.$mytag` Looks like bash
- `.%mytag` 
- `.*mytag` Starts are already used in links
- `.=mytag` Alsmost like `-` but uglier but not allowed in xml, which is nice. But used a lot in metalines for kwargs with a different meaning.
- `./mytag` Hm, this is command syntax in different tools, which is nice. And easy for non-programmers. And `//` comments look similar.

Thinking about it, I like `./mytag` most 



## Implementation

A contextline is not the same thing as a metaline.
This is because it is not part of the content hierarchy of the document (see [AST](./ast.md)). It just uses its scope.
Therefore it should also not interfere with the hierarchy.
It also cannot have Text nodes, which are leaves. Metalines are parts of blocks (see `block.rs`) which bundle them together.
Therefore it is not enough to just set a boolean flag at a metaline, but we need to have full support for it. It is its own Element.
We need to implement it end to end from parsing, through [events](./architecture.md), protobuf, and back into pretty printing.

Contextlines are used to set [document IDs](./document_ids.md), e.g., `./id 123`.


