Improve the `engrave-faces' section

This commit is contained in:
Gerard Vermeulen 2023-01-01 13:43:44 +01:00
parent c6b5804223
commit 8216f87ba1

View File

@ -243,7 +243,7 @@ The [[info:emacs#Init File][init file (info)]] does not load the ~custom-file~ a
'(eglot . "gnu-devel"))
(embark . "gnu-devel")
(embark-consult . "gnu-devel")
(engrave-faces . "gnu")
(engrave-faces . "gnu-devel")
(hyperbole . "gnu-devel")
(marginalia . "gnu-devel")
(org . "gnu-devel")
@ -2464,34 +2464,39 @@ valid directories and files. In an [[https://orgmode.org/][Org-mode]] buffer th
:CUSTOM_ID: sec:engrave-faces
:END:
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
specific output formats and Org offers it as an alternative to =minted=. *The
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 to my satisfaction:*
This package has a front-end that processes fontified buffers and pipes its
output into one of three back-ends for export to LaTeX, HTML and text with ANSI
escape codes. It is an alternative to =minted= in case of LaTeX export or to
=htmlized= in case of HTML export. The listings below work around three issues
with spacing in the =pdf= output resulting from =LaTeX= export by means of [[info:org#Source blocks in LaTeXexport][Org
source block export to LaTeX (info)]] and [[https://github.com/tecosaur/engrave-faces#readme][Engrave Faces]]. They increase the
quality of the export results of this [[file:README.org][README.org]] to a level acceptable for my
workflow:
1. The default Org export configuration for engraving listings produces =pdf=
output with a non-equidistant interline spacing in floating listings and
equidistant interline spaces non-floating =tcolorbox= environments. I have
traced non-equidistance interline spacing back to the =breakable= option in
=Code= environments inside =listing= environments. However, =tcolorbox=
requires =breakable= for listings that do not fit on a page. As a
work-around, the filter =org-latex-engraved-source-block-filter= in listing
traced the non-equidistant interline spacing back to the =breakable= option
of =Code= environments inside =listing= environments. However, =tcolorbox=
requires =breakable= for listings that do not fit on a page. The filter
=org-latex-engraved-source-block-filter= in listing
[[lst:org-latex-engraved-source-block-filter]] and the
=org-latex-engraved-preamble= customization in listing
[[lst:smart-latex-engrave-org-source-blocks]] allow to engrave =org-mode= source
blocks to "floating unbreakable with a caption" or "non-floating breakable
without a caption" LaTeX environments.
blocks to "floating unbreakable with caption" or "non-floating breakable
without caption" LaTeX environments. This is a partial work-around, but part
of my workflow.
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 faces in for instance
src_emacs-lisp{(find-library "org-faces")} and src_emacs-lisp{(find-library
"faces")} have symbolic color names (beware: Emacs themes may replace the
symbolic color names with hexadecimal strings), this fix allows to engrave
org-mode source blocks during LaTeX export without any further tweaking.
for instance org-mode source blocks during LaTeX export without any
customization of =engrave-faces-themes=.
3. Listing [[lst:ensure-engrave-faces-with-latex-face-mapper-fix]] makes
=engrave-faces-latex-face-mapper= handle horizontal and vertical spacing
in multiple line documentation strings correctly. For instance, *without this
fix* the mishandling of vertical and horizontal spacing destroys the
in multiple line documentation strings correctly. For instance, without this
fix the mishandling of vertical and horizontal spacing destroys the
indentation in Python documentation strings. An Emacs lisp example of the
bug is the disappearance of the empty line in the documentation string of
=org-latex-engraved-source-block-filter= of listing
@ -2586,7 +2591,7 @@ environments and non-floating breakable LaTeX environments by means of
#+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 :tangle no
#+begin_src emacs-lisp
(when (and (ensure-package-installation 'engrave-faces)
(require 'engrave-faces-latex nil t))
(defun engrave-faces-latex--color (color)
@ -2622,7 +2627,7 @@ environments and non-floating breakable LaTeX environments by means of
#+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 :tangle no
#+begin_src emacs-lisp
(when (require 'engrave-faces-latex nil t)
(defun engrave-faces-latex-face-mapper-override (faces content)
"Create a LaTeX representation of CONTENT with FACES applied."