From 8be80558c7bb52632c08d58af89823faff9789fe Mon Sep 17 00:00:00 2001 From: Patrick Fong Date: Thu, 28 Sep 2023 10:27:15 -0700 Subject: [PATCH] lint all Md files --- README.md | 56 ++++++++++++++++++------------------- README_TESTERS.md | 20 ++++++------- TODO.md | 18 ++++++------ docs/sequences.md | 65 +++++++++++++++++++++---------------------- docs/sequences/bel.md | 20 ++++++------- docs/sequences/bs.md | 12 ++++---- docs/sequences/can.md | 8 +++--- docs/sequences/cr.md | 10 +++---- docs/sequences/enq.md | 12 ++++---- docs/sequences/ff.md | 6 ++-- docs/sequences/hts.md | 4 +-- docs/sequences/ind.md | 12 ++++---- docs/sequences/lf.md | 8 +++--- docs/sequences/nel.md | 4 +-- docs/sequences/ri.md | 12 ++++---- docs/sequences/tab.md | 10 +++---- docs/sequences/vt.md | 6 ++-- test/README.md | 1 - 18 files changed, 141 insertions(+), 143 deletions(-) diff --git a/README.md b/README.md index e5eb79827..cabdafe19 100644 --- a/README.md +++ b/README.md @@ -44,11 +44,11 @@ things, but I've been using it full time since April 2022. ## Download -| Platform / Package | Links | Notes | -| ----------| ----- | ----- | -| macOS | [Tip ("Nightly")](https://github.com/mitchellh/ghostty/releases/tag/tip) | MacOS 12+ Universal Binary | -| Linux | [Build from Source](#developing-ghostty) | | -| Windows | n/a | Not supported yet | +| Platform / Package | Links | Notes | +| ------------------ | ------------------------------------------------------------------------ | -------------------------- | +| macOS | [Tip ("Nightly")](https://github.com/mitchellh/ghostty/releases/tag/tip) | MacOS 12+ Universal Binary | +| Linux | [Build from Source](#developing-ghostty) | | +| Windows | n/a | Not supported yet | ### Configuration @@ -134,12 +134,12 @@ to support many of the features that The currently support shell integration features in Ghostty: - * We do not confirm close for windows where the cursor is at a prompt. - * New terminals start in the working directory of the previously focused terminal. - * Complex prompts resize correctly by allowing the shell to redraw the prompt line. - * The cursor at the prompt is turned into a bar. - * The `jump_to_prompt` keybinding can be used to scroll the terminal window - forward and back through prompts. +- We do not confirm close for windows where the cursor is at a prompt. +- New terminals start in the working directory of the previously focused terminal. +- Complex prompts resize correctly by allowing the shell to redraw the prompt line. +- The cursor at the prompt is turned into a bar. +- The `jump_to_prompt` keybinding can be used to scroll the terminal window + forward and back through prompts. #### Shell Integration Installation and Verification @@ -208,15 +208,15 @@ goes for any other shell. The high-level ambitious plan for the project, in order: -| # | Step | Status | -|:---:|------|:------:| -| 1 | [Standards-compliant terminal emulation](docs/sequences.md) | ⚠️ | -| 2 | Competitive performance | ✅ | -| 3 | Basic customizability -- fonts, bg colors, etc. | ✅ | -| 4 | Richer windowing features -- multi-window, tabbing, panes | ✅ | -| 5 | Native Platform Experiences (i.e. Mac Preference Panel) | ⚠️ | -| 6 | Windows Terminals (including PowerShell, Cmd, WSL) | ❌ | -| N | Fancy features (to be expanded upon later) | ❌ | +| # | Step | Status | +| :-: | ----------------------------------------------------------- | :----: | +| 1 | [Standards-compliant terminal emulation](docs/sequences.md) | ⚠️ | +| 2 | Competitive performance | ✅ | +| 3 | Basic customizability -- fonts, bg colors, etc. | ✅ | +| 4 | Richer windowing features -- multi-window, tabbing, panes | ✅ | +| 5 | Native Platform Experiences (i.e. Mac Preference Panel) | ⚠️ | +| 6 | Windows Terminals (including PowerShell, Cmd, WSL) | ❌ | +| N | Fancy features (to be expanded upon later) | ❌ | Additional details for each step in the big roadmap below: @@ -261,10 +261,10 @@ Ghostty is a cross-platform terminal emulator but we don't aim for a least-common-denominator experience. There is a large, shared core written in Zig but we do a lot of platform-native things: -* The macOS app is a true SwiftUI-based application with all the things you +- The macOS app is a true SwiftUI-based application with all the things you would expect such as real windowing, menu bars, a settings GUI, etc. -* macOS uses a true Metal renderer with CoreText for font discovery. -* The Linux app is built with GTK. +- macOS uses a true Metal renderer with CoreText for font discovery. +- The Linux app is built with GTK. There are more improvements to be made. The macOS settings window is still a work-in-progress. Similar improvements will follow with Linux. @@ -310,11 +310,11 @@ tasks. Other useful commands: - * `zig build test` for running unit tests. - * `zig build run -Dconformance=` runs a conformance test case from - the `conformance` directory. The `name` is the name of the file. This runs - in the current running terminal emulator so if you want to check the - behavior of this project, you must run this command in ghostty. +- `zig build test` for running unit tests. +- `zig build run -Dconformance=` runs a conformance test case from + the `conformance` directory. The `name` is the name of the file. This runs + in the current running terminal emulator so if you want to check the + behavior of this project, you must run this command in ghostty. ### Compiling a Release Build diff --git a/README_TESTERS.md b/README_TESTERS.md index 12ceb062a..a69302050 100644 --- a/README_TESTERS.md +++ b/README_TESTERS.md @@ -42,28 +42,28 @@ or even pair (time permitting) if you're interested. This is the priority of bugs: - 1. Crashes. 💥 These are just unacceptable and I'll drop everything to - fix a crash. +1. Crashes. 💥 These are just unacceptable and I'll drop everything to + fix a crash. - 2. Escape sequence logic or rendering issues. These are almost as bad as - crashes because they usually make your workflow unusable. This includes - unsupported escape sequences that impact your workflow. +2. Escape sequence logic or rendering issues. These are almost as bad as + crashes because they usually make your workflow unusable. This includes + unsupported escape sequences that impact your workflow. - 3. Anything else... +3. Anything else... ## Let's Talk! You likely landed in the Discord community first, if for some reason you're not -in there, join [here](https://discord.gg/ghostty). Discord is a great place to +in there, join [here](https://discord.gg/ghostty). Discord is a great place to share feedback, discuss issues, ask questions and talk to other testers. ## Other FAQ ### Can I Invite a Friend? -To the Discord, go for it! [discord.gg/ghostty](https://discord.gg/ghostty). -Initially, they'll land in a public Discord channel. As mentioned, testers -are being added slowly as bugs are fixed. Discord is being used as a sort-of +To the Discord, go for it! [discord.gg/ghostty](https://discord.gg/ghostty). +Initially, they'll land in a public Discord channel. As mentioned, testers +are being added slowly as bugs are fixed. Discord is being used as a sort-of waitlist, and people are added to the project as testers from there, so just send them the link and they will be added at some point. diff --git a/TODO.md b/TODO.md index a2d756f8e..893233dea 100644 --- a/TODO.md +++ b/TODO.md @@ -1,15 +1,15 @@ Performance: -* for scrollback, investigate using segmented list for sufficiently large +- for scrollback, investigate using segmented list for sufficiently large scrollback scenarios. -* Loading fonts on startups should probably happen in multiple threads -* `deleteLines` is very, very slow which makes scroll region benchmarks terrible +- Loading fonts on startups should probably happen in multiple threads +- `deleteLines` is very, very slow which makes scroll region benchmarks terrible Correctness: -* test wrap against wraptest: https://github.com/mattiase/wraptest +- test wrap against wraptest: https://github.com/mattiase/wraptest - automate this in some way -* Charsets: UTF-8 vs. ASCII mode +- Charsets: UTF-8 vs. ASCII mode - we only support UTF-8 input right now - need fallback glyphs if they're not supported - can effect a crash using `vttest` menu `3 10` since it tries to parse @@ -17,13 +17,13 @@ Correctness: Improvements: -* scrollback: configurable +- scrollback: configurable Mac: -* Preferences window +- Preferences window Major Features: -* Bell -* Sixels: https://saitoha.github.io/libsixel/ +- Bell +- Sixels: https://saitoha.github.io/libsixel/ diff --git a/docs/sequences.md b/docs/sequences.md index ea7c162eb..8cdf91ac5 100644 --- a/docs/sequences.md +++ b/docs/sequences.md @@ -1,9 +1,8 @@ # Control and Escape Sequences -⚠️ **This is super out of date. Ghostty's support is much better +⚠️ **This is super out of date. Ghostty's support is much better than this document seems. TODO to update this.** ⚠️ - This is the list of control and escape sequences known in the ecosystem of terminal emulators and their implementation status in ghostty. Note that some control sequences may never be implemented in ghostty. In these scenarios, @@ -11,35 +10,35 @@ it is noted why. Status meanings: - * ✅ - Implementation is complete and considered 100% accurate. - * ⚠️ - Implementation works, but may be missing some functionality. The - details of how well it works or doesn't are in the linked page. In many - cases, the missing functionality is very specific or esoteric. Regardless, - we don't consider a sequence a green checkmark until all known feature - interactions are complete. - * ❌ - Implementation is effectively non-functional, but ghostty continues - in the face of it (probably in some broken state). - * 💥 - Ghostty crashes if this control sequence is sent. +- ✅ - Implementation is complete and considered 100% accurate. +- ⚠️ - Implementation works, but may be missing some functionality. The + details of how well it works or doesn't are in the linked page. In many + cases, the missing functionality is very specific or esoteric. Regardless, + we don't consider a sequence a green checkmark until all known feature + interactions are complete. +- ❌ - Implementation is effectively non-functional, but ghostty continues + in the face of it (probably in some broken state). +- 💥 - Ghostty crashes if this control sequence is sent. -| ID | ASCII | Name | Status | -|:---:|:-----:|:-----|:------:| -| `ENQ` | `0x05` | [Enquiry](sequences/enq.md) | ✅ | -| `BEL` | `0x07` | [Bell](sequences/bel.md) | ❌ | -| `BS` | `0x08` | [Backspace](sequences/bs.md) | ⚠️ | -| `TAB` | `0x09` | [Tab](sequences/tab.md) | ⚠️ | -| `LF` | `0x0A` | [Linefeed](sequences/lf.md) | ⚠️ | -| `VT` | `0x0B` | [Vertical Tab](sequences/vt.md) | ✅ | -| `FF` | `0x0C` | [Form Feed](sequences/ff.md) | ✅ | -| `CR` | `0x0D` | [Carriage Return](sequences/cr.md) | ⚠️ | -| `SO` | `0x0E` | [Shift Out](#) | ❌ | -| `SI` | `0x0F` | [Shift In](#) | ❌ | -| `CAN` | `0x18` | [Cancel Parsing](sequences/can.md) | ✅ | -| `SUB` | `0x1A` | [Cancel Parsing (Alias)](sequences/can.md) | ✅ | -| `IND` | `ESC D` | [Index](sequences/ind.md) | ✅ | -| `NEL` | `ESC E` | [Next Line](sequences/nel.md) | ✅ | -| `HTS` | `ESC H` | [Horizontal Tab Set](sequences/hts.md) | ✅ | -| `RI` | `ESC M` | [Reverse Index](sequences/ri.md) | ⚠️ | -| `SS2` | `ESC N` | [Single Shift 2](#) | ❌ | -| `SS3` | `ESC O` | [Single Shift 3](#) | ❌ | -| `SPA` | `ESC V` | [Start Protected Area](#) | ❌ | -| `EPA` | `ESC W` | [End Protected Area](#) | ❌ | +| ID | ASCII | Name | Status | +| :---: | :-----: | :----------------------------------------- | :----: | +| `ENQ` | `0x05` | [Enquiry](sequences/enq.md) | ✅ | +| `BEL` | `0x07` | [Bell](sequences/bel.md) | ❌ | +| `BS` | `0x08` | [Backspace](sequences/bs.md) | ⚠️ | +| `TAB` | `0x09` | [Tab](sequences/tab.md) | ⚠️ | +| `LF` | `0x0A` | [Linefeed](sequences/lf.md) | ⚠️ | +| `VT` | `0x0B` | [Vertical Tab](sequences/vt.md) | ✅ | +| `FF` | `0x0C` | [Form Feed](sequences/ff.md) | ✅ | +| `CR` | `0x0D` | [Carriage Return](sequences/cr.md) | ⚠️ | +| `SO` | `0x0E` | [Shift Out](#) | ❌ | +| `SI` | `0x0F` | [Shift In](#) | ❌ | +| `CAN` | `0x18` | [Cancel Parsing](sequences/can.md) | ✅ | +| `SUB` | `0x1A` | [Cancel Parsing (Alias)](sequences/can.md) | ✅ | +| `IND` | `ESC D` | [Index](sequences/ind.md) | ✅ | +| `NEL` | `ESC E` | [Next Line](sequences/nel.md) | ✅ | +| `HTS` | `ESC H` | [Horizontal Tab Set](sequences/hts.md) | ✅ | +| `RI` | `ESC M` | [Reverse Index](sequences/ri.md) | ⚠️ | +| `SS2` | `ESC N` | [Single Shift 2](#) | ❌ | +| `SS3` | `ESC O` | [Single Shift 3](#) | ❌ | +| `SPA` | `ESC V` | [Start Protected Area](#) | ❌ | +| `EPA` | `ESC W` | [End Protected Area](#) | ❌ | diff --git a/docs/sequences/bel.md b/docs/sequences/bel.md index 753e93f08..3ee7a4445 100644 --- a/docs/sequences/bel.md +++ b/docs/sequences/bel.md @@ -1,24 +1,24 @@ # Bell -| | | -| --- | --- | +| | | +| ---- | ------ | | Text | | -| Hex | `0x07` | +| Hex | `0x07` | Rings a "bell" to alert the operator to some condition. ## Implementation Details - * ghostty logs "BELL" +- ghostty logs "BELL" ## TODO - * Add a configurable visual bell -- common in most terminal emulators -- - to flash the border. - * Mark the window as requesting attention, most operating systems support - this. For example, Windows windows will flash in the toolbar. - * Support an audible bell. +- Add a configurable visual bell -- common in most terminal emulators -- + to flash the border. +- Mark the window as requesting attention, most operating systems support + this. For example, Windows windows will flash in the toolbar. +- Support an audible bell. ## References - * https://vt100.net/docs/vt100-ug/chapter3.html +- https://vt100.net/docs/vt100-ug/chapter3.html diff --git a/docs/sequences/bs.md b/docs/sequences/bs.md index a0a02c312..80835947e 100644 --- a/docs/sequences/bs.md +++ b/docs/sequences/bs.md @@ -1,9 +1,9 @@ # Backspace -| | | -| --- | --- | +| | | +| ---- | ------ | | Text | | -| Hex | `0x08` | +| Hex | `0x08` | Move the cursor left one cell. @@ -11,9 +11,9 @@ TODO: Details about how this interacts with soft wrapping. ## Implementation Details - * ghostty implements this naively as `cursor.x -|= 1` (`-|=` being a - saturating subtraction). +- ghostty implements this naively as `cursor.x -|= 1` (`-|=` being a + saturating subtraction). ## TODO - * Soft wrap integration +- Soft wrap integration diff --git a/docs/sequences/can.md b/docs/sequences/can.md index d601505a7..d2f5236ba 100644 --- a/docs/sequences/can.md +++ b/docs/sequences/can.md @@ -1,9 +1,9 @@ # Cancel Parsing -| | | -| --- | --- | -| Text | | -| Hex | `0x18` or `0x1A` | +| | | +| ---- | ---------------- | +| Text | | +| Hex | `0x18` or `0x1A` | Cancels sequence parsing. Any partially completed sequence such as `ESC` can send `0x18` and revert back to an unparsed state. The sequence characters diff --git a/docs/sequences/cr.md b/docs/sequences/cr.md index 763b02b1a..e5ba913b7 100644 --- a/docs/sequences/cr.md +++ b/docs/sequences/cr.md @@ -1,13 +1,13 @@ # Carriage Return -| | | -| --- | --- | +| | | +| ---- | ------ | | Text | | -| Hex | `0x0D` | +| Hex | `0x0D` | Moves the cursor to the left-most column and resets any pending wrap flags. ## TODO - * Integration with left/right scrolling margins - * Integration with origin mode +- Integration with left/right scrolling margins +- Integration with origin mode diff --git a/docs/sequences/enq.md b/docs/sequences/enq.md index dae4cbbe6..f6180d72f 100644 --- a/docs/sequences/enq.md +++ b/docs/sequences/enq.md @@ -1,21 +1,21 @@ # Enquiry (Answerback) -| | | -| --- | --- | +| | | +| ---- | ------ | | Text | | -| Hex | `0x05` | +| Hex | `0x05` | Sends an answerback string. In the VT100, this was configurable by the operator. ## Implementation Details - * ghostty always sends `""` +- ghostty always sends `""` ## TODO - * Make the answerback configurable +- Make the answerback configurable ## References - * https://vt100.net/docs/vt100-ug/chapter3.html +- https://vt100.net/docs/vt100-ug/chapter3.html diff --git a/docs/sequences/ff.md b/docs/sequences/ff.md index c5ead80fe..b8a25048d 100644 --- a/docs/sequences/ff.md +++ b/docs/sequences/ff.md @@ -1,8 +1,8 @@ # Form Feed -| | | -| --- | --- | +| | | +| ---- | ------ | | Text | | -| Hex | `0x0C` | +| Hex | `0x0C` | Equivalent to [linefeed](lf.md). diff --git a/docs/sequences/hts.md b/docs/sequences/hts.md index a0f65ad99..451957a9d 100644 --- a/docs/sequences/hts.md +++ b/docs/sequences/hts.md @@ -1,7 +1,7 @@ # Horizontal Tab Set -| | | -| --- | --- | +| | | +| ---- | ----------- | | Text | `ESC H` | | Hex | `0x18 0x48` | diff --git a/docs/sequences/ind.md b/docs/sequences/ind.md index 2d9182e8b..dc1b9c077 100644 --- a/docs/sequences/ind.md +++ b/docs/sequences/ind.md @@ -1,7 +1,7 @@ # Index -| | | -| --- | --- | +| | | +| ---- | ----------- | | Text | `ESC D` | | Hex | `0x18 0x44` | @@ -10,10 +10,10 @@ if necessary. This always unsets the pending wrap state. If the cursor is currently outside the scrolling region: - * move the cursor down one line if it is not on bottom line of the screen. +- move the cursor down one line if it is not on bottom line of the screen. If the cursor is inside the scrolling region: - * If the cursor is on the bottom-most line of the screen: invoke - [scroll up](su.md) with the value `1`. - * Else: move the cursor one line down. +- If the cursor is on the bottom-most line of the screen: invoke + [scroll up](su.md) with the value `1`. +- Else: move the cursor one line down. diff --git a/docs/sequences/lf.md b/docs/sequences/lf.md index 80e11f325..a36472415 100644 --- a/docs/sequences/lf.md +++ b/docs/sequences/lf.md @@ -1,12 +1,12 @@ # Linefeed -| | | -| --- | --- | +| | | +| ---- | ------ | | Text | | -| Hex | `0x0A` | +| Hex | `0x0A` | Invoke [Index](ind.md). ## TODO - * Linefeed mode (mode 20) +- Linefeed mode (mode 20) diff --git a/docs/sequences/nel.md b/docs/sequences/nel.md index 978fcc10a..39691789f 100644 --- a/docs/sequences/nel.md +++ b/docs/sequences/nel.md @@ -1,7 +1,7 @@ # Index -| | | -| --- | --- | +| | | +| ---- | ----------- | | Text | `ESC E` | | Hex | `0x18 0x45` | diff --git a/docs/sequences/ri.md b/docs/sequences/ri.md index 1192ca598..88ba96fe1 100644 --- a/docs/sequences/ri.md +++ b/docs/sequences/ri.md @@ -1,7 +1,7 @@ # Reverse Index -| | | -| --- | --- | +| | | +| ---- | ----------- | | Text | `ESC M` | | Hex | `0x18 0x4D` | @@ -9,13 +9,13 @@ Reverse [index](ind.md). This unsets the pending wrap state. If the cursor is outside of the scrolling region: - * move the cursor one line up unless it is the top-most line of the screen. +- move the cursor one line up unless it is the top-most line of the screen. If the cursor is inside the scrolling region: - * If the cursor is on the top-most line: invoke [scroll down](#) with value `1` - * Else: move the cursor one line up. +- If the cursor is on the top-most line: invoke [scroll down](#) with value `1` +- Else: move the cursor one line up. ## TODO - * Scroll region edge cases +- Scroll region edge cases diff --git a/docs/sequences/tab.md b/docs/sequences/tab.md index 8ba00e4d6..c186289ee 100644 --- a/docs/sequences/tab.md +++ b/docs/sequences/tab.md @@ -1,9 +1,9 @@ # Tab -| | | -| --- | --- | +| | | +| ---- | ------ | | Text | | -| Hex | `0x09` | +| Hex | `0x09` | Move the cursor right to the next tab stop. @@ -17,5 +17,5 @@ Initially, tab stops are set on every 8th column. ## TODO - * Integration with left/right margins of the scrolling region. - * How does horizontal tab interact with the pending wrap state? +- Integration with left/right margins of the scrolling region. +- How does horizontal tab interact with the pending wrap state? diff --git a/docs/sequences/vt.md b/docs/sequences/vt.md index 85e385c38..f721741b3 100644 --- a/docs/sequences/vt.md +++ b/docs/sequences/vt.md @@ -1,8 +1,8 @@ # Vertical Tab -| | | -| --- | --- | +| | | +| ---- | ------ | | Text | | -| Hex | `0x0B` | +| Hex | `0x0B` | Equivalent to [linefeed](lf.md). diff --git a/test/README.md b/test/README.md index ef59fb12e..8b59aa062 100644 --- a/test/README.md +++ b/test/README.md @@ -38,4 +38,3 @@ the full test suite against only a single terminal emulator. This test suite expects the `ghostty` binary to be in _this directory_. You can manually copy it into place. Each time you modify the binary, you must rebuild the Docker image. -