Improve section readability to prepare a mail to the list
This commit is contained in:
Gerard Vermeulen
parent
c7c4d4bb15
commit
17f2dc78c8
228
README.org
228
README.org
@ -2322,109 +2322,40 @@ valid directories and files. In an [[https://orgmode.org/][Org-mode]] buffer th
|
|||||||
|
|
||||||
This package aims to produce a versatile generic core which can process a
|
This package aims to produce a versatile generic core which can process a
|
||||||
fontified buffer and pass the data to any number of backends to deal with
|
fontified buffer and pass the data to any number of backends to deal with
|
||||||
specific output formats and it should work with =org-mode=. *Thanks to the
|
specific output formats and Org offers it as an alternative to =minted=. *The
|
||||||
listings below*, [[https://github.com/tecosaur/engrave-faces#readme][Engrave Faces]] and [[info:org#Source blocks in LaTeX export][Org source block export to LaTeX (info)]] *are
|
listings below make* [[https://github.com/tecosaur/engrave-faces#readme][Engrave Faces]] and [[info:org#Source blocks in LaTeX export][Org source block export to LaTeX (info)]]
|
||||||
capable of handling this [[file:README.org]] file:*
|
*capable of handling this [[file:README.org]] file to my satisfaction:*
|
||||||
1. Listing [[lst:ensure-engrave-faces-with-latex-face-mapper-fix]] ensures
|
1. The default Org export configuration for engraving listings produces =pdf=
|
||||||
installation of =engrave-faces= and makes =engrave-faces-latex-face-mapper=
|
output with a non-equidistant interline spacing in floating listings and
|
||||||
handle multi-line documentation strings.
|
equidistant interline spaces non-floating =tcolorbox= environments. I have
|
||||||
2. Listing [[lst:ensure-engrave-faces-with-latex-face-apply-fix]] ensures
|
traced non-equidistance interline spacing back to the =breakable= option in
|
||||||
installation of =engrave-faces= and makes =engrave-faces-latex-face-apply=
|
=Code= environments inside =listing= environments. However, =tcolorbox=
|
||||||
handle symbolic color name strings (in addition to the hexadecimal strings).
|
requires =breakable= for listings that do not fit on a page. As a
|
||||||
3. The =org-latex-engraved-source-block-filter= in listing
|
work-around, the filter =org-latex-engraved-source-block-filter= in listing
|
||||||
[[lst:org-latex-engraved-source-block-filter]] and the
|
[[lst:org-latex-engraved-source-block-filter]] and the
|
||||||
=org-latex-engraved-preamble= customization in listing
|
=org-latex-engraved-preamble= customization in listing
|
||||||
[[lst:smart-latex-engrave-org-source-blocks]] allow to engrave =org-mode= source
|
[[lst:smart-latex-engrave-org-source-blocks]] allow to engrave =org-mode= source
|
||||||
blocks to "floating unbreakable" or "non-floating breakable" LaTeX
|
blocks to "floating unbreakable with a caption" or "non-floating breakable
|
||||||
environments.
|
without a caption" LaTeX environments.
|
||||||
|
2. Listing [[lst:ensure-engrave-faces-with-latex-face-apply-fix]] makes
|
||||||
|
=engrave-faces-latex-face-apply= handle symbolic color name strings (in
|
||||||
|
addition to the hexadecimal strings). Since for instance the faces in
|
||||||
|
src_emacs-lisp{(find-library "org-faces")} have symbolic color names, this
|
||||||
|
fix allows to engrave org-mode source blocks during LaTeX export without any
|
||||||
|
further tweaking.
|
||||||
|
3. Listing [[lst:ensure-engrave-faces-with-latex-face-mapper-fix]] makes
|
||||||
|
=engrave-faces-latex-face-mapper= handle horizontal and vertical whitespace
|
||||||
|
in multiple line documentation strings correctly. For instance, *without this
|
||||||
|
fix* the empty line in the documentation string of
|
||||||
|
=org-latex-engraved-sourc-block-filter= of listing
|
||||||
|
[[lst:org-latex-engraved-source-block-filter]] is invisible in the exported =pdf=
|
||||||
|
file and *very obviously* the mishandling of the spacing destroys the
|
||||||
|
indentation in Python documentation strings. The idea of the fix is to let
|
||||||
|
the LaTeX face mapper wrap only groups of "words joined by blank characters"
|
||||||
|
in LaTeX commands and pass "newlines and other whitespace between those
|
||||||
|
groups" on without wrapping.
|
||||||
4. Listing [[lst:ox-engraved-emacs-lisp-setup]] shows how to use this configuration.
|
4. Listing [[lst:ox-engraved-emacs-lisp-setup]] shows how to use this configuration.
|
||||||
|
|
||||||
#+caption[Ensure =engrave-faces= installation and fix multiline docstrings]:
|
|
||||||
#+caption: Ensure =engrave-faces= installation and fix multiline docstrings.
|
|
||||||
#+name: lst:ensure-engrave-faces-with-latex-face-mapper-fix
|
|
||||||
#+begin_src emacs-lisp
|
|
||||||
(when (and (ensure-package-installation 'engrave-faces)
|
|
||||||
(require 'engrave-faces-latex nil t))
|
|
||||||
(defun engrave-faces-latex-face-mapper-override (faces content)
|
|
||||||
"Create a LaTeX representation of CONTENT With FACES applied."
|
|
||||||
(let* ((style (engrave-faces-preset-style faces))
|
|
||||||
(protected-content
|
|
||||||
(funcall
|
|
||||||
(if (and engrave-faces-latex-mathescape
|
|
||||||
(eq 'font-lock-comment-face (car style)))
|
|
||||||
#'engrave-faces-latex--protect-content-mathescape
|
|
||||||
#'engrave-faces-latex--protect-content)
|
|
||||||
content)))
|
|
||||||
;; Wrap groups of "words joined by blank characters" in LaTeX commands.
|
|
||||||
;; Do not wrap newlines and other whitespace between those groups.
|
|
||||||
(let ((regexp (rx (or (group-n 1 (+ graph ) (* (+ blank) (+ graph)))
|
|
||||||
(group-n 2 (+ (any "\n" space))))))
|
|
||||||
(slug (when (and style
|
|
||||||
(eq engrave-faces-latex-output-style 'preset))
|
|
||||||
(plist-get (cdr style) :slug)))
|
|
||||||
(start 0)
|
|
||||||
(stack))
|
|
||||||
(while (string-match regexp protected-content start)
|
|
||||||
(setq start (match-end 0))
|
|
||||||
(when-let ((pc (match-string 1 protected-content)))
|
|
||||||
(if (stringp slug)
|
|
||||||
(push (concat "\\EF" slug "{" pc "}") stack)
|
|
||||||
(push (engrave-faces-latex-face-apply faces pc) stack)))
|
|
||||||
(when-let ((pc (match-string 2 protected-content)))
|
|
||||||
(push pc stack)))
|
|
||||||
(apply #'concat (nreverse stack))))))
|
|
||||||
|
|
||||||
(with-eval-after-load 'emacs
|
|
||||||
(defun toggle-engrave-faces-latex-face-mapper-override ()
|
|
||||||
"Toggle `engrave-faces-latex-face-mapper' advice."
|
|
||||||
(interactive)
|
|
||||||
(toggle-advice 'engrave-faces-latex-face-mapper
|
|
||||||
:override #'engrave-faces-latex-face-mapper-override))
|
|
||||||
|
|
||||||
(toggle-engrave-faces-latex-face-mapper-override))
|
|
||||||
#+end_src
|
|
||||||
|
|
||||||
#+caption[Ensure =engrave-faces= installation and fix symbolic colors]:
|
|
||||||
#+caption: Ensure =engrave-faces= installation and fix symbolic colors.
|
|
||||||
#+name: lst:ensure-engrave-faces-with-latex-face-apply-fix
|
|
||||||
#+begin_src emacs-lisp
|
|
||||||
(when (and (ensure-package-installation 'engrave-faces)
|
|
||||||
(require 'engrave-faces-latex nil t))
|
|
||||||
(defun engrave-faces-latex--color (color)
|
|
||||||
"Convert COLOR loosely to a string of six hexadecimal digits."
|
|
||||||
(if (char-equal ?# (aref color 0))
|
|
||||||
(substring color 1 7)
|
|
||||||
(apply 'format "%02x%02x%02x"
|
|
||||||
(mapcar (lambda (c) (ash c -8))
|
|
||||||
(color-values color)))))
|
|
||||||
|
|
||||||
(defun engrave-faces-latex-face-apply-override (faces content)
|
|
||||||
"Convert attributes of FACES to LaTeX commands applied to CONTENT."
|
|
||||||
(let ((attrs (engrave-faces-merge-attributes faces)))
|
|
||||||
(let ((bg (plist-get attrs :background))
|
|
||||||
(fg (plist-get attrs :foreground))
|
|
||||||
(it (eql (plist-get attrs :slant) 'italic))
|
|
||||||
(bl (member (plist-get attrs :weight) '(bold extra-bold)))
|
|
||||||
(st (plist-get attrs :strike-through)))
|
|
||||||
(concat
|
|
||||||
(when bg (concat "\\colorbox[HTML]{"
|
|
||||||
(engrave-faces-latex--color bg) "}{"))
|
|
||||||
(when fg (concat "\\textcolor[HTML]{"
|
|
||||||
(engrave-faces-latex--color fg) "}{"))
|
|
||||||
(when st "\\sout{") (when bl "\\textbf{") (when it "\\textit{")
|
|
||||||
content
|
|
||||||
(when bg "}") (when fg "}") (when st "}") (when bl "}") (when it "}"))))))
|
|
||||||
|
|
||||||
(with-eval-after-load 'emacs
|
|
||||||
(defun toggle-engrave-faces-latex-face-apply-override ()
|
|
||||||
"Toggle `engrave-faces-latex-face-apply' advice."
|
|
||||||
(interactive)
|
|
||||||
(toggle-advice 'engrave-faces-latex-face-apply
|
|
||||||
:override #'engrave-faces-latex-face-apply-override))
|
|
||||||
|
|
||||||
(toggle-engrave-faces-latex-face-apply-override))
|
|
||||||
#+end_src
|
|
||||||
|
|
||||||
#+caption[Engrave to floating unbreakable or non-floating breakable environments]:
|
#+caption[Engrave to floating unbreakable or non-floating breakable environments]:
|
||||||
#+caption: Define an =org-export= filter function to engrave =org-src-mode=
|
#+caption: Define an =org-export= filter function to engrave =org-src-mode=
|
||||||
#+caption: blocks to floating unbreakable LaTeX environments or non-floating
|
#+caption: blocks to floating unbreakable LaTeX environments or non-floating
|
||||||
@ -2443,6 +2374,7 @@ capable of handling this [[file:README.org]] file:*
|
|||||||
(let ((enter "^\\\\begin{Code}\n\\\\begin{Verbatim}")
|
(let ((enter "^\\\\begin{Code}\n\\\\begin{Verbatim}")
|
||||||
(leave "^\\\\end{Verbatim}\n\\\\end{Code}"))
|
(leave "^\\\\end{Verbatim}\n\\\\end{Code}"))
|
||||||
;; Transform only blocks matching the enter regexp at position 0.
|
;; Transform only blocks matching the enter regexp at position 0.
|
||||||
|
;; Do not transform blocks that are listing environments.
|
||||||
(when (and (string-match enter data) (eql 0 (match-beginning 0)))
|
(when (and (string-match enter data) (eql 0 (match-beginning 0)))
|
||||||
(setq data (replace-match
|
(setq data (replace-match
|
||||||
"\\begin{Breakable}\n\\begin{Verbatim}" t t data))
|
"\\begin{Breakable}\n\\begin{Verbatim}" t t data))
|
||||||
@ -2456,8 +2388,8 @@ capable of handling this [[file:README.org]] file:*
|
|||||||
data)))))
|
data)))))
|
||||||
#+end_src
|
#+end_src
|
||||||
|
|
||||||
#+caption[Enable smart LaTeX engraving of =org-src-mode= blocks]:
|
#+caption[Smart LaTeX engraving of =org-src-mode= blocks]:
|
||||||
#+caption: Enable smart LaTeX engraving of =org-src-mode= blocks.
|
#+caption: Smart LaTeX engraving of =org-src-mode= blocks.
|
||||||
#+name: lst:smart-latex-engrave-org-source-blocks
|
#+name: lst:smart-latex-engrave-org-source-blocks
|
||||||
#+begin_src emacs-lisp
|
#+begin_src emacs-lisp
|
||||||
(defun smart-latex-engrave-org-source-blocks ()
|
(defun smart-latex-engrave-org-source-blocks ()
|
||||||
@ -2506,6 +2438,102 @@ capable of handling this [[file:README.org]] file:*
|
|||||||
[LISTINGS-SETUP]"))
|
[LISTINGS-SETUP]"))
|
||||||
#+end_src
|
#+end_src
|
||||||
|
|
||||||
|
#+caption[Fix engraving of symbolic color names]:
|
||||||
|
#+caption: Fix engraving of symbolic colors names.
|
||||||
|
#+name: lst:ensure-engrave-faces-with-latex-face-apply-fix
|
||||||
|
#+begin_src emacs-lisp
|
||||||
|
(when (and (ensure-package-installation 'engrave-faces)
|
||||||
|
(require 'engrave-faces-latex nil t))
|
||||||
|
(defun engrave-faces-latex--color (color)
|
||||||
|
"Convert COLOR loosely to a string of six hexadecimal digits."
|
||||||
|
(if (char-equal ?# (aref color 0))
|
||||||
|
(substring color 1 7)
|
||||||
|
(apply 'format "%02x%02x%02x"
|
||||||
|
(mapcar (lambda (c) (ash c -8))
|
||||||
|
(color-values color)))))
|
||||||
|
|
||||||
|
(defun engrave-faces-latex-face-apply-override (faces content)
|
||||||
|
"Convert attributes of FACES to LaTeX commands applied to CONTENT."
|
||||||
|
(let ((attrs (engrave-faces-merge-attributes faces)))
|
||||||
|
(let ((bg (plist-get attrs :background))
|
||||||
|
(fg (plist-get attrs :foreground))
|
||||||
|
(it (eql (plist-get attrs :slant) 'italic))
|
||||||
|
(bl (member (plist-get attrs :weight) '(bold extra-bold)))
|
||||||
|
(st (plist-get attrs :strike-through)))
|
||||||
|
(concat
|
||||||
|
(when bg (concat "\\colorbox[HTML]{"
|
||||||
|
(engrave-faces-latex--color bg) "}{"))
|
||||||
|
(when fg (concat "\\textcolor[HTML]{"
|
||||||
|
(engrave-faces-latex--color fg) "}{"))
|
||||||
|
(when st "\\sout{") (when bl "\\textbf{") (when it "\\textit{")
|
||||||
|
content
|
||||||
|
(when bg "}") (when fg "}") (when st "}") (when bl "}") (when it "}"))))))
|
||||||
|
|
||||||
|
(with-eval-after-load 'emacs
|
||||||
|
(defun toggle-advice (symbol where function &optional props)
|
||||||
|
"Toggle between states after `advice-remove' and `advice-add'."
|
||||||
|
(let ((how "%s `%s' advice `%s' %s `%s'"))
|
||||||
|
(if (advice-member-p function symbol)
|
||||||
|
(progn
|
||||||
|
(message how "Removal of" where function "from" symbol)
|
||||||
|
(advice-remove symbol function))
|
||||||
|
(message how "Addition of" where function "to" symbol)
|
||||||
|
(advice-add symbol where function props))))
|
||||||
|
|
||||||
|
(defun toggle-engrave-faces-latex-face-apply-override ()
|
||||||
|
"Toggle `engrave-faces-latex-face-apply' advice."
|
||||||
|
(interactive)
|
||||||
|
(toggle-advice 'engrave-faces-latex-face-apply
|
||||||
|
:override #'engrave-faces-latex-face-apply-override))
|
||||||
|
|
||||||
|
(toggle-engrave-faces-latex-face-apply-override))
|
||||||
|
#+end_src
|
||||||
|
|
||||||
|
#+caption[Fix engraving of horizontal/vertical spacing in multiline docstrings]:
|
||||||
|
#+caption: Fix engraving of horizontal and vertical spacing in multiple line
|
||||||
|
#+caption: documentation strings.
|
||||||
|
#+name: lst:ensure-engrave-faces-with-latex-face-mapper-fix
|
||||||
|
#+begin_src emacs-lisp
|
||||||
|
(when (and (ensure-package-installation 'engrave-faces)
|
||||||
|
(require 'engrave-faces-latex nil t))
|
||||||
|
(defun engrave-faces-latex-face-mapper-override (faces content)
|
||||||
|
"Create a LaTeX representation of CONTENT with FACES applied."
|
||||||
|
(let* ((style (engrave-faces-preset-style faces))
|
||||||
|
(protected-content
|
||||||
|
(funcall
|
||||||
|
(if (and engrave-faces-latex-mathescape
|
||||||
|
(eq 'font-lock-comment-face (car style)))
|
||||||
|
#'engrave-faces-latex--protect-content-mathescape
|
||||||
|
#'engrave-faces-latex--protect-content)
|
||||||
|
content)))
|
||||||
|
;; Wrap groups of "words joined by blank characters" in LaTeX commands.
|
||||||
|
;; Do not wrap newlines and other whitespace between those groups.
|
||||||
|
(let ((regexp (rx (or (group-n 1 (+ graph ) (* (+ blank) (+ graph)))
|
||||||
|
(group-n 2 (+ (any "\n" space))))))
|
||||||
|
(slug (when (and style
|
||||||
|
(eq engrave-faces-latex-output-style 'preset))
|
||||||
|
(plist-get (cdr style) :slug)))
|
||||||
|
(start 0) (stack))
|
||||||
|
(while (string-match regexp protected-content start)
|
||||||
|
(setq start (match-end 0))
|
||||||
|
(when-let ((pc (match-string 1 protected-content)))
|
||||||
|
(if (stringp slug)
|
||||||
|
(push (concat "\\EF" slug "{" pc "}") stack)
|
||||||
|
(push (engrave-faces-latex-face-apply faces pc) stack)))
|
||||||
|
(when-let ((pc (match-string 2 protected-content)))
|
||||||
|
(push pc stack)))
|
||||||
|
(apply #'concat (nreverse stack))))))
|
||||||
|
|
||||||
|
(with-eval-after-load 'emacs
|
||||||
|
(defun toggle-engrave-faces-latex-face-mapper-override ()
|
||||||
|
"Toggle `engrave-faces-latex-face-mapper' advice."
|
||||||
|
(interactive)
|
||||||
|
(toggle-advice 'engrave-faces-latex-face-mapper
|
||||||
|
:override #'engrave-faces-latex-face-mapper-override))
|
||||||
|
|
||||||
|
(toggle-engrave-faces-latex-face-mapper-override))
|
||||||
|
#+end_src
|
||||||
|
|
||||||
#+caption[Emacs setup to use =engrave-faces-latex= in =org-mode= smartly]:
|
#+caption[Emacs setup to use =engrave-faces-latex= in =org-mode= smartly]:
|
||||||
#+caption: Emacs setup to use =engrave-faces-latex= in =org-mode= smartly.
|
#+caption: Emacs setup to use =engrave-faces-latex= in =org-mode= smartly.
|
||||||
#+name: lst:ox-engraved-emacs-lisp-setup
|
#+name: lst:ox-engraved-emacs-lisp-setup
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user