daniel/emacs
1
2
Fork 0
Code Issues 7 Pull Requests Projects Releases Wiki Activity

update eaf package

Browse Source
This commit is contained in:
Daniel Weschke
2021-01-30 14:52:51 +01:00
parent 84eb4929ee
commit 5207af83cb
4981 changed files with 11795 additions and 761570 deletions
Download Patch File Download Diff File Expand all files Collapse all files

161
lisp/emacs-application-framework/README.zh-CN.md
View File

@@ -6,7 +6,7 @@ EAF 是一个全新的图形应用框架，通过扩展Emacs的多媒体能力
## EAF 应用展示
EAF是一个可编程扩展的框架，你可以开发自己的Qt5应用并集成在Emacs中。
| 浏览器 | Markdown预览程序 |
| 浏览器 | Markdown预览(支持Mermaid和PlantUML) |
| :--------: | :----: |
| <img src="./screenshot/browser.gif" width="400"> | <img src="./screenshot/markdown_previewer.gif" width="400"> |
@@ -31,7 +31,7 @@ EAF是一个可编程扩展的框架，你可以开发自己的Qt5应用并集
| <img src="./screenshot/air_share.png" width="400"> | <img src="./screenshot/org_previewer.gif" width="400"> |
| | |
| 终端模拟器 | RSS阅读器 |
| 终端模拟器 | RSS阅读器 (集成Elfeed) |
| :--------: | :------: |
| <img src="./screenshot/terminal.gif" width="400"> | <img src="./screenshot/rss_reader.gif" width="400"> |
| | |
@@ -41,92 +41,102 @@ EAF是一个可编程扩展的框架，你可以开发自己的Qt5应用并集
| <img src="./screenshot/aria2.gif" width="400"> | <img src="./screenshot/mindmap.gif" width="400"> |
| | |
| 流程图 | 笔记管理系统 |
| Jupyter | 笔记管理系统 |
| :--------: | :--------: |
| <img src="./screenshot/mermaid.gif" width="400"> | <img src="./screenshot/eaf-interleave.gif" width="400"> |
| <img src="./screenshot/jupyter.png" width="400"> | <img src="./screenshot/eaf-interleave.gif" width="400"> |
| | |
## EmacsConf2020 - Extend Emacs to Modern GUI Applications with EAF（暂无中文字幕）
- 由[MatthewZMD](https://github.com/MatthewZMD)在EmacsConf2020的演讲和demo。
- 官网（内附Q&A）: https://emacsconf.org/2020/talks/34/
- Youtube链接:
[![EmacsConf2020 - Extend Emacs to Modern GUI Applications with EAF](https://img.youtube.com/vi/HK_f8KTuR0s/0.jpg)](https://www.youtube.com/watch?v=HK_f8KTuR0s)
## 安装
1. 安装EAF依赖，对于每个依赖的解释可以在[依赖列表](#依赖列表)找到。
以下这行是针对*Archlinux*，同样的包的安装方式在别的发行版略有不同，请善用搜索引擎：
1. 下载EAF:
```Bash
yay -S python-pyqt5 python-pyqt5-sip python-pyqtwebengine python-qrcode python-feedparser python-dbus python-pyinotify python-markdown nodejs aria2 libreoffice python-pymupdf python-grip filebrowser-bin
git clone --depth=1 -b master https://github.com/manateelazycat/emacs-application-framework.git ~/.emacs.d/site-lisp/emacs-application-framework/
```
2. 使用 ```git clone``` 下载这个仓库.
```Bash
git clone https://github.com/manateelazycat/emacs-application-framework.git --depth=1
你也可以通过[Quelpa](https://github.com/quelpa/quelpa)来下载
```Emacs-lisp
(quelpa '(eaf (:fetcher github
:repo "manateelazycat/emacs-application-framework"
:files ("*"))))
```
3. 把EAF加入Emacs的 ```load-path```，然后在 `init.el` 中写入:
2. 通过`M-x install-eaf-dependencies`安装EAF依赖，
如果你更喜欢手动执行安装脚本，
- GNU/Linux用户：
```Bash
cd emacs-application-framework
chmod +x ./install-eaf.sh
./install-eaf.sh
```
- Windows用户：
```shell
>>>>>>> Update README and eaf-install-dependencies (need Windows testing)
cd emacs-application-framework
node ./install-eaf-win32.js
```
脚本里安装的每一个依赖的解释可以在[依赖列表](#依赖列表)找到。
3. 安装Elisp依赖包:
- [emacs-ctable](https://github.com/kiwanami/emacs-ctable)
- [emacs-deferred](https://github.com/kiwanami/emacs-deferred)
- [emacs-epc](https://github.com/kiwanami/emacs-epc)
- [s.el](https://github.com/magnars/s.el)
4. 从这里开始，你可以把EAF加入Emacs的 ```load-path```，然后在 `init.el` 中写入:
```Elisp
(add-to-list 'load-path "~/.emacs.d/site-lisp/emacs-application-framework/")
(require 'eaf)
```
如果你使用[use-package](https://github.com/jwiegley/use-package)，下面有一个简单的配置文件供你参考:
或者，如果你使用[use-package](https://github.com/jwiegley/use-package)，下面有一个简单的配置文件供你参考:
```Elisp
(use-package eaf
:load-path "~/.emacs.d/site-lisp/emacs-application-framework" ; Set to "/usr/share/emacs/site-lisp/eaf" if installed from AUR
:init
(use-package epc :defer t)
(use-package ctable :defer t)
(use-package deferred :defer t)
(use-package s :defer t :ensure t)
:custom
(eaf-find-alternate-file-in-dired t)
(eaf-browser-continue-where-left-off t)
:config
(eaf-setq eaf-browser-enable-adblocker "true")
(eaf-bind-key scroll_up "C-n" eaf-pdf-viewer-keybinding)
(eaf-bind-key scroll_down "C-p" eaf-pdf-viewer-keybinding)
(eaf-bind-key take_photo "p" eaf-camera-keybinding))
(eaf-bind-key take_photo "p" eaf-camera-keybinding)
(eaf-bind-key nil "M-q" eaf-browser-keybinding)) ;; unbind, see more in the Wiki
```
---
如果你使用[Chemacs](https://github.com/plexus/chemacs)， 下面是一份 `init.el`的配置示例：
```Elisp
;; An example of init.el
(defun add-subdirs-to-load-path (dir)
"Recursive add directories to `load-path'."
(let ((default-directory (file-name-as-directory dir)))
(add-to-list 'load-path dir)
(normal-top-level-add-subdirs-to-load-path)))
(add-subdirs-to-load-path "~/.emacs.d/")
(require 'eaf)
```
在安装EAF时，你仅需要修改此文件中调用函数`add-subdirs-to-load-path`的参数值，将其更改为你的EAF安装位置的绝对路径。 配置示例中的EAF是安装在`~/.emacs.d/`.
在EAF安装完成后，假设你将它安装到了`~/eaf`,你电脑中只有存放在`~/.emacs.d`的Emacs配置文件和安装的EAF，并且你电脑中安装了Chemacs，此时`.emacs-profiles.el`应该这样配置:
```Elisp
(("default" . ((user-emacs-directory . "~/.emacs.d")))
("EAF" . ((user-emacs-directory . "~/eaf"))))
```
当你想使用Chemacs打开EAF，只需在终端中执行`emacs --with-profile EAF`。
### 依赖列表
**核心** 分类代表必备依赖，这些包必须安装好EAF才能工作。其余依赖都可选，若想其使用对应的应用时，你才需要安装这些依赖。当然我们推荐先把所有依赖都安装好，等到真正使用的时候就不用再次折腾。
| 包名 | 依赖 | 解释 |
| :-------- | :------ | :------ |
| python-pyqt5, python-pyqt5-sip | 核心 | GUI图形库 |
| python-dbus | 核心 | DBus库，用于在Emacs和Python进程间通讯 |
| python-pyqtwebengine | 核心 | 基于Chromium的浏览器引擎 |
| wmctrl | 核心 | 激活Emacs窗口输入焦点 |
| python-pymupdf | PDF阅读器 | 解析PDF文件 |
| python-grip | Markdown预览 | 建立Markdown文件的HTML服务 |
| python-qrcode | 文件上传，文件下载，文字传输 | 根据文件信息生成二维码 |
| python-feedparser | RSS阅读器 | 解析RSS/Atom信息 |
| python-pyinotify | 流程图 | 监听 mmd 格式文件的变动 |
| python-markdown | 流程图 | 转换 mmd 格式为 mermaid 识别的 html 格式 |
| aria2 | 浏览器 | 下载网络文件 |
| nodejs | 终端模拟器 | 通过浏览器与本地TTY交互 |
| libreoffice | 办公文档阅读器 | 转换doc文件为pdf格式 |
| filebrowser-bin | 文件浏览器 | 在电脑和手机之间快速共享文件 |
| qtconsole | jupyter | 提供RichJupyterWidget |
| java-openjdk | Markdown 预览 | 正常渲染Markdown文档中的PlantUML代码 |
## EAF应用启动命令
| 应用名称 | 启动命令 |
@@ -144,36 +154,37 @@ git clone https://github.com/manateelazycat/emacs-application-framework.git --de
| 二维码下载文件 | `M-x eaf-file-sender-qrcode` or `eaf-file-sender-qrcode-in-dired` |
| 二维码在线浏览器 | `M-x eaf-file-browser-qrcode` |
| 无线分享 | `M-x eaf-open-airshare` 输入要分享给手机的字符串 |
| RSS新闻阅读器 | `M-x eaf-open-rss-reader` |
| 思维导图 | `M-x eaf-create-mindmap` or `M-x eaf-open-mindmap` |
| 微软Office阅读器 | `M-x eaf-open-office` |
| 流程图 | `M-x eaf-open` 输入 mmd 格式文件 |
| jupyter | `M-x eaf-open-jupyter` |
| 演示程序 | `M-x eaf-open-demo` |
- 在`dired`文件管理器中，建议绑定按键到命令 `eaf-open-this-from-dired` ，它会自动用合适的EAF应用来打开文件。
- EAF浏览器以及PDF浏览器支持Emacs内置书签操作，通过使用`M-x bookmark-set`（默认`C-x r m`）以及`M-x bookmark-bmenu-list`（默认`C-x r l`）。
```
注意：
EAF使用DBus的普通权限总线 (session bus)，请不要用 sudo 来启动EAF，root用户只能访问系统权限总线 (system bus)
```
## Wiki
强烈建议使用EAF之前浏览一遍[Wiki](https://github.com/manateelazycat/emacs-application-framework/wiki)。
Wiki包括架构设计，按键绑定，自定义选项和任务列表等文档。你还会在Wiki发现很多有用的技巧，比如Docker，Helm等，
Wiki囊括了各种你想了解的EAF相关文档，包括了：
1. 按键绑定
2. 自定义选项
3. 架构设计
4. 任务列表
你还会在Wiki发现很多有用的技巧，如Docker，Helm等，
## 常用问题
### EAF是怎么工作的？
EAF主要实现这几个功能：
1. 利用QWindow的Reparent技术来实现PyQt应用进程的窗口粘贴到Emacs对应的Buffer区域
2. 通过DBus IPC来实现Emacs进程和Python进程的控制指令和跨进程消息通讯
2. 通过Python EPC来实现Emacs进程和Python进程的控制指令和跨进程消息通讯
3. 通过Qt5的QGraphicsScene来实现镜像窗口，以对应Emacs的Buffer/Window模型
若想了解更多EAF设计背景，请看[Wiki](https://github.com/manateelazycat/emacs-application-framework/wiki/Hacking)
### EAF vs EXWM?
1. EAF和EXWM的共同点都是：“提升Emacs和别的程序的协作效率“
2. EXWM是一个X11窗口管理器，通过X11协议来控制Emacs和其他程序，但是EXWM只是管理其他程序，但是它并不会修改别的程序。比如它没法修改Chrome，PDF阅读器等GUI程序内在的行为
2. EXWM是一个X11窗口管理器，通过X11协议来控制Emacs和其他程序，但是EXWM只是管理其他程序，但是它并不会修改应用程序的内在行为。
3. EAF不是一个窗口管理器，EAF只是依赖Emacs自身的窗口管理功能显示自己
4. EAF的目标是通过PyQt创造新的应用来扩展Emacs的多媒体能力。从Emacs本身的Buffer/Mode设计上看，它和你平常用的 `xx-mode` 插件没有啥区别，只是它用Qt来绘制内容，而不是Emacs自身的文本库来绘制内容
5. EAF通过造轮子的方式，把大多数程序员常用的应用写出来以后，达到Live in Emacs的最终目标
@@ -181,23 +192,19 @@ EAF主要实现这几个功能：
或许EAF和EXWM看起来有点相似，但它们在设计和理念上是两个完全不同的项目。所以请大家多多学习X11和Qt的区别，理解技术的本质，避免无意义的比较和争论。
### 为什么EAF只能在Linux下工作？
1. DBus是Linux下专用的进程间通讯技术，其他操作系统可能无法支持DBus
2. Qt5的QGraphicsScene技术无法在MacOS下正常工作，也就无法实现Qt5应用的镜像窗口以支持Emacs的Buffer/Window模型
### 为什么EAF无法在MacOS下工作？
1. Qt5的QGraphicsScene技术无法在MacOS下正常工作，也就无法实现Qt5应用的镜像窗口以支持Emacs的Buffer/Window模型
2. QWindow Reparent技术无法在MacOS下正常工作，也就无法实现Qt应用进程的窗口粘贴到Emacs对应的Buffer区域
欢迎操作系统级别黑客移植EAF，目前为止，我知道的主要的迁移障碍就只有两个：DBus，QGraphicsScene
### 为什么EAF的js-video-player在Windows下无法播放视频文件？
`js-video-player`需要qtwebengine编译时链接到ffmpeg，才能支持额外的编码如`h264/aac`.
### `[EAF] *eaf* aborted (core dumped)` 奔溃了怎么办？
请检查 `*eaf*` 这个窗口的内容。通常是EAF的Python依赖没有安装好，如果你确定依赖没有问题，请附带 `*eaf*` 窗口的内容给我们提交issue，那里面有很多线索可以帮助我们排查问题。
### 为什么通过窗口管理器使用EAF无法接收输入信息？
EAF确认可以工作的桌面环境或者窗口管理器包括：KDE、Gnome2、Gnome3、Mate、XFce、LXDE、i3、QTile、Xpra.
### Github 个人访问标记干什么用的？
Markdown预览程序依赖grip，你需要访问[Github Personal access token](https://github.com/settings/tokens/new?scopes=)去获取你个人的标记，然后通过下面的命令设置标记后，grip才能正常的工作：
我们认为不同的窗口管理器对于X11协议的支持不够完善才导致这样的问题。
```Elisp
(setq eaf-grip-token "yourtokencode")
```
尽管不设置访问标记一开始也能成功使用，但Github过段时间会弹出 "GitHub Rate Limit Reached" 的错误。
现在的解决方案是将命令`wmctrl -m`中Name的值加入`eaf-wm-focus-fix-wms`，如果还有问题，请在Github提出issue。
### 代理
可以通过下面设置来通过代理访问互联网：
@@ -224,9 +231,11 @@ Markdown预览程序依赖grip，你需要访问[Github Personal access token](h
### 反馈安装和配置问题之前，请一定先阅读[Wiki](https://github.com/manateelazycat/emacs-application-framework/wiki)!!!
如果你遇到任何问题，请先用命令 `emacs -q` 并只添加EAF配置，做一个对比测试，如果 `emacs -q` 的时候可以工作，请检查你个人的配置文件。
如果你使用中遇到任何问题，并且问题是`git pull`后出现的，请先阅读[Discussions](https://github.com/manateelazycat/emacs-application-framework/discussions/527)页面。
如果```emacs -q```环境下问题依旧，请到[这里](https://github.com/manateelazycat/emacs-application-framework/issues/new)反馈。
关于其他问题，请用命令 `emacs -q` 并只添加EAF配置做一个对比测试，如果 `emacs -q` 可以正常工作，请检查你个人的配置文件。
如果`emacs -q`环境下问题依旧，请到[这里](https://github.com/manateelazycat/emacs-application-framework/issues/new)反馈, 并附带 `*eaf*` 窗口的内容给我们提交issue，那里面有很多线索可以帮助我们排查问题。。
如果你遇到崩溃的问题, 请用下面的方式来收集崩溃信息:
1. 先安装gdb并打开选项 `eaf-enable-debug`