unison/doc2.u

{-
- [x] Debug the lexer/parser combination
- [ ] Implement display logic for new doc type in DisplayValues
- [ ] Write illustrative transcript (and possibly separate tests)
- [ ] Pretty-printer should reverse the syntax
- [ ] PR writeup
- [ ] (Later) docs command should look for foo.doc if nothing is linked, or just have it do: display foo.doc
- [ ] (Later) Top level types should allow anon doc blocks
- [ ] (Later) Remove backticks syntax
- [ ] (Later) Instant docs preview
- [ ] (Later) Remove old doc, rename Doc2 to Doc
-}

unique[da70bff6431da17fa515f3d18ded11852b6a745f] type Doc2.SpecialForm
  = Source [Either Link.Type Any]
  | Example Nat Any 
  | Link (Either Link.Type Any)
  | Signature [Any]
  | InlineSignature Any
  | Eval Doc2.Evaluation
  | InlineEval Doc2.Evaluation
  | Embed Any
  | InlineEmbed Any

unique[b7a4fb87e34569319591130bf3ec6e24c9955b6a] type Doc2
  = Word Text
  | Code Doc2
  | CodeBlock Text Doc2 
  | Bold Doc2
  | Italic Doc2
  | Strikethrough Doc2
  -- style {{ myclass }} mydoc 
  | Style Doc2 Doc2
  | Blockquote Doc2
  | Blankline
  | SectionBreak
  | Aside (Optional Doc2) Doc2
  -- callout icon content
  | Callout (Optional Doc2) Doc2
  | Folded Boolean Doc2 Doc2
  | Paragraph [Doc2]
  | BulletedList [Doc2]
  | NumberedList Nat [Doc2]
  | Section Doc2 [Doc2] 
  | NamedLink Doc2 Doc2
  | Special Doc2.SpecialForm
  | Docs [Doc2]

unique[fb488e55e66e2492c2946388e4e846450701db04] type Doc2.Evaluation = Evaluation Any Any 

unique[d7b2ced8c08b2c6e54050d1f5acedef3395f293d] type Pretty.Annotated w txt
  = Empty
    -- | A group adds a level of breaking. Layout tries not to break a group
    -- unless needed to fit in available width. Breaking is done "outside in".
    --
    --   (a | b) <> (c | d) will try (a <> c), then (b <> d)
    --
    --   (a | b) <> group (c | d) will try (a <> c), then (b <> c), then (b <> d)
  | Group w (Pretty.Annotated w txt)
  | Lit w txt
  | Wrap w [Pretty.Annotated w txt]
  | OrElse w (Pretty.Annotated w txt) (Pretty.Annotated w txt)
  | Append w [Pretty.Annotated w txt]

type Pretty txt = Pretty (Pretty.Annotated () txt)

Pretty.get = cases Pretty p -> p

Doc2.evaluate : 'a -> Evaluation
Doc2.evaluate a = Doc2.Evaluation.Evaluation (Any a) (Any !a) 

Doc2.Evaluation.source : Evaluation -> Any
Doc2.Evaluation.source = cases Evaluation src _ -> src

Doc2.Evaluation.result : Evaluation -> Any
Doc2.Evaluation.result = cases Evaluation _ result -> result

syntax.doc.docs = cases [d] -> d
                        ds -> Docs ds
syntax.doc.word = Word
syntax.doc.bold = Doc2.Bold
syntax.doc.italic = Italic
syntax.doc.strikethrough = Strikethrough
syntax.doc.paragraph = Paragraph
syntax.doc.embedTermLink tm = 
  guid = "b7a4fb87e34569319591130bf3ec6e24"
  Right (Any tm)
syntax.doc.embedTypeLink typ = 
  guid = "b7a4fb87e34569319591130bf3ec6e24"
  Left typ 
syntax.doc.source t = Special (Source t)
syntax.doc.signature t = Special (Signature t)
syntax.doc.inlineSignature t = Special (InlineSignature t)
syntax.doc.inlineEval e = Special (InlineEval (evaluate e))
syntax.doc.embedSignatureLink tm =
  guid = "d9a4fb87e34569319591130bf3ec6e24"
  Any tm
syntax.doc.code c = Code c 
syntax.doc.codeBlock typ c = CodeBlock typ (word c)
syntax.doc.verbatim c = CodeBlock "raw" c 
syntax.doc.evalBlock d = Special (Eval (evaluate d))
syntax.doc.eval a = Special (InlineEval (evaluate a))
syntax.doc.example n a = Special (Example n (Any a))
syntax.doc.link = Link
syntax.doc.transclude d = 
  guid = "b7a4fb87e34569319591130bf3ec6e24"
  d
syntax.doc.namedLink = NamedLink 
syntax.doc.bulletedList = BulletedList
syntax.doc.numberedList = NumberedList
syntax.doc.section = Section

syntax.doc.renderToConsole : Doc2 -> Pretty (Either SpecialForm ConsoleText) 
syntax.doc.renderToConsole d = todo "implement me"

unique[e25bc44d251ae0301517ad0bd02cbd294161dc89] type ConsoleText
  = Plain Text
  | Foreground ANSI.Color ConsoleText 
  | Background ANSI.Color ConsoleText
  | Bold ConsoleText
  | Underline ConsoleText
  | Invert ConsoleText

unique[de2e0ee924578939213c950dfd8e0ba1047703ae] type ANSI.Color
  = Black | Red | Green | Yellow | Blue | Magenta | Cyan | White
  | BrightBlack | BrightRed | BrightGreen | BrightYellow | BrightBlue 
  | BrightMagenta | BrightCyan | BrightWhite

doc1 = {{

# Unison documentation format

The syntax tries to be close to markdown.

## Basic formatting

Paragraphs are separated by one or more blanklines. There's syntax for bold, italics, and strikethrough text:

'''
_italics_ or *italics*

**bold text** or __moar bold text__

~~striken text~~

''some code''

[The Unison website](https://unisonweb.org)
'''

Renders as:

_italics_ or *italics*

**bold text** or __moar bold text__

~~stricken text~~

''some code''

[The Unison website](https://unisonweb.org)

### Escaping formatting

If you want the text. 

'''
{{ syntax.doc.word "__not bold__"}}
'''

Renders as:

{{ syntax.doc.word "__not bold__" }}

If you have some inline text you want to leave unparsed and have it render in a monospace font, do:

'''
An example of bold text syntax: ''__some bold text__''
'''

Renders as:

An example of bold text syntax: ''__some bold text__''

## Sections and subsections

'''
# Section title! 

Sections consist of section titles followed by zero or more paragraphs or other section elements (such as subsections). 

## Subsection title 

* Item 1
* Item 2

## An empty subsection!

### Subsection 2.1

Some deeply nested content in subsection 2.1
'''

Sections start with a title, then zero or more documents, separated by blanklines. Sections whose title starts with ''##'' are subsections of sections whose title starts with one ''#''. Sections may be nested arbitrarily.

## Lists

### Bulleted lists

Bulleted lists can use ''+'', ''-'', or ''*'' for the bullets. They can be nested, to any depth:

'''
+ A
+ B
+ C
  - C1
  * C2
'''

Renders as:

+ A
+ B
+ C
  - C1
  * C2

### Numbered lists

'''
1. A
2. B
3. C
'''

Renders as:

1. A
2. B
3. C

The first number of the list determines the starting number in the rendered output. The other numbers are ignored:

'''
10. A
99. B
102. C
'''

Renders as:

10. A
99. B
102. C

Numbered lists can be nested as well, and combined with bulleted lists:

'''
1. Wake up.
  + What am I doing here?
  + In this nested list. 
2. Take shower.  
3. Get dressed.
'''

1. Wake up.
  + What am I doing here?
  + In this nested list. 
2. Take shower.  
3. Get dressed.

## Evaluation 

'''
Expressions can be evaluated inline, for instance @eval{1 + 1}.
'''

Renders as:

Expressions can be evaluated inline, for instance @eval{1 + 1}.

Blocks of code can be evaluated as well, for instance:

'''
```
id x = x

id 99
``` 
'''

Renders as:

```
id x = x

id 99
``` 

## Including Unison source code

'''
@source{ type Optional, id }
'''

Renders as:

@source{ type Optional, id }

You can also render just the signatures of a collection of terms: 

'''
@signatures{ id, Some, None }
'''

Renders as:

@signatures{ id, Some, None }

You can reference a signature inline, like so 

'''
An inline signature @signature{id}.
'''

Renders as:

An inline signature @signature{id}.

## Including other documents

'''
"And what is the use of a book," thought {{name}}, "without pictures or conversations?"

* [The documentation]({{baseUrl}}/docs)
'''

"And what is the use of a book," thought {{name}}, "without pictures or conversations?"

TODO why do we have to declare ''name'' earlier in the file?

## Non-unison code blocks 

A code block with no syntax highlighting starts with at least two {{ code (word "'") }} characters, and is terminated by the same number of {{ code (word "'") }} characters. 

''''
'''
Not formatted. Rendered as a code block with no syntax highlighting.
'''
''''

Renders as:

'''
Not formatted. Rendered as a code block with no syntax highlighting.
'''

You can use triple (or greater) backticks plus a language name for blocks with syntax highlighting.

'''
``` Haskell
-- A fenced code block which isn't parsed by Unison
reverse = foldl (flip (:)) []
```

``` Scala
// A fenced code block which isn't parsed by Unison
def reverse[A](xs: List[A]) = 
  xs.foldLeft(Nil : List[A])((acc,a) => a +: acc)
```
'''

Renders as:

``` Haskell
-- A fenced code block which isn't parsed by Unison
reverse = foldl (flip (:)) []
```

``` Scala
// A fenced code block which isn't parsed by Unison
def reverse[A](xs: List[A]) = 
  xs.foldLeft(Nil : List[A])((acc,a) => a +: acc)
```
}}

name = {{ Alice }}
baseUrl = {{ https://www.unisonweb.org }}