emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

module: add :tools collab

Browse source 
Add a collaborative editing module, powered by crdt.el.

Ref: https://code.librehq.com/qhong/crdt.el
Co-authored-by: Arte Ebrahimi <arteebrahimi@gmail.com>
This commit is contained in:
Jonathan Ming 2023-07-24 10:29:46 -07:00 • committed by GitHub
parent 177157b044
commit 9245a347a4
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 181 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

24
modules/config/default/+evil-bindings.el
View file

@ -505,6 +505,30 @@
:desc "Unicode" "u" #'insert-char
:desc "From clipboard" "y" #'+default/yank-pop)
;;; <leader> l --- live share/collab
;;; TODO Do you like this location for this map? This was the best idea we
;;; could come up with, but we're happy to move it if there's a better
;;; place! Also not sure if we're allowed to say "live share" since that's
;;; a blatant ripoff of VS Code's name for this feature
(:when (modulep! :tools collab)
(:prefix-map ("l" . "live share/collab")
:desc "Switch to a shared buffer" "b" #'crdt-switch-to-buffer
:desc "Connect to a session" "c" #'crdt-connect
:desc "Disconnect from session" "d" #'crdt-disconnect
:desc "Toggle following user's cursor" "f" #'crdt-follow-user
:desc "Stop following user if any" "F" #'crdt-stop-follow
:desc "Goto another user's cursor" "g" #'crdt-goto-user
:desc "List shared buffers" "i" #'crdt-list-buffers
:desc "Kick a user (host only)" "k" #'crdt-kill-user
:desc "List sessions" "l" #'crdt-list-sessions
:desc "Share current buffer" "s" #'crdt-share-buffer
:desc "Stop sharing current buffer" "S" #'crdt-stop-share-buffer
:desc "List connected users" "u" #'crdt-list-users
:desc "Stop a session (host only)" "x" #'crdt-stop-session
:desc "Copy URL of current session" "y" #'crdt-copy-url
:desc "Goto next user's cursor" "]" #'crdt-goto-next-user
:desc "Goto previous user's cursor" "[" #'crdt-goto-prev-user))
;;; <leader> n --- notes
(:prefix-map ("n" . "notes")
:desc "Search notes for symbol" "*" #'+default/search-notes-for-symbol-at-point

138
modules/tools/collab/README.org Normal file
View file

@ -0,0 +1,138 @@
#+TITLE: tools/collab
#+DATE: September 2, 2022
#+SINCE: v3.0.0
#+STARTUP: inlineimage nofold
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#with-tunnel][With =+tunnel=]]
- [[#macos][macOS]]
- [[#linux][Linux]]
- [[#windows][Windows]]
- [[#features][Features]]
- [[#keybindings][Keybindings]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
- [[#people-outside-my-lan-cant-connect-to-the-collab-session-im-hosting][People outside my LAN can't connect to the collab session I'm hosting]]
- [[#i-got-an-error-saying-something-including-crdtel-protocol][I got an error saying something including "crdt.el protocol"]]
* Description
This module adds collaborative editing via the [[https://code.librehq.com/qhong/crdt.el][crdt]] plugin.
** Maintainers
+ [[https://github.com/artenator][@artenator]]
+ [[https://github.com/jming422][@jming422]]
** Module Flags
+ =+tunnel= Enables TCP forwarding over the [[https://tox.chat/][Tox]] protocol so that a collaborative
editing session can be established between machines that are behind a NAT.
** Plugins
+ [[https://code.librehq.com/qhong/crdt.el][crdt]]
* Prerequisites
With no flags, this module requires nothing else to work. The =+tunnel= flag has one dependency:
** With =+tunnel=
Tunneling requires the [[https://github.com/gjedeer/tuntox][tuntox]] program, which is used to establish TCP
connections to your collaborators over the Tox peer-to-peer networking protocol.
*** macOS
tuntox can be installed from Homebrew:
#+BEGIN_SRC bash
brew install tuntox
#+END_SRC
*** Linux
You can download the tuntox binary for most architectures from its [[https://github.com/gjedeer/tuntox/releases][Releases]] page
on GitHub, and it can be found in some [[https://repology.org/project/tuntox/versions][package manager repositories]] as well.
*** Windows
Tuntox is currently not supported on Windows, so Windows users cannot use the
=+tunnel= flag and must choose another networking solution, such as a VPN. For
more options, see [[*People outside my LAN can't connect to the collab session I'm hosting][this Troubleshooting entry]].
* Features
+ Start a collaborative editing session in one of your buffers with =M-x
crdt-share-buffer= and following the prompts.
+ If you're using =+tunnel=, get the sharable URL of your session using =M-x
crdt-copy-url=. If not using =+tunnel=, then instead of a URL, others can
connect using your public IP address and chosen TCP port number (default port
is 6530)
+ Others can connect to your session using =M-x crdt-connect= and following the
prompts to pass in your tunnel URL or IP address and port
+ Once connected, some commands you can use are:
+ =crdt-list-buffers= to list shared buffers. Use this after =crdt-connect= to
open shared buffers for editing!
+ =crdt-share-buffer= Start a new collaboration session, or add more buffers
to an existing session. Once a session has started, both the host and
clients can use this function to share buffers!
+ =crdt-goto-user= to jump to another collaborator
+ =crdt-follow-user= / =crdt-stop-follow= to toggle following another
collaborator
+ =crdt-visualize-author-mode= to add colors to regions of the buffer,
visualizing who most recently edited each part of the buffer
+ =crdt-stop-session= (host) / =crdt-disconnect= (client) to exit the collab
session
** Keybindings
When this module is enabled, the `SPC l` leader keymap becomes available, making most of the above functions and more available under that prefix:
| Binding | Description |
|-----------+---------------------------------------------------------|
| =SPC l b= | Switch to a shared buffer |
| =SPC l c= | Connect to a session |
| =SPC l d= | Disconnect from session |
| =SPC l f= | Toggle following another user's cursor |
| =SPC l F= | Stop following user if any |
| =SPC l g= | Goto another user's cursor |
| =SPC l i= | List shared buffers |
| =SPC l k= | Kick a user (host only) |
| =SPC l l= | List sessions |
| =SPC l s= | Share current buffer, optionally starting a new session |
| =SPC l S= | Stop sharing current buffer |
| =SPC l u= | List connected users |
| =SPC l x= | Stop a session (host only) |
| =SPC l y= | Copy URL of current session |
| =SPC l ]= | Goto next user's cursor |
| =SPC l [= | Goto previous user's cursor |
* Configuration
This list is not exhaustive; for the full list of config options, type =SPC h V
crdt-= after loading the module.
| Custom variable | Default | Function |
|-----------------------------+--------------------------+-------------------------------------------------------------------------------------------|
| crdt-ask-for-name | t | Set to nil to always use =crdt-default-name= as your name without asking |
| crdt-default-name | ~(user-full-name)~ | Your display name in collaboration sessions |
| crdt-tuntox-executable | "tuntox" | Path to the tuntox binary |
| crdt-tuntox-password-in-url | t if =+tunnel=, else nil | Set to t to put your session password (in plaintext) into the URL made by =crdt-copy-url= |
* Troubleshooting
** People outside my LAN can't connect to the collab session I'm hosting
Without =+tunnel= enabled, on most home/work networks you will be unable to have
others join you from across the Internet unless you set something up to
facilitate the connection between collaborators.
You have a lot of options here, but some of the most common are:
+ Enable the =+tunnel= flag to tunnel your traffic using the [[https://tox.chat/][Tox]] peer-to-peer
networking protocol
+ Use a VPN
+ Use a non-peer-to-peer tunneling method, such as Teredo. One free software
implementation of this method is called [[https://www.remlab.net/miredo/][Miredo]]
+ Use a TCP reverse proxy server, such as [[https://ngrok.com/][ngrok]]
+ Use SSH port forwarding, if you have access to a server with a public network
address
** I got an error saying something including "crdt.el protocol"
All collaborators must be using the same version of the crdt package in order to
guarantee stability & support for all features. These types of errors should not
occur if everyone is up to date, so ensure that all collaborators have upgraded
Doom Emacs to the latest version and have not pinned =crdt=.

8
modules/tools/collab/config.el Normal file
View file

@ -0,0 +1,8 @@
;;; tools/collab/config.el -*- lexical-binding: t; -*-
(use-package! crdt
:commands (crdt-share-buffer crdt-connect)
:init
(when (featurep! +tunnel)
(setq crdt-use-tuntox t)
(setq crdt-tuntox-password-in-url t)))

4
modules/tools/collab/doctor.el Normal file
View file

@ -0,0 +1,4 @@
;;; tools/collab/doctor.el -*- lexical-binding: t; -*-
(when (and (featurep! +tunnel) (not (executable-find "tuntox")))
(warn! "Couldn't find tuntox command. This needs to be on your path for the +tunnel flag to work properly."))

6
modules/tools/collab/packages.el Normal file
View file

@ -0,0 +1,6 @@
;; -*- no-byte-compile: t; -*-
;;; tools/collab/packages.el
(package! crdt
:recipe (:host nil :repo "https://code.librehq.com/qhong/crdt.el")
:pin "3ba890658d657db5d6aaedd5c2a78b6f93a5f139")

1
templates/init.example.el
View file

@ -87,6 +87,7 @@
:tools
;;ansible
;;biblio ; Writes a PhD for you (citation needed)
;;collab ; buffers with friends
;;debugger ; FIXME stepping through code, to help you add bugs
;;direnv
;;docker