Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/yangsheng6810/org-latex-impatient

Instant Previews LaTeX snippets in Org-mode
https://github.com/yangsheng6810/org-latex-impatient

Last synced: 12 days ago
JSON representation

Instant Previews LaTeX snippets in Org-mode

Awesome Lists containing this project

README 

        
#+TITLE: org-latex-impatient

=org-latex-impatient= provides instant preview of LaTeX snippets via MathJax outputed SVG. Unlike [[https://github.com/fuxialexander/emacs-webkit-katex-render][webkit-katex-render]], this does not need xwidget support. Currently =org-mode= and its derived modes, e.g. org-journal, are fully supported. =Markdown-mode= support is new, but seems decent as long as you have correct highlight for math fragments.  Support for =latex-mode= is experimental and under construction (no support for custom =\newcommand= yet).

[[file:img/screenshot.png]]

* Dependencies

  - [[https://github.com/Malabarba/names][Names]]

  - [[https://github.com/mathjax/MathJax-node][MathJax-node]]

  - [[https://github.com/mathjax/mathjax-node-cli/][MathJax-node-cli]]

  - [[https://github.com/tumashu/posframe][posframe]]



* Installation

  You can install =MathJax-node-cli= via ~npm~:

  #+BEGIN_SRC shell

npm install mathjax-node-cli

  #+END_SRC

  You need to set ~org-latex-impatient-tex2svg-bin~ to the location of the executable ~tex2svg~.



* Usage

   #+begin_src emacs-lisp

(use-package org-latex-impatient

  :defer t

  :hook (org-mode . org-latex-impatient-mode)

  :init

  (setq org-latex-impatient-tex2svg-bin

        ;; location of tex2svg executable

        "~/node_modules/mathjax-node-cli/bin/tex2svg"))

   #+end_src

   Or just enable minor mode ~org-latex-impatient-mode~ manually when it is needed.

   [[file:img/screencast.gif]]



* Customization

   - ~org-latex-impatient-delay~: change the number of seconds to wait before re-compilation after Emacs is idle. Default to be 0.1.

   - ~org-latex-impatient-tex2svg-bin~:  set the location of ~tex2svg~ executable.

   - ~org-latex-impatient-border-color~: border color.

   - ~org-latex-impatient-border-width~: border width (an integer), 0 will disable border.

   - ~org-latex-impatient-scale~: set the scale of the preview. Due to limitations in the way Emacs handles SVG pictures, it is implemented by manipulating SVG directly.

   - ~org-latex-impatient-posframe-position~: at which point shall the posframe be positioned. Can take two choices, ~point~ at the current point, or ~tex-end~ at the end of the LaTeX snippet. See the next option for detail.

   - ~org-latex-impatient-posframe-position-handler~: set the posframe position handler.

     Default value is ~org-latex-impatient-poshandler~, which uses end point of current LaTeX fragment for inline math, and centering right below the end point otherwise. You might want to use ~posframe-poshandler-point-bottom-left-corner~ for showing it using the point specified by ~org-latex-impatient-posframe-position~, or ~posframe-poshandler-point-window-center~ for a position centering right below the end point. Check the documentation of ~posframe-show~ for other options.

   - ~org-latex-impatient-user-latex-definitions~: custom LaTeX definitions used in the preview. Should be a list of strings. Default: ~'("\\newcommand{\\ensuremath}[1]{#1}" "\\renewcommand{\\usepackage}[2][]{}")~, which handles ~\ensuremath~ correctly for =MathJax=. In general, it is recommended to add your custom LaTeX command via the following:

     #+BEGIN_SRC org

,#+LATEX_HEADER: \newcommand{\someNewCommand}{Some Definition}

     #+END_SRC                                                                                                                                                                                                     

   - ~org-latex-impatient-inhibit-envs~: a list of LaTeX environments. If a LaTeX fragment contains one of them, preview will be disabled. This exists to avoid previewing environments unsupported by MathJax, e.g. =tikzpicture=.

   - ~org-latex-impatient-inhibit-commands~: a list of LaTeX commands. If a LaTeX fragment contains one of them, preview will be disabled. This exists to avoid previewing commands unsupported by MathJax, e.g. =\tikz=



* FAQ



** TeX parse error: Undefined control sequence

There are many LaTeX commands that are not supported by MathJax, therefore also unsupported by =org-latex-impatient-mode=. Mostly, such commands are not important for a preview.



If this is the case, you can /ignore/ it by override its definition with a place holder in ~org-latex-impatient-user-definitions~. For example, if you are using beamer, you would be calling ~\setbeamertemplate~ in the setup file or header. You will see errors like "TeX parse error: Undefined control sequence =\setbeamercolor=". This is a command that receives two parameters, so you can run

#+begin_src emacs-lisp

(add-to-list 'org-latex-impatient-user-latex-definitions "\\renewcommand{\\setbeamertemplate}[2]{}" t)

#+end_src

It is recommended to override top level commands for obvious reasons. Repeat this process for every such command.



Since most LaTeX packages are not relevant in math preview, we assume that *all* package usage are not necessary in producing a preview, and override the ~\usepackage~ call in the header. +If this prevents you from using certain commands defined by an external package, add this in the *front* of ~org-latex-impatient-user-latex-definitions~ like the following:+

# #+begin_src emacs-lisp

# (add-to-list 'org-latex-impatient-user-latex-definitions "\\usepackage{somepackge}") ;

# #+end_src



* Known Issue

  - Some SVG files get cropped slightly more than it should. This happens with =librsvg= 2.45 or below. It can also happen on Emacs 28, problem introduced in commit =8f42b94f= and fixed in =b42481e2=. ([[https://debbugs.gnu.org/cgi/bugreport.cgi?bug=44065][bug #44065]])

  - Some report problem of showing scaled SVG on Mac OSX. A workaround is to avoid customization of ~org-latex-impatient-scale~.

  - For ~latex-mode~, currently we do not support customized ~newcommand~ or ~renewcommand~. One workaround is to manually add the definitions to ~org-latex-impatient-user-latex-definitions~.



* Future Plans

  - Add support for ~latex-mode~. There is experimental support, but it does not support any customized commands. Such a support would require either parsing =tex= file, or actually compiling a =tex= file with ~latex/pdflatex/xelatex~.

  - Use ~latex/pdflatex/xelatex~ for image generation instead of ~mathjax~. Some progress made, but needs refactoring to make things consistent.

  - Support for scaling in different Emacs versions.



* License

  This piece work is licensed under GPLv3.