lang/org: major refactor
The motivation for this change was to rethink lang/org's flags. Many of its former flags represented non-features. Therefore, its flags have been reduced to five: +dragndrop, +ipython, +pandoc, +gnuplot and +present. Everything else is included as org-load-hooks and treated as reasonable defaults. Other changes: - Fixes #1502: don't autopair certain pairs when in a math region - Fixes #1483: broken localleader in org-agenda - Adds gnuplot support #1108 - Doom's org submodules have been moved into lang/org/contrib/, because I expect there will be *many* more to come, and I don't want to pollute the moudle's root.
This commit is contained in:
Henrik Lissner
parent
9752cc005c
commit
11bfb17894
17 changed files with 972 additions and 809 deletions
|
|
@ -1,59 +1,194 @@
|
|||
#+TITLE: :lang org
|
||||
#+TITLE: lang/org
|
||||
#+DATE: February 19, 2017
|
||||
#+SINCE: 2.0
|
||||
#+STARTUP: inlineimages
|
||||
|
||||
This module provides support for org-mode.
|
||||
|
||||
+ A custom attachment system that keeps files in a centralized location.
|
||||
+ Drag-and-drop support for images (with inline preview) and media files (drops
|
||||
a file icon and a short link).
|
||||
+ Executable code blocks with support for a variety of languages and tools,
|
||||
including REST requests, SQL, google translate, plantuml, and matlab.
|
||||
+ An org-capture workflow that works from outside Emacs (through the
|
||||
=bin/org-capture= shell script).
|
||||
+ Exported documents are saved to a centralized location.
|
||||
+ A configuration for using org-mode for slide-show presentations, or exporting
|
||||
org files to reveal.js slideshows.
|
||||
+ (TODO) A static site generator based in org-mode and Emacs.
|
||||
|
||||
#+begin_quote
|
||||
org-mode is a beast, and Doom's most difficult module to maintain. And its most
|
||||
important. This module is /highly/ opinionated and experimental; my foray into
|
||||
learning org is a neverending quest.
|
||||
#+end_quote
|
||||
|
||||
* Table of Contents :TOC:
|
||||
- [[#install][Install]]
|
||||
* Table of Contents :TOC_3:noexport:
|
||||
- [[#description][Description]]
|
||||
- [[#module-flags][Module Flags]]
|
||||
- [[#plugins][Plugins]]
|
||||
- [[#hacks][Hacks]]
|
||||
- [[#prerequisites][Prerequisites]]
|
||||
- [[#macos][MacOS]]
|
||||
- [[#arch-linux][Arch Linux]]
|
||||
- [[#nixos][NixOS]]
|
||||
- [[#windows][Windows]]
|
||||
- [[#features][Features]]
|
||||
- [[#invoking-the-org-capture-frame-from-outside-emacs][Invoking the org-capture frame from outside Emacs]]
|
||||
- [[#built-in-custom-link-types][Built-in custom link types]]
|
||||
- [[#configuration][Configuration]]
|
||||
- [[#usage][Usage]]
|
||||
- [[#appendix][Appendix]]
|
||||
- [[#changing-org-directory][Changing ~org-directory~]]
|
||||
|
||||
* Install
|
||||
Org has no hard dependencies, but there are some things you'll need to make use of Org's more esoteric features.
|
||||
* Description
|
||||
This module adds org-mode support to Doom Emacs, along with a number of
|
||||
adjustments, extensions and reasonable defaults to make it more performant and
|
||||
intuitive out of the box:
|
||||
|
||||
+ A custom, centralized attachment and export system that stores files in one
|
||||
place, rather than in the same directory as the input file(s) (only applies to
|
||||
attachments/exporting from files in/under =org-directory=).
|
||||
+ Executable code blocks with support for a variety of languages and tools
|
||||
(depending on what :lang modules are enabled).
|
||||
+ Supports an external org-capture workflow through the =bin/org-capture= shell
|
||||
script and ~+org-capture/open-frame~.
|
||||
+ A configuration for using org-mode for slide-show presentations or exporting
|
||||
org files to reveal.js slideshows.
|
||||
+ Drag-and-drop support for images (with inline preview) and media files (drops
|
||||
a file icon and a short link) (requires =+dragndrop= flag).
|
||||
+ Integration with pandoc, ipython, reveal.js, beamer, and others (requires
|
||||
flags).
|
||||
+ Export-to-clipboard functionality, for copying text into formatted html,
|
||||
markdown or rich text to the clipboard (see ~+org/export-to-clipboard~ and
|
||||
~+org/export-to-clipboard-as-rich-text~).
|
||||
|
||||
#+begin_quote
|
||||
Org is a system for writing plain text notes with syntax highlighting, code
|
||||
execution, task scheduling, agenda management, and many more. The whole idea is
|
||||
that you can write notes and mix them with references to things like articles,
|
||||
images, and example code combined with the output of that code after it is
|
||||
executed.
|
||||
|
||||
https://www.mfoot.com/blog/2015/11/22/literate-emacs-configuration-with-org-mode/
|
||||
#+end_quote
|
||||
|
||||
** Module Flags
|
||||
+ =+dragndrop= Enables drag-and-drop support for images and files; inserts
|
||||
inline previews for images and an icon+link for other media types.
|
||||
+ =+gnuplot= Installs gnuplot & gnuplot-mode, which enables rendering images
|
||||
from gnuplot src blocks or plotting tables with ~org-plot/gnuplot~ (bound to
|
||||
=SPC m b p=, by default).
|
||||
+ =+ipython= Enables ipython+babel integration.
|
||||
+ =+pandoc= Enables pandoc integration into the Org exporter.
|
||||
+ =+present= Enables integration with reveal.js, beamer and org-tree-slide, so
|
||||
Emacs can be used for presentations.
|
||||
|
||||
** Plugins
|
||||
+ [[https://orgmode.org/][org-plus-contrib]]
|
||||
+ [[https://github.com/sabof/org-bullets][org-bullets]]
|
||||
+ [[https://github.com/TobiasZawada/org-yt][org-yt]]
|
||||
+ [[https://github.com/snosov1/toc-org][toc-org]]
|
||||
+ [[https://github.com/jkitchin/ox-clip][ox-clip]]
|
||||
+ [[https://github.com/hniksic/emacs-htmlize][htmlize]]
|
||||
+ [[https://github.com/astahlman/ob-async][ob-async]]
|
||||
+ =:lang crystal=
|
||||
+ [[https://github.com/brantou/ob-crystal][ob-crystal]]
|
||||
+ =:lang go=
|
||||
+ [[https://github.com/pope/ob-go][ob-go]]
|
||||
+ =:lang nim=
|
||||
+ [[https://github.com/Lompik/ob-nim][ob-nim]]
|
||||
+ =:lang racket=
|
||||
+ [[https://github.com/DEADB17/ob-racket][ob-racket]]
|
||||
+ =:lang rest=
|
||||
+ [[https://github.com/alf/ob-restclient.el][ob-restclient]]
|
||||
+ =:lang rust=
|
||||
+ [[https://github.com/micanzhang/ob-rust][ob-rust]]
|
||||
+ =:editor evil=
|
||||
+ [[https://github.com/Somelauw/evil-org-mode][evil-org]]
|
||||
+ =:tools pdf=
|
||||
+ [[https://github.com/markus1189/org-pdfview/tree/09ef4bf8ff8319c1ac78046c7e6b89f6a0beb82c][org-pdfview]]
|
||||
+ =+dragndrop=
|
||||
+ [[https://github.com/abo-abo/org-download][org-download]]
|
||||
+ =+ipython=
|
||||
+ [[https://github.com/gregsexton/ob-ipython][ob-ipython]]
|
||||
+ =+pandoc=
|
||||
+ [[https://github.com/kawabata/ox-pandoc][ox-pandoc]]
|
||||
+ =+present=
|
||||
+ [[https://github.com/anler/centered-window-mode][centered-window]]
|
||||
+ [[https://github.com/takaxp/org-tree-slide][org-tree-slide]]
|
||||
+ [[https://github.com/yjwen/org-reveal][ox-reveal]]
|
||||
|
||||
** Hacks
|
||||
+ The window is recentered when following links.
|
||||
+ The breadcrumbs displayed in eldoc when hovering over an org headline has been
|
||||
reworked to strip out link syntax and normalize font-size disparities.
|
||||
+ If =:ui workspaces= is enabled, persp-mode won't register org agenda buffers that
|
||||
are temporarily opened in the background.
|
||||
+ Temporary org agenda files aren't added to recentf.
|
||||
+ =file:= links are highlighted with the ~error~ face if they are broken.
|
||||
+ TAB was changed to toggle only the visibility state of the current subtree,
|
||||
rather than cycle through it recursively. This can be reversed with:
|
||||
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
(after! org
|
||||
(remove-hook 'org-tab-first-hook #'+org|cycle-only-current-subtree t))
|
||||
#+END_SRC
|
||||
+ (Evil users) Nearby tables are formatted when exiting insert or replace mode
|
||||
(see ~+org|enable-auto-reformat-tables~).
|
||||
+ Statistics cookies are updated when saving the buffer of exiting insert mode
|
||||
(see ~+org|enable-auto-update-cookies~).
|
||||
+ Org-protocol has been lazy loaded (see ~+org|init-protocol-lazy-loader~);
|
||||
loaded when the server recieves a request for an org-protocol:// url.
|
||||
+ Babel and babel plugins are now lazy loaded (see
|
||||
~+org|init-babel-lazy-loader~); loaded when a src block is executed. No need
|
||||
to use ~org-babel-do-load-languages~ in your config, just install your babel
|
||||
packages to extend language support (and ensure its ~org-babel-execute:*~
|
||||
function is autoloaded).
|
||||
+ If a variable is used as a file path in ~org-capture-template~, it will be
|
||||
resolved relative to ~org-directory~, instead of ~default-directory~ (see
|
||||
~+org*capture-expand-variable-file~).
|
||||
|
||||
* Prerequisites
|
||||
Org has a few soft dependencies that you will need to make use of Org's more
|
||||
esoteric features:
|
||||
|
||||
+ For inline LaTeX previews, you need ~latex~ and ~dvipng~.
|
||||
+ To run babel code blocks, you need whatever dependencies those languages
|
||||
need. It is recommended you enable the associated module in =lang/= and ensure
|
||||
its dependencies are met.
|
||||
+ The =+crm= module uses a sqlite database to manage your contacts, invoices,
|
||||
and projects; this needs sqlite installed.
|
||||
+ For rendering GNUPlot images (with =+gnuplot= flag) you need the ~gnuplot~
|
||||
program installed.
|
||||
+ To run babel code blocks, you need whatever dependencies those languages need.
|
||||
It is recommended you enable the associated =:lang= module and ensure its
|
||||
dependencies are met, e.g. install the =ruby= executable for ruby support.
|
||||
|
||||
** MacOS
|
||||
#+BEGIN_SRC sh
|
||||
brew cask install mactex
|
||||
brew install sqlite
|
||||
brew install gnuplot
|
||||
#+END_SRC
|
||||
|
||||
** Arch Linux
|
||||
#+BEGIN_SRC sh
|
||||
sudo pacman --needed --noconfirm -S texlive-core texlive-bin texlive-science sqlite
|
||||
pacman -S texlive-core texlive-bin texlive-science
|
||||
pacman -S gnuplot
|
||||
#+END_SRC
|
||||
|
||||
** TODO NixOS
|
||||
|
||||
** TODO Windows
|
||||
|
||||
* Features
|
||||
** Invoking the org-capture frame from outside Emacs
|
||||
The simplest way to use the org-capture frame is through the ~bin/org-capture~
|
||||
script. I'd recommend binding a shortcut key to it. If Emacs isn't running, it
|
||||
will spawn a temporary daemon for you.
|
||||
|
||||
Alternatively, you can call ~+org-capture/open-frame~ directly, e.g.
|
||||
|
||||
#+BEGIN_SRC sh
|
||||
emacsclient --eval '(+org-capture/open-frame INTIAL-INPUT KEY)'
|
||||
#+END_SRC
|
||||
|
||||
** Built-in custom link types
|
||||
This module defines a number of custom link types in ~+org|init-custom-links~.
|
||||
They are (with examples):
|
||||
|
||||
+ ~doom-docs:news/2.1.0~ (=~/.emacs.d/docs/%s=)
|
||||
+ ~doom-modules:editor/evil/README.org~ (=~/.emacs.d/modules/%s=)
|
||||
+ ~doom-repo:issues~ (=https://github.com/hlissner/doom-emacs/%s=)
|
||||
+ ~doom:core/core.el~ (=~/.emacs.d/%s=)
|
||||
+ ~duckduckgo:search terms~
|
||||
+ ~gimages:search terms~ (Google Images)
|
||||
+ ~github:hlissner/doom-emacs~
|
||||
+ ~gmap:Toronto, Ontario~ (Google Maps)
|
||||
+ ~google:search terms~
|
||||
+ ~org:todo.org~ (={org-directory}/%s=)
|
||||
+ ~wolfram:sin(x^3)~
|
||||
+ ~youtube:P196hEuA_Xc~ (link only)
|
||||
+ ~yt:P196hEuA_Xc~ (like =youtube=, but includes an inline preview of the video)
|
||||
|
||||
* Configuration
|
||||
(Coming soon)
|
||||
** Changing ~org-directory~
|
||||
To modify ~org-directory~ it must be set /before/ =org= has loaded:
|
||||
|
||||
* Usage
|
||||
(Coming soon)
|
||||
|
||||
* Appendix
|
||||
(Coming soon)
|
||||
#+BEGIN_SRC emacs-lisp
|
||||
;; ~/.doom.d/config.el
|
||||
(setq org-directory "~/new/org/location/")
|
||||
#+END_SRC
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue