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

docs(:lang): update READMEs to new format

Browse source
This commit is contained in:
Henrik Lissner 2021-10-16 01:28:32 +02:00 • committed by Henrik Lissner
parent ca7579a1e9
commit 20cac97c08
61 changed files with 4261 additions and 2634 deletions
Download patch file Download diff file Expand all files Collapse all files

375
modules/lang/org/README.org
View file

@ -1,48 +1,29 @@
#+TITLE: lang/org
#+DATE: February 19, 2017
#+SINCE: 2.0
#+STARTUP: inlineimages
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::lang org][Issues]] ↖ [[doom-module-source:lang/org][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :lang org
#+SUBTITLE: Organize your plain life in plain text
#+CREATED: February 20, 2017
#+SINCE: 2.0.0
* 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]]
- [[#changing-org-directory][Changing ~org-directory~]]
- [[#changing-org-noter-notes-search-path][Changing ~org-noter-notes-search-path~]]
- [[#troubleshooting][Troubleshooting]]
- [[#org-roam][=org-roam=]]
- [[#should-i-go-with-roam-v1-or-roam2-v2][Should I go with =+roam= (v1) or =+roam2= (v2)?]]
- [[#migrating-your-existing-files-from-v1-roam-to-v2-roam2][Migrating your existing files from v1 (=+roam=) to v2 (=+roam2=)]]
* Description
* Description :unfold:
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 system that stores files in one place, rather
- A custom, centralized attachment system that stores files in one place, rather
than in the same directory as the input file(s) (only applies to attachments
from files in/under =org-directory=).
+ Executable code blocks with support for a variety of languages and tools
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
- 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
- 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, jupyter, reveal.js, beamer, and others
- Drag-and-drop support for images (with inline preview) and media files (drops
a file icon and a short link) (requires [[doom-module:][+dragndrop]] flag).
- Integration with pandoc, ipython, jupyter, reveal.js, beamer, and others
(requires flags).
+ Export-to-clipboard functionality, for copying text into formatted html,
- 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~).
@ -56,218 +37,228 @@ executed.
https://www.mfoot.com/blog/2015/11/22/literate-emacs-configuration-with-org-mode/
#+end_quote
** Module Flags
+ =+brain= Enables [[https://github.com/Kungsgeten/org-brain][org-brain]] integration.
+ =+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).
+ =+hugo= Enables integration with [[https://gohugo.io][hugo]] to export from Emacs well-formed
([[https://github.com/russross/blackfriday][blackfriday]]) markdown.
+ =+ipython= (**DEPRECATED**) Enables ipython integration for babel.
+ =+journal= Enables [[https://github.com/bastibe/org-journal][org-journal]] integration.
+ =+jupyter= Enables Jupyter integration for babel.
+ =+noter= Enables org-noter integration. Keeps notes in sync with a document.
Requires [[https://github.com/politza/pdf-tools][pdf-tools]] (=:tools pdf=) or [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Document-View.html][DocView]] or [[https://github.com/wasamasa/nov.el][nov.el]] to be enabled.
+ =+pandoc= Enables pandoc integration into the Org exporter.
+ =+pomodoro= Enables a pomodoro timer for clocking time on tasks.
+ =+present= Enables integration with reveal.js, beamer and org-tree-slide, so
Emacs can be used for presentations. It automatically downloads [[https://github.com/hakimel/reveal.js][reveal.js]].
+ =+pretty= Enables pretty unicode symbols for bullets and priorities, and
better syntax highlighting for latex. Keep in mind: this can be expensive. If
org becomes too slow, it'd be wise to disable this flag.
+ =+roam= Enables integration with [[https://github.com/org-roam/org-roam-v1][org-roam v1]]. This requires ~sqlite3~ to be
installed on your system. Incompatible with =+roam2=.
+ =+roam2= Enables integration with [[https://github.com/org-roam/org-roam][org-roam v2]]. This requires ~sqlite3~ to be
installed on your system. Incompatible with =+roam=.
** Maintainers
- [[doom-user:][@hlissner]]
** Plugins
+ [[https://github.com/hniksic/emacs-htmlize][htmlize]]
+ [[https://github.com/astahlman/ob-async][ob-async]]
+ [[https://github.com/rexim/org-cliplink][org-cliplink]]
+ [[https://github.com/magit/orgit][orgit]]
+ [[https://orgmode.org/][org-plus-contrib]]
+ [[https://github.com/TobiasZawada/org-yt][org-yt]]
+ [[https://github.com/jkitchin/ox-clip][ox-clip]]
+ [[https://github.com/snosov1/toc-org][toc-org]]
+ =: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 rst=
+ [[https://github.com/msnoigrs/ox-rst][ox-rst]]
+ =:lang rust=
+ [[https://github.com/micanzhang/ob-rust][ob-rust]]
+ =:lang scala=
+ [[https://github.com/zwild/ob-ammonite][ob-ammonite]]
+ =:editor evil=
+ [[https://github.com/Somelauw/evil-org-mode][evil-org]]
+ =:tools pdf=
+ [[https://github.com/fuxialexander/org-pdftools][org-pdftools]]
+ =+dragndrop=
+ [[https://github.com/abo-abo/org-download][org-download]]
+ =+gnuplot=
+ [[https://github.com/mkmcc/gnuplot-mode][gnuplot]]
+ [[https://github.com/bruceravel/gnuplot-mode][gnuplot-mode]]
+ =+hugo=
+ [[https://github.com/kaushalmodi/ox-hugo][ox-hugo]]
+ =+ipython=
+ [[https://github.com/gregsexton/ob-ipython][ob-ipython]]
+ =+jupyter=
+ [[https://github.com/dzop/emacs-jupyter][jupyter]]
+ =+pandoc=
+ [[https://github.com/kawabata/ox-pandoc][ox-pandoc]]
+ =+pomodoro=
+ [[https://github.com/marcinkoziej/org-pomodoro][org-pomodoro]]
+ =+present=
+ [[https://github.com/anler/centered-window-mode][centered-window]]
+ [[https://github.com/takaxp/org-tree-slide][org-tree-slide]]
+ [[https://gitlab.com/oer/org-re-reveal][org-re-reveal]]
+ =+pretty=
+ [[https://github.com/integral-dw/org-superstar-mode][org-superstar]]
+ [[https://github.com/harrybournis/org-fancy-priorities][org-fancy-priorities]]
+ =+roam=
+ [[https://github.com/org-roam/org-roam-v1][org-roam]] (v1)
+ =+roam2=
- [[https://github.com/org-roam/org-roam][org-roam]] (v2)
+ =+noter=
+ [[https://github.com/weirdNox/org-noter][org-noter]]
[[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
- +brain ::
Enable [[https://github.com/Kungsgeten/org-brain][org-brain]] integration.
- +dragndrop ::
Enable drag-and-drop support for images and files; inserts inline previews
for images and an icon+link for other media types.
- +gnuplot ::
Install 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).
- +hugo ::
Enable integration with [[https://gohugo.io][hugo]] to export from Emacs well-formed ([[https://github.com/russross/blackfriday][blackfriday]])
markdown.
- +ipython ::
(**DEPRECATED**) Enable ipython integration for babel.
- +journal ::
Enable [[doom-package:][org-journal]] integration.
- +jupyter ::
Enable Jupyter integration for babel.
- +noter ::
Enable [[doom-package:][org-noter]] integration. Keeps notes in sync with a document. Requires
[[doom-module:][:tools pdf]], [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Document-View.html][DocView]], or [[https://github.com/wasamasa/nov.el][nov.el]] to be enabled.
- +pandoc ::
Enable pandoc integration into the Org exporter.
- +pomodoro ::
Enable a pomodoro timer for clocking time on tasks.
- +present ::
Enable integration with reveal.js, beamer and org-tree-slide, so Emacs can be
used for presentations. It automatically downloads [[https://github.com/hakimel/reveal.js][reveal.js]].
- +pretty ::
Enable pretty unicode symbols for bullets and priorities, and better syntax
highlighting for latex. Keep in mind: this can be expensive. If org becomes
too slow, it'd be wise to disable this flag.
- +roam ::
Enable integration with [[https://github.com/org-roam/org-roam-v1][org-roam v1]]. This requires ~sqlite3~ to be installed
on your system. /Incompatible with [[doom-module:][+roam2]]./
- +roam2 ::
Enable integration with [[https://github.com/org-roam/org-roam][org-roam v2]]. This requires ~sqlite3~ to be installed
on your system. /Incompatible with [[doom-module:][+roam]]./
** Packages
- [[doom-package:][evil-org]] if [[doom-package:][:editor evil]]
- [[doom-package:][htmlize]]
- [[doom-package:][jupyter]] if [[doom-package:][+jupyter]]
- [[doom-package:][ob-ammonite]] if [[doom-package:][:lang scala]]
- [[doom-package:][ob-async]]
- [[doom-package:][ob-crystal]] if [[doom-package:][:lang crystal]]
- [[doom-package:][ob-go]] if [[doom-package:][:lang go]]
- [[doom-package:][ob-ipython]] if [[doom-package:][+ipython]]
- [[doom-package:][ob-nim]] if [[doom-package:][:lang nim]]
- [[doom-package:][ob-racket]] if [[doom-package:][:lang racket]]
- [[doom-package:][ob-restclient]] if [[doom-package:][:lang rest]]
- [[doom-package:][ob-rust]] if [[doom-package:][:lang rust]]
- [[doom-package:][org-cliplink]]
- [[doom-package:][org-download]] if [[doom-package:][+dragndrop]]
- [[doom-package:][orgit]]
- [[doom-package:][org-noter]] if [[doom-package:][+noter]]
- [[doom-package:][org-pdftools]] if [[doom-package:][:tools pdf]]
- [[doom-package:][org-plus-contrib]]
- [[doom-package:][org-pomodoro]] if [[doom-package:][+pomodoro]]
- [[doom-package:][org-roam]] (v1) if [[doom-package:][+roam]]
- [[doom-package:][org-roam]] (v2) if [[doom-package:][+roam2]]
- [[doom-package:][org-yt]]
- [[doom-package:][ox-clip]]
- [[doom-package:][ox-hugo]] if [[doom-package:][+hugo]]
- [[doom-package:][ox-pandoc]] if [[doom-package:][+pandoc]]
- [[doom-package:][ox-rst]] if [[doom-package:][:lang rst]]
- [[doom-package:][toc-org]]
- if [[doom-package:][+gnuplot]]
- [[doom-package:][gnuplot]]
- [[doom-package:][gnuplot-mode]]
- if [[doom-package:][+present]]
- [[doom-package:][centered-window]]
- [[doom-package:][org-tree-slide]]
- [[doom-package:][org-re-reveal]]
- if [[doom-package:][+pretty]]
- [[doom-package:][org-superstar]]
- [[doom-package:][org-fancy-priorities]]
** Hacks
+ Adds support for a ~:sync~ parameter for org src blocks. This overrides
- Adds support for a ~:sync~ parameter for org src blocks. This overrides
~:async~.
+ Gracefully degrades ~:async~ babel blocks to ~:sync~ when =ob-async= would
cause errors or issues (such as with a ~:session~ parameter, which =ob-async=
does not support, or when exporting org documents).
+ The window is recentered when following links.
+ The breadcrumbs displayed in eldoc when hovering over an org headline has been
- Gracefully degrades ~:async~ babel blocks to ~:sync~ when [[doom-package:][ob-async]] would cause
errors or issues (such as with a ~:session~ parameter, which [[doom-package:][ob-async]] does not
support, or when exporting org documents).
- 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,
- If [[doom-module:][: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
#+begin_src emacs-lisp
(after! evil-org
(remove-hook 'org-tab-first-hook #'+org-cycle-only-current-subtree-h))
#+END_SRC
+ (Evil users) Nearby tables are formatted when exiting insert or replace mode
#+end_src
- (Evil users) Nearby tables are formatted when exiting insert or replace mode
(see ~+org-enable-auto-reformat-tables-h~).
+ Statistics cookies are updated when saving the buffer of exiting insert mode
- Statistics cookies are updated when saving the buffer of exiting insert mode
(see ~+org-enable-auto-update-cookies-h~).
+ Org-protocol has been lazy loaded (see ~+org-init-protocol-lazy-loader-h~);
- Org-protocol has been lazy loaded (see ~+org-init-protocol-lazy-loader-h~);
loaded when the server receives a request for an org-protocol:// url.
+ Babel and babel plugins are now lazy loaded (see
- Babel and babel plugins are now lazy loaded (see
~+org-init-babel-lazy-loader-h~); 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
- 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-a~).
* Prerequisites
Org has a few soft dependencies that you will need to make use of Org's more
esoteric features:
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
+ For inline LaTeX previews, ~latex~ and ~dvipng~ is needed.
+ To render GNUPlot images (with =+gnuplot= flag) the ~gnuplot~ program is
needed.
+ To execute 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.
To use ~jupyter kernels~ you need the =+jupyter= flag, the associated kernel as
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module has no hard requirements, but these soft requirements are needed to
use Org's more esoteric features:
- For inline LaTeX previews, ~latex~ and ~dvipng~ is needed.
- To render GNUPlot images (with [[doom-module:][+gnuplot]] flag) the ~gnuplot~ program is needed.
- To execute babel code blocks, you need whatever dependencies those languages
need. It is recommended you enable the associated [[doom-module:][:lang]] module and ensure its
dependencies are met, e.g. install the =ruby= executable for ruby support. To
use ~jupyter kernels~ you need the [[doom-module:][+jupyter]] flag, the associated kernel as
well as the ~jupyter~ program.
+ =org-roam= (with =+roam= or =+roam2= flag) requires =sqlite3= to be installed.
- [[doom-package:][org-roam]] (with [[doom-module:][+roam]] or [[doom-module:][+roam2]] flag) requires =sqlite3= to be installed.
** MacOS
#+BEGIN_SRC sh
#+begin_src sh
brew install --cask mactex
brew install gnuplot
#+END_SRC
#+end_src
** Arch Linux
#+BEGIN_SRC sh
#+begin_src sh
pacman -S texlive-core texlive-bin texlive-science
pacman -S gnuplot
pacman -S jupyter # required by +jupyter
#+END_SRC
#+end_src
** NixOS
#+BEGIN_SRC nix
#+begin_src nix
environment.systemPackages = with pkgs; [
# any less than medium isn't guaranteed to work
texlive.combined.scheme-medium
# required by +jupyter
(python38.withPackages(ps: with ps; [jupyter]))
];
#+END_SRC
#+end_src
** TODO Windows
* Features
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
** 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
#+begin_src sh
emacsclient --eval '(+org-capture/open-frame INTIAL-INPUT KEY)'
#+END_SRC
#+end_src
** Built-in custom link types
This module defines a number of custom link types in ~+org-init-custom-links-h~.
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)~
+ ~wikipedia:Emacs~
+ ~youtube:P196hEuA_Xc~ (link only)
+ ~yt:P196hEuA_Xc~ (like =youtube=, but includes an inline preview of the video)
- ~doom-docs:index.org~ -> =~/.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)~
- ~wikipedia:Emacs~
- ~youtube:P196hEuA_Xc~ (link only)
- ~yt:P196hEuA_Xc~ (like =youtube=, but includes an inline preview of the video)
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** Changing ~org-directory~
To modify ~org-directory~ it must be set /before/ =org= has loaded:
#+BEGIN_SRC emacs-lisp
;; ~/.doom.d/config.el
~org-directory~ must be set /before/ [[doom-package:][org]] has loaded:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(setq org-directory "~/new/org/location/")
#+END_SRC
** Changing ~org-noter-notes-search-path~
To modify ~org-noter-notes-search-path~ set:
#+end_src
#+BEGIN_SRC emacs-lisp
;; ~/.doom.d/config.el
** Changing ~org-noter-notes-search-path~
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(setq org-noter-notes-search-path '("~/notes/path/"))
#+END_SRC
#+end_src
* Troubleshooting
[[doom-report:][Report an issue?]]
** =org-roam=
*** Should I go with =+roam= (v1) or =+roam2= (v2)?
Long story short: if you're new to =org-roam= and haven't used it, then you
should go with =+roam2=; if you already have an ~org-roam-directory~ with the v1
files in it, then you can keep use =+roam= for a time being.
Long story short: if you're new to [[doom-package:][org-roam]] and haven't used it, then you should
go with [[doom-module:][+roam2]]; if you already have an ~org-roam-directory~ with the v1 files in
it, then you can keep use [[doom-module:][+roam]] for a time being.
V1 isn't actively maintained anymore and is now basically EOL. This means that
the feature disparity between the both will continue to grow, while its existing
@ -291,14 +282,22 @@ appear during the migration process. Because of that, *don't forget to backup*
your ~org-roam-directory~ before attempting to migrate.
In order to migrate from v1 to v2 using Doom follow the next steps:
1. Enable =+roam2= flag (and disable =+roam= if it was previously enabled) in
your =init.el=.
1. Enable [[doom-module:][+roam2]] flag (and disable [[doom-module:][+roam]] if it was previously enabled) in your
=init.el=.
2. Ensure your ~org-roam-directory~ points to a directory with your v1 files.
3. Run =doom sync -u= in your shell.
3. Run ~$ doom sync -u~ in your shell.
4. Restart Emacs (if it was previously opened) and run ~org-roam-migrate-wizard~
command (=M-x org-roam-migrate-wizard RET=). The wizard will automatically
command (~M-x org-roam-migrate-wizard RET~). The wizard will automatically
attempt to backup your previous ~org-roam-directory~ to =org-roam.bak=, but
just in case backup it yourself too.
4. After the wizard is done you should be good to go. Verify the integrity of
your data and whether it did everything as expected. In case of failure
[[https://github.com/org-roam/org-roam/issues][report]] your issue.
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote