Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs #6

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added .gitbook/assets/add_next_occurrence_skip.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added .gitbook/assets/adding_a_line.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added .gitbook/assets/select_all_occurrences.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added .gitbook/assets/select_current_line.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added .gitbook/assets/undo_cursor.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
9 changes: 9 additions & 0 deletions SUMMARY.md
Original file line number Diff line number Diff line change
@@ -11,6 +11,7 @@
* [Modal editing](get-started/modal-editing.md)
* [Remote Development](get-started/remote-development.md)
* [Themes](get-started/themes.md)
* [Installation With Package Manager](get-started/installing-with-package-manager.md)

## Features

@@ -19,6 +20,14 @@

## Development

* [Contributing](development/contributing.md)
* [Contributing Guide For Developers](development/new-contributor-guide-developer.md)
* [Contributoring Guide For Users](new-contributor-guide-user.md)
* [Building from source](development/building-from-source.md)
* [Architecture](development/architecture.md)
* [Plugin Development](development/plugin-development.md)
* [Theme](development/theme.md)

## FAQ

* [Why Lapce?](faq/why-lapce.md)
4 changes: 2 additions & 2 deletions development/architecture.md
Original file line number Diff line number Diff line change
@@ -4,12 +4,12 @@

## Frontend

The frontend uses [Druid](https://github.com/linebender/druid) for the GUI of Lapce. Druid is a data first GUI framework. And all the state and logic are in `lapce-data` sub crate, e.g., file buffers, editor tabs, cursor, etc. The UI widgets tree, layout, and rendering logic are in `lapce-ui` sub crate, including all the UI related stuff, e.g., keyboard and mouse events, file dialogs, context menus etc. 
The frontend uses [Druid](https://github.com/linebender/druid) for the GUI of Lapce. Druid is a data first GUI framework. And all the state and logic are in `lapce-data` sub crate, e.g., file buffers, editor tabs, cursor, etc. The UI widgets tree, layout, and rendering logic are in `lapce-ui` sub crate, including all the UI related stuff, e.g., keyboard and mouse events, file dialogs, context menus etc.

## Proxy

The `lapce-proxy` sub crate provides the interface between the frontend, and the file system, plugins and lsp servers, so Lapce talks to files, plugins, lsp servers through the proxy. The reason for that is to provide the ability for remote development. In remote development mode, the `lapce-proxy` binary runs in the remote box, so that it can read files in the remote box, and the plugins and lsp servers can run in the remote box to utilise the power of the remote box.

## File Editing

Here is the flow of a typical file editing process. When you open a file in the GUI, `lapce-data` talks to `lapce-proxy` which reads the file from local disk and responds with the content of the file. `lapce-data` stores the file content locally. When `lapce-ui` receives a keyboard event, it modifies the file content in `lapce-data`, and only sends the change of that edit to `lapce-proxy.` `lapce-proxy` receives the change, and applies the change locally which make the file content in sync. When you save the file in the GUI, `lapce-data` sends the file save request to `lapce-proxy`, and `lapce-proxy` saves the file to the local disk. 
Here is the flow of a typical file editing process. When you open a file in the GUI, `lapce-data` talks to `lapce-proxy` which reads the file from local disk and responds with the content of the file. `lapce-data` stores the file content locally. When `lapce-ui` receives a keyboard event, it modifies the file content in `lapce-data`, and only sends the change of that edit to `lapce-proxy.` `lapce-proxy` receives the change, and applies the change locally which make the file content in sync. When you save the file in the GUI, `lapce-data` sends the file save request to `lapce-proxy`, and `lapce-proxy` saves the file to the local disk.
34 changes: 34 additions & 0 deletions development/building-from-source.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
## Building from source

It is easy to build Lapce from source on a GNU/Linux distribution. Cargo handles the build process, all you need to do, is ensure the correct dependencies are installed.

1. Install the Rust compiler and Cargo using [`rustup.rs`](https://rustup.rs/). If you already have the toolchain, ensure you are using version 1.64 or higher.

2. Install dependencies for your operating system:

#### Ubuntu
```sh
sudo apt install clang libxkbcommon-x11-dev pkg-config libvulkan-dev
```
#### Fedora
```sh
sudo dnf install clang libxkbcommon-x11-devel libxcb-devel vulkan-loader-devel
```

3. Clone this repository (this command will clone to your home directory):
```sh
git clone https://github.com/lapce/lapce.git ~/lapce
```

4. `cd` into the repository, and run the build command with the release flag
```sh
cd ~/lapce
```

```sh
cargo build --release
```

> If you use a different distribution, and are having trouble finding appropriate dependencies, let us know in an issue!

Once Lapce is compiled, the executable will be available in `target/release/lapce`.
23 changes: 23 additions & 0 deletions development/new-contributor-guide-developer.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# New Contributor Guide **Developers**

This document contains some useful resources for anyone wishing to contribute to the Lapce project by contributing code.

## Quick Start

1. Get an overview of the architecture from [`faq/why-lapce.md`](why-lapce.md) and [Architecture](development/architecture.md).

2. Explore the rope data structure, a key part of Lapce's architecture. The crate used is [xi_rope](https://crates.io/crates/xi-rope).

3. Review both open and closed [issues](https://github.com/lapce/lapce/issues), there may be others working on a similar feature.

4. [Get cracking](https://dictionary.cambridge.org/dictionary/english/get-cracking)!

5. Be aware that unless you explicitly state otherwise, contributions you make to this project will be under the Apache License Version 2.

## Resources

The [Wikipedia article on ropes](https://en.wikipedia.org/wiki/Rope_(data_structure)) provides an overview of the data structure.

For some context, also see [Ropes: an Alternative to Strings](https://www.cs.tufts.edu/comp/150FP/archive/hans-boehm/ropes.pdf) by Boehm, Atkinson, and Plass.


23 changes: 23 additions & 0 deletions development/new-contributor-guide-user.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# New Contributor Guide **Users**

This document contains some useful resources for anyone wishing to contribute to the Lapce project by suggesting improvements, requesting features, or supporting the community. Where it says _question_ in this document, it can also apply to _suggestions_, _requests_, etc.

## Quick Start

1. Open a text editor

2. Write out your question (or request, or suggestion).

3. _Revise_ your question

4. Choose where to post your question

5. Post it!

## Resources

For general information about open source software, [see these FAQs](https://opensource.org/faq) by the Open Source Initiative.

We don't have a specified code of conduct yet, but for some reasonable guidelines see the [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/).

[This guide](http://www.catb.org/~esr/faqs/smart-questions.html), by Eric Steven Raymond, is about how to ask excellent questions. You can apply the same techniques (such as _Use meaningful, specific subject headers_) to suggestions and bug reports. The more specific (and helpful!) you can be with your question, the more it helps us to provide a solution.
2 changes: 1 addition & 1 deletion development/plugin-development.md
Original file line number Diff line number Diff line change
@@ -14,4 +14,4 @@ Then in the plugin folder, run

`volts publish`

It should publish the plugin to the registry. 
It should publish the plugin to the registry.
6 changes: 3 additions & 3 deletions development/theme.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
# Theme

Developing a theme plugin for Lapce is easy. Firstly [open settings](../get-started/settings.md), and you can change colours in theme settings, and change the UI appearance in UI Settings. 
Developing a theme plugin for Lapce is easy. Firstly [open settings](../get-started/settings.md), change colours in theme settings, then change the UI appearance in UI Settings.

<figure><img src="../.gitbook/assets/theme_settings.png" alt=""><figcaption></figcaption></figure>

[Open command palette](../get-started/command-palette.md), choose the command `Export current settings to a theme file`, it will generate the theme file for you.

<figure><img src="../.gitbook/assets/theme_export_file.png" alt=""><figcaption></figcaption></figure>

Change the name of the theme, and save the file.&#x20;
Change the name of the theme, and save the file.

To create a theme plugin for Lapce, follow the format of this repo [https://github.com/lapce/atom-one](https://github.com/lapce/atom-one), the important files are `volt.toml` and the theme file.&#x20;
To create a theme plugin for Lapce, follow the format of this repo [https://github.com/lapce/atom-one](https://github.com/lapce/atom-one), the important files are `volt.toml` and the theme file.

After that is done, you can [publish it](plugin-development.md#publish-plugin).
31 changes: 31 additions & 0 deletions faq/why-lapce.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
A word from the [original creator](https://github.com/dzhou121) on the original inspiration and idea of Lapce
---

I'm a Vim fan. After years of using it, I started to customize it like everybody else. I thought I had something that worked quite well until I hit one problem. My linter sometimes took seconds to check the code, and it would freeze Vim because Vim didn't have asynchronous support. I looked around; I found NeoVim and problem solved. Happy days.

But there was always this one thing I couldn't solve. I want to make Vim pretty. I tried all kinds of themes. Tried all kinds of status bar plugins with icons in it. File explorers with file icons in them. But no, I also wanted a 1px vertical split bar, not the thick colored one or the dashed line drawn with pipe characters. After hours and hours of search, it occurred to me that it's impossible to do. Again NeoVim was the savior. It introduced external UI. The idea was that NeoVim splits the UI and the backend. The backend emits events to the UI, and the UI draws them. I couldn't wait to try it out with writing a UI in Electron, with the hope that I could solve my vertical split bar dream. But I didn't because it emits the drawing events treating it as a whole canvas, and I don't get the boundary of each splits. I started to hack NeoVim code. I made it to emit split sizes and positions, and I finally can draw the bars in the UI. With joy, I also looked at emits the command modes to the UI, so I could put the command in the middle of the window. And then echo messages, status line, etc. I pushed a PR for the hacky solution(https://github.com/neovim/neovim/pull/5686). Then I hit performance issues in Electron because Javascript was not fast enough to deserialize the drawing events from NeoVim. So I wrote another UI in Go with Qt binding(https://github.com/dzhou121/gonvim).

I wanted to external more and more components in NeoVim, but I found it harder and harder, and I spotted Xi-Editor. I started to write a UI for it straightaway. Creating a code editor with Vim editing experience was the plan. There were things missing that I had to add in Xi. And working on it was so much easier because Xi was built to be the UI/backend architecture without the heritage(burden) of (Neo)Vim.

Then one day, I experienced VSCode's remote development feature, and it felt so "local". I wanted to add the feature to my code editor. Then I realized that it can't be done with NeoVim or Xi's UI/backend architecture. The reason was that (Neo)Vim/Xi backends are the editing engine, so when you put the backend to a remote machine, every keyboard input needs to be sent to it, and the backend emits the drawing events to you, which will include the network latency in everything you type. That wouldn't work. The editing logic must be tightly bound with the UI to give the best editing experience.

So the new architecture I came up with was like this:
```
UI
```
- Reads file from Proxy
- Handle keyboard/mouse events and do the edits on the file buffer
- Send the file editing delta to the proxy to keep the file in sync

```
Proxy
```
- Receive save event from UI and flush the file buffer to disk
- proxy the events between UI and the plugins

```
Plugin
```
- Communicate with UI through proxy

UI sits locally. Proxy and Plugin will be in the remote box when doing remote development. With this architecture, I can make sure the editing experience is always the best, with other considerations like syntax highlighting being done in a different thread, so nothing blocks the main thread at any time. I finally had a lightning-fast and powerful code editor. (which can be beautiful as well)
29 changes: 29 additions & 0 deletions features/multiple-cursor.md
Original file line number Diff line number Diff line change
@@ -7,6 +7,10 @@ To add the line above or below to the selection, use:
`Ctrl+Alt+ArrowUp` and `Ctrl+Alt+ArrowDown` For Windows and Linux

`Meta+Alt+ArrowUp` and `Meta+Alt+ArrowDown` For macOS
<details>
<summary>Demo</summary>
<figure><img src="../.gitbook/assets/adding_a_line.gif"alt=""><figcaption></figcaption></figure>
</details>

## Insert cursors at end of line

@@ -22,13 +26,22 @@ To select lines that current cursors are at, use:

`Meta+L` For macOS

<details>
<summary>Demo</summary>
<figure><img src="../.gitbook/assets/select_current_line.gif"alt=""><figcaption></figcaption></figure>
</details>

## Select all occurrences at the cursor

To select all occurrences of the current selection, or the word the cursor at, use:

`Ctrl+Shift+L` For Windows and Linux

`Meta+Shift+L` For macOS
<details>
<summary>Demo</summary>
<figure><img src="../.gitbook/assets/select_all_occurrences.gif"alt=""><figcaption></figcaption></figure>
</details>

## Add next occurrence

@@ -38,16 +51,32 @@ To add the next occurrence of the current selection, or the work the cursor at,

`Meta+D` For macOS


<details>
<summary>Demo</summary>
<figure><img src="../.gitbook/assets/add_next_occurrence_current_selection.gif"alt=""><figcaption></figcaption></figure>
</details>

Or if you want to skip the next occurrence, use:

`Ctrl+K Ctrl+D` For Windows and Linux

`Meta+K Meta+D` For macOS

<details>
<summary>Demo</summary>
<figure><img src="../.gitbook/assets/add_next_occurrence_skip.gif"alt=""><figcaption></figcaption></figure>
</details>

## Undo cursor

To undo the last cursor action, use:

`Ctrl+U` For Windows and Linux

`Meta+U` For macOS

<details>
<summary>Demo</summary>
<figure><img src="../.gitbook/assets/undo_cursor.gif"alt=""><figcaption></figcaption></figure>
</details>
79 changes: 79 additions & 0 deletions get-started/installing-with-package-manager.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
## Installation With Package Manager

### Arch Linux

There is an community package that can be installed with `pacman`:

```bash
sudo pacman -Syu lapce
```

### Fedora
```bash
sudo dnf copr enable titaniumtown/lapce
sudo dnf install lapce
```

### Flatpak

Lapce is available as a flatpak [here](https://flathub.org/apps/details/dev.lapce.lapce)

```bash
flatpak install flathub dev.lapce.lapce
```

### Gentoo

Lapce is available in Gentoos user repository GURU.
If the GURU is not activated, it can be with:

```bash
emerge --ask app-eselect/eselect-repository # install eselect repository
eselect repository enable guru
emaint sync -r guru
```

After activating and syncing the GURU repository, lapce can be installed with

```bash
emerge app-editors/lapce
```

### Homebrew

```bash
brew install lapce
```

### nixpkgs

You can find the packages [here](https://search.nixos.org/packages?channel=unstable&show=lapce&from=0&size=50&sort=relevance&type=packages&query=lapce):

```bash
# try with nix-shell
nix-shell -p lapce

# on NixOS
nix-env -iA nixos.lapce

# on non-NixOS installs, including macOS
nix-env -iA nixpkgs.lapce

# only if nix.settings.experimental-features is set to both "nix-command" and "flakes"
# WARNING: THIS BREAKS nix-env, PROCEED AT YOUR OWN RISK. THIS ALSO INSTALLS FROM UNSTABLE BRANCH.
nix profile install nixpkgs#hello
```

### Scoop

```bash
scoop install lapce
```

### winget

You can find the packages [here](https://github.com/microsoft/winget-pkgs/tree/master/manifests/l/Lapce/Lapce):

```bash
winget install lapce
```
4 changes: 2 additions & 2 deletions get-started/setup.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Setup

Lapce currently supports Linux, Windows and macOS. Simply download [Lapce](https://lapce.dev/#downloads-all) for your platform and install it if needed.&#x20;
Lapce currently supports Linux, Windows and macOS. Simply [download Lapce](https://lapce.dev/#downloads-all) for your platform and install it as needed. For package managers, please see [Installation With Package Manager](get-started/installing-with-package-manager.md).

<figure><img src="../.gitbook/assets/first_launch.png" alt=""><figcaption></figcaption></figure>

@@ -20,6 +20,6 @@ Alternatively, you can also choose `Open recent workspace` in the dropdown menu,

## Work with files

After you opened a workspace, the files will appear in the file explorer on the left panel. You can navigate the files and folder there and open them by clicking on the file name. Alternatively, you can use `Go To File` feature (`Cmd`+`p` on macOS and `Ctrl`+`p` on Linux and Windows) to fuzzy search files in your workspace for quicker opening.&#x20;
After you opened a workspace, the files will appear in the file explorer on the left panel. You can navigate the files and folder there and open them by clicking on the file name. Alternatively, you can use `Go To File` feature (`Cmd`+`p` on macOS and `Ctrl`+`p` on Linux and Windows) to fuzzy search files in your workspace for quicker opening.

<figure><img src="../.gitbook/assets/workspace_go_to_file.png" alt=""><figcaption></figcaption></figure>