emacs documention

Table of Contents

1. Release Notes (发行版本信息)
2. Documention (文档)
   1. Getting Started （开始）
      1. Install （安装）
      2. Update & Rollback （升级与回滚）
      3. Configure （配置设置）
      4. Migrate （配置迁移）
      5. Troubleshoot （故障排除）
   2. Frequently/ Asked Questions （常见问题）
   3. Contributing （贡献）
   4. Workflow Tips, Tricks & Tutorials
   5. Module Appendix

Doom是为那些希望自己的工作框架组中拥有尽量少的框架，并且可以自己手动配置可更新的配置的Emacs老手门所量身定制的，且支持GNU Emacs 26.3+的配置框架。这将是你自己的配置的基础，也可以是通过引用Emacs爱好者的配置来学习这个操作系统的途径。

Doom是一个聚焦于性能表现（包括运行速度和启动速度）以及可读性高的代码设计，合理设计的意见集合体，这将大大拉近你与Emacs之间的距离。

Release Notes (发行版本信息)

Documention (文档)

Getting Started （开始）

GNU Emacs是一个伟大的线上冒险，更不用说Doom Emacs了。在你开始冒险之前，你应该线安装Emacs，Doom，以及相关的一些包，然后去学习如何更好的处理你新的系统。这份引导将通过安装，使用，配置和故障排除这几步，代领你畅游Emacs。

这份指导手册将不会过多关注与技术细节，方便我们可以尽可能快速的上手。更技术性的用户手册正由一群致力于更深入了解Emacs工作原理的贡献者们编辑中。

Install （安装）

首先，需要安装以下软件：

• Git 2.23+
• Emacs 27.1+ （建议使用27.2）
• ripgrep 11.0+
• GNU Find
• (可选)fd 7.3.0+ （在Debian，或者Ubuntu以及衍生系统中称为fd-find）——可用于提升很多文件的索引命令的表现。

需要确认的是这些包通过你的操作系统的包管理器是有效可用的，比如 macOS的homebrew 和macports，Windows的scoop/chocolatey，或者各种Linux发行版中的pacman/aptitude等等

1. 安装Emacs以及依赖环境

   1. Linux

      各种热门的Linux发行版安装Emacs 27.1+的方法会在下方列出。如果很不幸，Emacs 27.1或者更新的版本在你的系统中无法使用，那么你不得不从源代码开始构建。

      • Ubuntu

        1. Emacs

           在Ubuntu的包管理器中，Emacs 27以上的版本不是开箱即用的，但是通过PPA就可以了：

           add-apt-repository ppa:kelleyk/emacs
           apt-get update
           apt-get install emacs27
           

           或者通过snap

           snap install emacs --classic
           

           有时候，在开始安装emcas27之前，你不得不先删除较版本的Emacs以及他的依赖环境:

           sudo apt remove emacs
           sudo apt autoremove
           

        2. 其他的依赖环境

           接下来，安装Doom的其他依赖环境：

           apt-get install ripgrep fd-find
               #在18.04或者更早的版本中，ripgrep和fd-find在官方仓库中是无效的。
               #你可以通过别的方法安装，比如
           sudo dpkg -i fd_8.2.1_amd64.deb  # adapt version number and architecture
           sudo dpkg -i fd_8.2.1_amd64.deb  # adapt version number and architecture
           

      • Fedora

        dnf install emacs git ripgrep # 必要的依赖环境
        dnf install fd-find # 可选的依赖环境，如果Fedora的版本小于28，则使用“fd”
        

      • Arch Linux

        pacman -S git emacs ripgrep # 必要的依赖环境
        pacman -S fd # 可选的依赖环境
        

      • NixOS
        省略

      • openSUSE

        1. Emacs 27.1

           Emacs可以从包列表中安装，可以通过zypper手动安装。
           比方说，在openSUSE Leap 15.1中安装（需要root用户权限）:

           zypper addrepo https://download.opensuse.org/repositories/editors/openSUSE_Leap_15.1/editors.repo
           zypper refresh
           zypper install emacs
           

           如果本来你已经安装了一个emacs的旧版本，那么将会有提示你更新。

        2. ripgrep

           同样，也可以从包列表中下载ripgrep 11.0.2或者手动安装（需要root用户权限）：

           zypper addrepo https://download.opensuse.org/repositories/openSUSE:Factory/standard/openSUSE:Factory.repo
           zypper refresh
           zypper install ripgrep
           

           ripgrep只有0.8.1的版本在Leap 15.1和15.2中是官方提供的，所以你需要下载Rust来从源码构建ripgrep。Rust也同样可以通过包列表下载安装，或者通过zypper手动安装，比如：

           zypper addrepo https://download.opensuse.org/repositories/openSUSE:Leap:15.1:Update/standard/openSUSE:Leap:15.1:Update.repo
           zypper refresh
           zypper install rust
           

           从源码构建详情，具体参照ripgrep documention。

      • Gentoo Linux
        只要使用Gentoo官方的::gentoo仓库。

        1. Emacs
           启用gui使用标志以使用Emacas的图形界面，同时为了正确显示字体需要启用xft使用标志。

           echo "app-editors/emacs gui xft" >> /etc/portage/package.use/emacs
           

           安装最新的且未被屏蔽且与DOOM兼容的版本：

           emerge '>=app-editors/emacs-27.0'
           

           为了GCCEmacs/本地编译，或者可以通过jit使用标志来使用emcas28的电子编译版本：
           通过讲下列代码加入到package.accpet_{keywords解除期望版本的屏蔽}：

           =app-editors/emacs-28.0.9999 **
           

           然后将jit使用标志加入到package.use

           =app-editors/emacs-28.0.9999 jit
           

           最后融合：

           emerge =app-editors/emacs-28.0.9999
           

        2. 其他的依赖环境

           # 必要
           emerge '>=dev-vcs/git-2.23' '>=sys-apps/ripgrep-11.0' sys-apps/findutils
           # 可选
           emerge '>=sys-apps/fd-7.3.0'
           

   2. On macOS

      MacOS的用户虽然有很多途径安装Emacs，但是并不是所有途径安装的Emacs都适合Doom。在开始安装之前，你需要先安装Homebrew或者MacPorts中的其中一个包管理器：

      • Homebrew

      • MacPorts

      • 通过Homebrew安装

        首先，安装Doom的依赖环境：

        brew install git ripgrep # 必要的依赖环境
        brew install coreutils fd # 可选的依赖环境
        xcode-select --install # 安装clang
        

        对于安装Emacs本体，下面三种方法是最合适的选择，其中按照推荐的从多到少排序（根据兼容性）：

        • emacs-mac

          它提供了原生的emojis和更好的子框架支持，与macOS有着很好的整合：

          brew tap railwaycat/emacsmacport
          brew install emacs-mac --with-modules
          ln -s /usr/local/opt/emacs-mac/Emacs.app /Applications/Emacs.app
          

        • emaca-plus

          有些用户可能已经遇到过滚动时闪烁的问题：

          brew tap d12frosted/emacs-plus
          brew install emacs-plus
          ln -s /usr/local/opt/emacs-plus/Emacs.app /Applications/Emacs.app
          

        • emacs

          这是另一个可以接受的方法，但是这种方法并不提供一个Emacas的App

          brew install emcas
          

        • 不被推荐的版本

          这些版本的Emacs与Doom出现过比较多的冲突问题，在接下来的使用过程中可能会出现报错。所以这些版本是不推荐的：

          • emacsformacosx.com

          • brew cask install emacs （从emacsformacosx.com中安装）

          • AquaMacs

          • XEmacs

      • 通过MacPorts安装
        省略，推荐homebrew

   3. On Windows

      警告：Windows中运行Emacs速度会比较慢，不推荐。
      省略。

2. Doom Emacas安装

   Emacas以及Doom所需的依赖环境已经安装完毕了，接下来就改安装Doom Emacas本体了：

   git clone https://github.com/hlissner/doom-emacs ~/.emacs.d
   ~/.emacs.d/bin/doom install
   

   （这里在执行install报错的时候，基本为网络故障，笔者本人是通过升级clashpro的加强模式简单暴力地解决的。对于git的加速配置不是很懂，通过网上的方法也都试验过，并没有成功。）

   doom install将会在你的～/.doom.d（如果不存在）的文件下的创建DOOMDIR（Doom的各类文件的意思吧），并且指引你完成Doom Emacs的第一次安装。务必仔细阅读安装中跳出的指导说明。

   如果这是你第一次安装，你应该先运行一下doom docotr，这个步骤可以帮你诊断当前的系统以及配置是否存在常见问题。（在安装过程中，如果想从更具有技术层面进行分解=doom install=，那么doom install命令将会在“Install Doom Manually”章节被拆解成下列的shell命令）

   • bin/doom的作用

     这个功能将是你最好的伙伴。当然这个伙伴不会给你买啤酒，但是他会承担很多关于配置和维护你的Doom Emacs配置的大量工作。尤其是安装更新包括Doom自带的和你自己安装的包。

     它本身提供了大量的命令，可以通过bin/doom help来查看。这里详细说明最重要的几条命令：

     • doom sync ：这个命令可以将你的配置与Doom Emacas同步。可以确保已经安装必要的包，必要的元数据正常生成，于此同时将不必要的孤包删除。无论什么时候，当你修改了你的 doom 或者 packages.el 之时，记得要运行 doom sync 。如果你想用覆盖由别的模组安装的包，可以使用 doom sync -u 。

     • doom upgrade ：更新Doom Emacs以及所有包

     • doom env ：产生一个“环境变量”文件，相当于在Doom Emacs启动时，它用于加载的shell环境的快照。如果你在通过程序坞或者lancher在一个错误的环境中启动Emcas，那么这时候就你需要 doom env 。（该功能仅限与使用图形Emacs的MacOS用户。）

     • doom doctor ：如果你的Doom Emacs出错了，那么可以用 doom doctor 对你的安装，系统以及运行环境进行诊断。

     • doom purge ：随着时间的推移，Doom的插件会越积越多，你可以通过运行此条命令删除已经被淘汰的包以及那些孤包，还可以添加 -g 来切换到现有的仓库。

       使用 doom help 命令来查看 doom 提供的命令概况，也可以使用 doom help COMMADN 来展示 COMMADN 文档。

       推荐你将 ～/.emacs.d/bin 加入你的环境变量，这样就可以在随时使用doom了。
       在你的.bashrc或者.zshrc文件中添加 exprot PATH=“$HOME/.emcas.d/bin:$PATH”。

   • Install Doom Manually

     如果你更倾向于自己安装Doom，而不是直接使用 doom install=，可以参考以下 =bash shell 命令(假设已经将 hlissner/doom-emcas 克隆到 ～/.emacs.d):

     # 设置环境变量，这样可以直接调用doom命令
     PATH="$HOME/.emacs.d/bin:$PATH"
     
     # 创建一个私人配置文件的文件夹
     mkdir ~/.doom.d  # or ~/.config/doom
     
     # init.example.el文件包含了一个doom的样本，
     # 可以告诉你Doom到底是什么需要以什么顺序载入什么模组。
     
     cp ~/.emacs.d/init.example.el ~/.doom.d/init.el
     cp ~/.emacs.d/core/templates/config.example.el ~/.doom.d/config.el
     cp ~/.emacs.d/core/templates/packages.example.el ~/.doom.d/packages.el
     
     # You might want to edit ~/.doom.d/init.el here and make sure you only have the
     # modules you want enabled.
     
     # 在这一步，你或许已经想要编辑～/.doom.d/init.el文件，
     # 并且想要确认此时只有一些你想要启用的模组。
     
     # 将你的配置与Doom同步
     doom sync
     
     # 如果你自己知道Emacs不会从你自己的shell环境启动，
     # 这时候就需要创建一个环境变量文件来确保Doom会继承你的shell环境。
     # （比如用macOS或者使用启动台这种不能使用正确的shell的启动方式）
     
     # 当然你不确定自己是否需要创建环境变量文件，这行去做也并无大碍。
     # `doom install`命令会提示你是否创建一个文件，如果那时候你选择的是no，那么你可以通过以下命令来创建：
     doom env
     
     # Lastly, install the icon fonts Doom uses:
     
     # 最后，安装图标字体
     emacs --batch -f all-the-icons-install-fonts
     
     # 在Windows系统中， 该命令只会下载，之后还需要手动安装。
     

     通过阅读配置文件，来了解 ～/.doom.d 文件夹以及 ～/。doom.d/init.el 文件。

   • 通过Chemacs2安装Doom和其他配置
     Chemacs2是Emacs的一个载入引导程序，可以完成多个Emacs配置之间进行切换。下面是一个将Doom Emacs设置为默认设置的引导：

     1. 首先，安装Doom：

        git clone https://github.com/hlissner/doom-emacs ~/doom-emacs
        ~/doom-emacs/bin/doom install
        

     2. 将现有的配置转移，并且将Chemacs2安装在 ～/.emcas.d/ ：

        [ -f ~/.emacs ] && mv ~/.emacs ~/.emacs.bak
        [ -d ~/.emacs.d ] && mv ~/.emacs.d ~/.emacs.legacy
        git clone https://github.com/plexus/chemacs2.git ~/.emacs.d
        

     3. 创建一个包含Emacs文件列表的 ～/.emacs-profiles.el 。这个文件构成类似于 .dirlocal.el 文件。下面是一个同时配置Doom（默认配置），Spacemacs和Prelude的例子：

        (("default"   . ((user-emacs-directory . "~/doom-emacs")))
         ("legacy" . ((user-emacs-directory . "~/.emacs.legacy")))
         ("spacemacs"   . ((user-emacs-directory . "~/spacemacs"))))
        

     用 –with-profile选项，用特定的配置启动Emacs：

     emacs --with-profile spacemacs
     

     如果不指定特定的配置文件，直接使用default文件。

   • 外部依赖环境

     Doom由提供特征，语言支持以及外部工具整合的将近160个模组组成。其中的很多模组需要你们自己安装他的依赖环境。具体的信息可以在模组的README.org文件或者运行 bin/doom doctor 找到。
     具体模组信息可以自行查看，其中包括了现在所有的可用的模块。当然这个文档还一直在更新中，有些模块可能还没有README.org文件。

     可以在Doom中使用 M-x doom/help-modules （在Doom中绑定在 SPC h d m或者C-h d m的键位上）跳转到模组的文档，或者可以将你的光标停留在～/.doom.d/init.el文件中该模组的名称上，然后再按下K键跳转到文档（也可以使用gd跳转到源码），如果是非evil用户，分别可以使用C-c g k和C-c g d。

Update & Rollback （升级与回滚）

Configure （配置设置）

Migrate （配置迁移）

Troubleshoot （故障排除）

Frequently/ Asked Questions （常见问题）

Contributing （贡献）

Workflow Tips, Tricks & Tutorials

Module Appendix