Newbiemacs Manual

Table of Contents

1. Keybinding Notation

  • C means Ctrl, i.e., the control key
  • M means Meta, i.e., the command key for macOS or the alt key for Windows
  • SPC means the space key
  • RET means the return key, i.e., the enter key.
  • C-g means hold C and then press g
  • C-x k means C-x and then k (without holding C)
  • C-x C-= means C-x and then C-=
  • SPC S i means SPC and then S and then i (This is case-sensitive, so S is different from s)

2. Cheat sheets

3. File managements

  • For beginners, I recommend using your system's file manager.
  • If you are comfortable with basics of emacs, I recommend dired for the file management.

3.1. How to open a file in Newbiemacs

  1. In your system's file manager, open the directory of the file that you want to open.
  2. In Newbiemacs go to the main screen by pressing the backspace key.
  3. Drag the file from your file manager to Newbiemacs.
  4. You can also drag a folder to Newbiemacs. It will then show the list of files in it.

3.2. How to open the current directory in the file manager

  1. Suppose that file A is opened in Newbiemacs.
  2. To open the directory containing A in the file manager, you can simply type M-o f F.

3.3. Symlinks

  • A symlink is a link to a file similar to a "shortcut" to a file.
  • Creating a symlink will allow you to search a file without moving it to one of the pdf, tex, misc folders.

3.3.1. How to create a symlink to a file

  1. Go to the Newbiemacs screen.
  2. In your Finder or File Explorer, find a file that you want to create a symlink.
  3. Drag-and-drop the file into the Newbiemacs screen.
  4. Type SPC f S. Then it will ask you to enter a symlink name. Follow the instructions.
  5. On macOS, a symlink will be created in this way and you are done.
  6. On Windows, however, it will only copy a string in the clipboard. Now open the command prompt run as administrator. Paste the string in the command prompt.

4. LaTeX-mode

4.1. How to edit a tex file

  • To compile a tex file type M-RET b
  • To view the pdf file type M-RET v
  • The forward searching (tex file to pdf file) will be done automatically.
  • To go to the location of the tex file from the pdf file, do "Command+Shift+mouse click" if you are using Skim on macOS or do "double click" if you are using SumatraPDF on Windows.

4.2. BibTeX

4.2.1. How to use the main bib file

  • In your tex file, type , t b

  • This will add the following two lines in your tex file. 

    \bibliographystyle{abbrv}
\bibliography{(path-to-newbiemacs)/newbiemacs/nbm-user-settings/references/ref.bib}
  • To add a citation, type , i c

4.2.2. How to toggle the bibliography

  • In your tex file, type , t b
  • This will toggle the above two lines to the actual bibitems.
  • This may be useful if you want to share your tex file with your collaborators without sharing the bib file.

4.2.3. How to open the main bib file

  • Type SPC N s 5

4.2.4. How to add a new bibtex item from MathSciNet

  1. Copy a bibtex item from MathSciNet or zbMath.
  2. In a latex file, type , n b and follow the instructions.

4.2.5. How to add a new bibtex item from arxiv

  1. Go to the arxiv page of the article you you want to cite.
  2. Click "Export BibTeX Citation" on the right box and copy the contents.
  3. In a latex file, type , n b and follow the instructions.

4.2.6. How to create a new bib file containing the current bibitems only

  • Type , t B
  • This will create a new bib file with file name "local-ref.bib" in the current directory.

4.3. Some useful tools

4.3.1. Add a figure in a tex file

  • Using Newbiemacs you can add an image into your tex file as follows.
    1. Take a screenshot (or upload a screenshot from your tablet).
    2. Go to your tex file.
    3. Press , i f and follow the instructions.
  • By default Newbiemacs will search the downloads folder and the desktop.
  • If your computer saves screenshots in a different folder you can add the folder: type ALT-BACKSPACE (or Command-BACKSPACE in macOS) followed by x followed by 3, and add the directory path in a new line.

4.3.2. Change variables

  • While writing your paper, you realized that you want to change the variable i to j.
  • You cannot simply replace all i to j, because then it will also change a word like this to thjs and a macro like \int to \jnt.
  • In Newbiemacs you can do the variable change as follows.
    1. Open your tex file.
    2. If you want the change only on some part, select the region by dragging your mouse. (If you want the change in the entire file, you don't have to do this.)
    3. Press , t v and follow the instructions.

4.3.3. Convert latex code to HWP math code (for Korean)

  • Suppose that you want to use the following latex code in Hangul program (한글 프로그램). 

    \sum_{i=1}^n \frac{a_i}{b_i} = \prod_{i=1}^n c_i^2
  • You can convert this latex code to HWP math code as follows.
    1. Place your cursor inside a math environment.

    2. Press , t h and a converted HWP math code will be stored in the clipboard. For example, the above latex code will be converted to 

      sum_{ i=1}^n   {a_i }over{b_i } =  prod_{ i=1}^n  c_i^2
    3. Go to Hangul program and paste the clipboard string in the math input window (ctrl n m)

5. Org-mode

  • Org-mode is a very useful tool to organize text files with extension "org".
  • An org file is basically a text file with mark-down-like structure.
  • Your org files will be stored in the folder org under the Newbiemacs folder.
  • In Newbiemacs we use org-roam, which is a package to connect org files nicely.

5.1. How to create an org file

  • Type SPC o r.
  • Type a title of a new org file. It will open a new org file.
  • Write anything you want there.
  • Type C-c C-c when you are done.

5.2. How to search an org file

  • Type SPC o r.
  • Type anything you remember about the title of the org file.

5.3. How to insert an org file link into the current org file

  • Type , i n.
  • Enter the tile of the org file to which you want to insert a link.

5.4. How to view the connections of the org files

  • Type SPC o u.

5.5. How to add a link to a file (or a directory)

  • Drag-and-drop a file (or a directory) in your org file will create a link to that file.

  • (Optional) If you want to open every linked file or directory using your system default application, add the following line in your user-init.el. (To open user-init.el, type SPC N c u.) 

    (setq org-file-apps nil)

6. Magit (git interface)

6.1. Configuring Git user name and email (one time only)

  • Before using Git you need to identify yourself by entering this. 

    git config --global user.name "your_username"
git config --global user.email "your_email"

6.2. Install GitHub CLI (one time only)

  • To connect with GitHub we need GitHub CLI (and obvious a GitHub account).
  • Install GitHub CLI: https://cli.github.com/

  • Run the following in a terminal. 

    gh auth login
  • Choose the default options. Then enter the provided code in the web browser.

6.3. Test if everything is working

  1. Create a temporary folder.
  2. Inside the temporary folder, type M-o g i to initiate a repository.
  3. Type "y" twice and enter any repository name.
  4. Create any file and commit and push.
  5. Check if this repository is created in github.

6.4. Newbiemacs git commands

command keybinding
M-o g s start magit
M-o g c clone repository
M-o g i initiate git repository
M-o g p publish to github
M-o g m merge tool for resolving conflicts

6.5. Basic magit commands

command keybinding
help ?
show log l l
stage one file s
stage all S
commit c c
push to origin P p
pull from origin F p
merge m m

6.6. Basic git work flow

  1. Edit your files in a git repository.
  2. Start magit (type M-o g s)
  3. Stage the files you want to commit (place the cursor at each file and type s)
  4. Commit (type c c and enter a commit message and then type C-c C-c)
  5. Push (type P p)
  6. If your local repository is not upto date, you need to do the following.
    1. Pull (type F p)
    2. Merge (type m m)
    3. If there are no conflicts, you are done.
    4. If there are conflicts, Git will automatically write them in each conflicted file, which you need to resolve conflicts as follows.
      1. Visit a conflicted file (place the cursor at a conflicted file and type RET)
      2. Once the conflicted file is open, run a merge tool (type M-o g m)
      3. The merge tool will find each line with conflicts. You can resolve the conflicts as instructed in the minibuffer.
      4. Go back to magit and stage the conflicted file that have been resolved. (This file may have been automatically staged by the merge tool.)
      5. Repeat the above process for each conflicted file.
      6. Commit. There should be a default commit message.
      7. Push

7. Vim

  • Newbiemacs uses evil mode, which allows us to use Vim keybindings.
  • To enable Vim, in the Newbiemacs screen, type e and choose "vim". Then restart Emacs.
  • Once Vim is enabled, the shortcut prefix M-o can be replaced by SPC and the shortcut prefix M-RET can be replaced by , in normal mode.
  • For example, you can open the current directory using the system file manager by typing SPC f F in normal mode instead of typing M-o f F, and you can compile a tex file by typing , b in normal mode instead of typing M-RET b,
  • Note, however, that M-o and M-RET has the advantage that they can be used in any Vim mode (normal mode, insert mode or anything else).

7.1. Basic concepts on Vim

  • In Vim, there are several modes. The two most important modes are called normal mode and insert mode

  • normal mode has a fat cursor and the icon at the bottom left corder has orange color.

    normal-mode.png

  • insert mode has a thin cursor and the icon at the bottom left corder has green color.

    insert-mode.png

  • Type i to change mode from normal mode to insert mode
  • Type ESC to change mode from insert mode to normal mode
  • There is another mode, called visual mode, which is a mode to select a region, just like what you usually do with your mouse. In visual mode, the icon at the bottom left corder has white color.

7.2. Keybindings of basic commands

mode keybinding description
all C-g cancel entering keyboard input
normal M-BACKSPACE go to newbiemacs screen
normal i change to insert mode
insert ESC change to normal mode
normal v start visual mode
visual y yank (copy) the selected region and back to normal mode
visual x cut the selected region and back to normal mode
normal p paste after cursor
normal P paste before cursor

8. Emacs Basics

8.1. Terminology

  • The following are fundamental terms in Emacs .
  • frame: A frame is what's commonly called "window" that is opened when you start Emacs.
  • window: Windows are what you see in a frame. Usually there is only one window but sometimes you will see many windows in one frame.
  • buffer: When you open a file in emacs, its content is shown in a buffer. You can edit the buffer. If you save a modified buffer, Emacs will change the file as modified.
  • minibuffer: A minibuffer is a small window at the bottom of a frame. It is opened when Emacs needs your input for certain commends.

8.2. Emacs mode

  • Besides normal mode and insert mode, there is another mode called emacs mode, which is indicated with blue color at the bottom left corner.

    emacs-mode.png

  • To toggle between emacs mode and normal mode (or insert mode), type C-z.
  • In emacs mode you can use the usual Emacs keybindings.
  • If you enter other "major modes", such as "help", "dired", or "magit", the default mode is emacs mode.
  • In many of such modes, typing ? shows keybindings in that mode.

8.3. Keybindings

  • Here are some basic Emacs keybindings.
mode command keybinding
all isearch-forward C-s
all query-replace M-%
all kill-buffer C-x k
all increase font-size C-x C-=
all decrease font-size C-x C--
all default font-size C-x C-0
all org-store-link C-c l
all org-insert-link C-c C-l

8.4. Window managements

  • If you use Emacs, you will often encounter a situation that the Emacs screen is divided into two or more windows.
  • Many of pop-up windows (such as help, warning, agenda, or magit) can be closed by simply typing q (if it's in Emacs mode).
  • To maximize the current window, type M-o w m or C-x 1.

8.5. Buffer managements

  • To switch to another buffer type M-o b b
  • To kill the current buffer type M-o b d or C-x k and select the buffer

8.6. Which-key

  • There are many Emacs keybindings starting with C-x or C-c or C-h.
  • Press one of these keys will show the possible keybingings.
  • In this way you can explore Emacs commands in your own.

8.7. Execute command

  • In Emacs there are tons of commands you can execute.
  • Type M-x and it will show all possible commands available for you.
  • Typing anything in the prompt will narrow down the list of commands to those containing what you typed there.

9. Spell checking

  • To spell check we need to install a spell checking program (only once).
  • Once the program is installed, you can spell check by typing M-o S b or M-o S i

9.1. Install a spell checker on macOS

  1. We first need to install Homebrew. Enter the following in a terminal. 

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. To use homebrew we need to add its path to the system. Enter the following in a terminal. 

    echo 'export PATH=/opt/homebrew/bin:$PATH' >> ~/.zshrc

  3. Install ispell by typing the following in a terminal. 

    brew install ispell

9.2. Install a spell checker on Windows

  • We first need to install Msys2. Click the link and install it as instructed.

  • Open Msys2 and install hunspell by typing the following line. 

    pacman -S mingw-w64-x86_64-hunspell

  • Open Msys2 and install hunspell-en by typing the following line. 

    pacman -S mingw-w64-x86_64-hunspell-en

9.3. Install a spell checker on GNU/Linux

  • Enter the following in a terminal. 

    sudo apt-get install ispell

10. Configurations

10.1. key-tree

  • You can add your own keybindings.
  • Press M-o k u
  • You can see the system keybindings by typing M-o k s.
  • You must not modify the system keybindings because it will prevent to update Newbiemacs.

10.2. user-init

  • You can add your own configurations in the user init file.
  • Press M-o N c u

11. Further readings

Author: Jang Soo Kim

Created: 2024-08-25 Sun 22:22

Validate