# Links

Links connect wasot documents together, enabling [zettelkasten](./use_cases.md) note-taking and other [use cases](./use_cases.md). Links point to [document IDs](./document_ids.md).

What I need:

- Optional Link name (unnamed link if not given)
- Optional Link target (unresolved link if not given)
- Links to ID
- Commands / Args for a link, e.g. to embedd it

Possible sources of inspirations:

- HTML
- Markdown
- Asciidoc
- <https://stackoverflow.com/questions/49969777/how-to-create-external-link-references-in-asciidoc-without-repeating-the-url-mul>

## Requirements

Functional requirements

- Arguments
- Name
- Target

All are optional.

Non-functional:

- Easy to type
- Easy to read the text ignoring the links
- Needs to work in programming languages as well

Maybe:

- Reuse existing concepts / parsers to build minimal intuition.

## Observations

- Typing a double-character is almost the same as typing one, so :: and : take almost the same time.
- I like it more if the markers are low, like `.` or `:`, not `(`
- The link start needs to be a good trigger for link-search, so `::` is kind of bad
- Text is more read than written, but we want to write at the speed of thought

## Ideas / Brainstorming

- ::link::
  - Good: Looks very good, no special characters
  - Bad: Probably Collides with a lot of languages
- <<link>>
  - <<Name of the link .. arg1 kw=arg :target>>
  - <<Name of the link :target>>
  - Good: Opposite characters
  - Bad: Looks ugly? A bit of a special character
- ((link))
  - Bad: looks ugly and communicates aside
  - Good: No special character
- //link//
  - //Name of the link .. arg1 kw=arg :target//
  - Good: No special character, a comment in many languages so proably not 2 in a line
  - At least most comments are `//` not only `//`
  - Bad: Bad trigger
- ((link))
  - ((Name of the link .. arg kw=arg :target))
  - Good: Simple double parentheses, easy to type
  - Looks clean, no collisions with most programming languages
- [[link]]
  - [[Name of the link .. arg1 kw=arg :target]]
  - Good: Similar to other languages, looks like a box
  - Bad: Special character
. ./link/ -> We can always escape for the  cost of 2 required characters, but at least constant
. ./test// Almost the same, but allows for / in links, which should be common

First impressions: After iterating on it a bit, these are the candidates I like:

- <<link>>, but ugly
- //link// as a better version of (())
- ((link)) makes the most sense and is easy to type

And maybe

- [[link]] because I am used to it, but special characters

## Remap links

## Reference Link

A target can be a URI, footnote like `*1` or an ID (default).

Put Links as foot-notes, like this

*1 <https://en.wikipedia.org/wiki/Statistical_Algorithms>

## Playing around

### Using :: and ()

Machine learning (ML) is a field of study in artificial intelligence concerned with
the development and study of ::statistical algorithms (<https://en.wikipedia.org/wiki/Statistical_Algorithms>):: that can learn from data and
generalise to unseen data, and thus perform tasks without explicit instructions.[1]
Within a subdiscipline in ::machine learning (<https://en.wikipedia.org/wiki/Machine_learning>)::, advances in the field of deep learning
have allowed neural networks, a class of statistical algorithms, to surpass many
previous machine learning approaches in performance.

-------- This gets converted to --------------

Machine learning (ML) is a field of study in artificial intelligence concerned with
the development and study of ::statistical algorithms (1):: that can learn from data and
generalise to unseen data, and thus perform tasks without explicit instructions.[1]
Within a subdiscipline in ::machine learning (1)::, advances in the field of deep learning
have allowed neural networks, a class of statistical algorithms, to surpass many
previous machine learning approaches in performance.

(1) <https://en.wikipedia.org/wiki/Statistical_Algorithms>
(2) <https://en.wikipedia.org/wiki/Machine_learning>

### Using ((link))

Machine learning (ML) is a field of study in artificial intelligence concerned with
the development and study of ((statistical algorithms :<https://en.wikipedia.org/wiki/Statistical_Algorithms>)) that can learn from data and
generalise to unseen data, and thus perform tasks without explicit instructions.[1]
Within a subdiscipline in ((machine learning :<https://en.wikipedia.org/wiki/Machine_learning>)), advances in the field of deep learning
have allowed neural networks, a class of statistical algorithms, to surpass many
previous machine learning approaches in performance.

-------- This gets converted to --------------

Machine learning (ML) is a field of study in artificial intelligence concerned with
the development and study of ((statistical algorithms :*1)) that can learn from data and
generalise to unseen data, and thus perform tasks without explicit instructions.[1]
Within a subdiscipline in ((machine learning :*2)), advances in the field of deep learning
have allowed neural networks, a class of statistical algorithms, to surpass many
previous machine learning approaches in performance.

*1 <https://en.wikipedia.org/wiki/Statistical_Algorithms>
*2 <https://en.wikipedia.org/wiki/Machine_learning>

## Implementation Status

The `((link))` syntax has been fully implemented.

### Core Components

| File | Purpose |
|------|---------|
| `src/parsers/wasot/link_parser.rs` | Link detection (`detect_links`) and parsing (`parse_link`) |
| `src/parsers/wasot/parser.rs:112-126` | `Link` struct and `TargetType` enum |
| `src/consumers/links_printer.rs` | Consumer that displays all links in a document |
| `src/events/events.rs:69` | Links included in `TextFinished` events |

### Syntax

```wasot
((name .. args key=value :target))
```

All parts are optional:
- **name**: Text before `..` (or entire content if no `..`)
- **args**: Positional and keyword arguments after `..`
- **target**: After the last ` :` (space-colon pattern)

### Target Types

Determined automatically by `determine_target_type()`:
- **URI**: Starts with a scheme like `https://`, `mailto:`, etc.
- **Footnote**: Starts with `*` followed by digits (e.g., `*1`)
- **ID**: Everything else (alphanumeric reference to another block)

### CLI Commands

```bash
cargo run -- links file.wasot       # Print all links with context
cargo run -- links-demo             # Run demo with example content
```

### Integration

Links are parsed within `QuotedString` (inline text, arguments) and propagated through the [event stream](./architecture.md) in `TextFinished` events. The `LinksPrinter` consumer demonstrates full link extraction from both inline text and block arguments. See [AST](./ast.md) for the data structures involved.
