mirror of
https://github.com/unisonweb/unison.git
synced 2024-09-23 16:28:02 +03:00
390 lines
8.3 KiB
Plaintext
390 lines
8.3 KiB
Plaintext
{-
|
|
- [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 }}
|
|
|