From: Timothy <tecosaur@gmail.com>
To: "Clément Pit-Claudel" <cpitclaudel@gmail.com>
Cc: Emacs developers <emacs-devel@gnu.org>
Subject: Re: Core package offering - engrave-faces.el
Date: Fri, 16 Jul 2021 21:08:15 +0800 [thread overview]
Message-ID: <87h7guxv7k.fsf@gmail.com> (raw)
In-Reply-To: <7319ffa7-d566-41b8-b778-69db2f6becc9@gmail.com>
Hi Clément, thanks for your email. I'll paste your reply that you kindly
linked and respond inline.
Clément Pit-Claudel <cpitclaudel@gmail.com> writes:
>> Unlike htmlize, Engrave Faces provides general functionality to
>> transform a buffer into another format with font-lock information.
>> This core functionality is currently made us of in
>> engrave-faces-latex.el, engrave-faces-ansi.el, and engrave-faces-html.el
>> to provide exporters for LaTeX, ASCII/ANSI, and HTML.
>
> Neat! But, I'm not sure I understand what the package actually does. Can you
> give a short example of the API and the results it produces?
Sure! So each of the engrave-faces-FORMAT.el files defines 1-2 user
facing interactive functions:
- engrave-faces-FORMAT-buffer, and maybe
- engrave-faces-FORMAT-buffer-standalone
These both return a new buffer which is an export of the current to
FORMAT.
So for example if I have an elisp buffer which only contains
(funcall #'message "hi")
and call M-x engrave-faces-latex-buffer I will be taken to a new buffer
containing
\color[HTML]{383a42}\textcolor[HTML]{4078f2}{(}\EFc{funcall} \EFhq{\#'}\EFhs{message} \EFs{"hi"}\textcolor[HTML]{4078f2}{)}
and M-x engrave-faces-latex-buffer will give
<span style="color: #4078f2;">(</span><span class="ef-c">funcall</span> <span class="ef-hq">#'</span><span class="ef-hs">message</span> <span class="ef-s">"hi"</span><span style="color: #4078f2;">)</span>
While the -standalone variants will generate a valid LaTeX/HTML document
with a preamble defining some of the commands/classes seen above.
Meanwhile, the most notable part of the core library itself
(engrave-faces.el) would be the macro `engrave-faces-define-backend'.
This could really do with a good docstring, but it takes
- a format name FORMAT
- the file extension for FORMAT
- a "face transforming" function
What this "face transforming" function needs to do is given a list of
faces applying to a certain content string, generate a new string that
applies that information to the content in FORMAT.
There's a rather nice helper function which I expect to be made use of
here, `engrave-faces-merge-attributes' which will take a face spec list
(as simple as "(default)" or complex as "((:weight bold :inherit
default) warning highlight (:extend t))") and a list of attributes, and
resolve all the attributes for that face spec while considering the
'saved' faces in `engrave-faces-preset-styles' -- returning a plist like:
(:foreground #FCCE7B :background #51afef :slant nil :weight bold :height nil :strike-through nil)
This can then be used to create a transformed version of the content
with face information in FORMAT like:
<span style="color: #FCCE7B; background-color: #51afef; weight: bold">content...</span>
With such a "face transforming" function `engrave-faces-define-backend'
will create the user-facing function `engrave-faces-FORMAT-buffer' which
will apply this transformation across the whole buffer.
I hope this gives you a better idea of what this package is doing :)
> If I understand correctly, the following may be relevant:
>
> https://github.com/cpitclaudel/esh (I mention it because it supports exporting
> overlays to HTML and LaTeX, too, and it uses a tricky algorithm to correctly
> handle overlapping fontification)
> https://github.com/Lindydancer/faceup
> https://github.com/Lindydancer/face-explorer
Interesting. I have not seen many of these before.
>> For comparison, htmlize.el is 1700 sloc and htmlfontify.el is 2200 sloc.
>
> My experience is that getting faces right is hard, so I'm not sure I'd assume
> these thousands of lines are just due to bloat ^^
Regarding the the thousands of lines being "bloat", I do not think that
this is the case, and I suspect that not (yet) handling overlays is has
made my job much easier with engrave-faces.el. However, from my usage I
have not found any clear failings with the current approach. To get a
sample of how things look see the attachments to my original email.
Should you be interested in seeing how a LaTeX export of some code
looks, I can refer you to https://tecosaur.github.io/emacs-config/config.pdf.
This is mostly elisp but has a sprinkling of other languages too.
Having looked at htmlize.el a bit I noticed that:
- It was hard to get a clear picture of what's going on easily
- The HTML generation and face-processing parts where deeply intertwined
With this package I'm aiming to create:
- A simpler, smaller (as much as possible), easier to understand core
- Separate the concerns of processing face information and creating a
representation in a certain format(s)
- Have the face processing be generalised such that creating exporters
in certain formats is a much easier task
I expect the current state of affairs has room for improvement, but I
feel it has also reached a state where it is plausibly useful :)
Please let me know if this has answered your questions, and if you have
any more.
--
Timothy
next prev parent reply other threads:[~2021-07-16 13:08 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-07-09 17:39 Core package offering - engrave-faces.el Timothy
2021-07-09 21:14 ` Clément Pit-Claudel
2021-07-16 6:04 ` Timothy
2021-07-16 7:09 ` Eli Zaretskii
2021-07-16 7:36 ` Timothy
[not found] ` <7319ffa7-d566-41b8-b778-69db2f6becc9@gmail.com>
2021-07-16 13:08 ` Timothy [this message]
2021-07-23 15:49 ` Timothy
2021-07-23 20:08 ` Clément Pit-Claudel
2021-07-24 5:54 ` Eli Zaretskii
2021-07-23 20:32 ` Stefan Monnier
2021-08-29 19:11 ` Timothy
2021-08-29 23:33 ` Stefan Monnier
2021-08-30 18:22 ` Timothy
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87h7guxv7k.fsf@gmail.com \
--to=tecosaur@gmail.com \
--cc=cpitclaudel@gmail.com \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.