modify citation links in a derived HTML backend

modify citation links in a derived HTML backend

[Matt Price]

[-- Attachment #1: Type: text/plain, Size: 1714 bytes --]

Hi,

(cc:ing Jens L. in case this is relevant for his dev work on org-re-reveal).

I'm experimenting with the new citation syntax in slideshows generated with
org-re-reveal.  Mostly it works fine, but cite-links don't function
properly in the slideshow because in reveal, internal links only work when
they refer to a slide (which will generally be generated from a headline in
org-re-reveal export). Otherwise, the framework will reject the location
change.  At least, that's how I read the code here:
https://github.com/hakimel/reveal.js/blob/ade234576e8ddd683cf16d0d8bb0236f37cf1a99/js/controllers/location.js#L32.


Ideally, there would be some way to override this behaviour, but at present
I don't see how to do that from within Reveal.

I also know it is possible to just eliminate the links using
org-cite-csl-no-citelink-backends, but that is a significant loss of
function.

Instead, I would like to modify the links that surround the individual
citations. At present, the generated code will look something like this:

<a href="#citeproc_bib_item_3">Zubaida, 2009</a>

and I'd like to change it to something like this:

<a href="#bibliography">Zubaida, 2009</a>

From what I can tell so far, the current behaviour of oc-csl is dictated by
a lambda defined in the citeproc package, and set via defconst in an alist
`citeproc-fmt--html-alist` defined in citeproc-formatters.el.

My question: what's the best way to override the output of citation objects
for a specific derived backend? Can I use an export filter? should I
instead use, I don't know, cl-letf to temporarily override some internal
function belonging to citeproc-formatters and return a modified link?

thanks as always for the help!

Matt

[-- Attachment #2: Type: text/html, Size: 2269 bytes --]

Re: modify citation links in a derived HTML backend

[Jens Lechtenboerger]

[-- Attachment #1: Type: text/plain, Size: 539 bytes --]

On 2021-07-02, Matt Price wrote:

> Hi,
>
> (cc:ing Jens L. in case this is relevant for his dev work on org-re-reveal).

Hi Matt,

just a quick reply: Yes, that is certainly relevant for me, but I do
not have the time to investigate this at the moment.  Note that I
use references with org-ref and org-re-reveal-ref (for which Bruce
opened an issue for org-cite support [1]).  Currently, I configure
org-ref-ref-html (although its doc string suggests otherwise).

Best wishes
Jens

[1] https://gitlab.com/oer/org-re-reveal-ref/-/issues/2

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5290 bytes --]

Re: modify citation links in a derived HTML backend

[Matt Price]

[-- Attachment #1: Type: text/plain, Size: 5017 bytes --]

Thanks Jens!

I've added some comments in the issue you linked to, but in the meantime
I've also come up with what seems to be at least a semi-viable hack for
adding native CSL citation support to org-re-reveal. It involves creating
two new variables and then let-setting `citeproc-fmt--formatters-alist` in
`org-re-reveal-export-to-html`. Something similar could presumably be done
in other derived backends.

I find it quite hackish and I don't know whether perhaps some more general
solution could be found, but in any case here is the code, which I have
inserted into org-re-reveal.el locally:

Something to note here is that `oc-csl.el` hard-codes the output format
options in org-cite-csl--output-formats. I wonder if it would be worth
having an extensible variable "org-cite-csl--output-format-alist" that
backends could modify if they have special needs. For instance, I am
thinking about website exporters like Hugo where authors might want to have
separate bibliography pages rather than endnotes, or add "title" attributes
to citations, or possibly even modal tooltips with formatted text.  It
probably doesn't make sense to build all of that in to citeproc.el, but
assing some additional information seems worthwhile.
-------------
(defvar org-re-reveal-citeproc-fmt-alist
  `((unformatted . citeproc-fmt--xml-escape)
    (cited-item-no . ,(lambda (x y) (concat "<a
href=\"#slide-bibliography""\">"
   x "</a>")))
    (bib-item-no . ,(lambda (x y) (concat "<a name=\"citeproc_bib_item_" y
"\"></a>"
 x)))
    (font-style-italic . ,(lambda (x) (concat "<i>" x "</i>")))
    (font-style-oblique . ,(lambda (x)
    (concat "<span style=\"font-style:oblique;\"" x "</span>")))
    (font-variant-small-caps . ,(lambda (x)
 (concat
  "<span style=\"font-variant:small-caps;\">" x "</span>")))
    (font-weight-bold . ,(lambda (x) (concat "<b>" x "</b>")))
    (text-decoration-underline .
                               ,(lambda (x)
                         (concat
                          "<span style=\"text-decoration:underline;\">" x
"</span>")))
    (rendered-var-url . ,(lambda (x) (concat "<a href=\"" x "\">" x
"</a>")))
    (rendered-var-doi . ,(lambda (x) (concat "<a href=\"" x "\">" x
"</a>")))
    ;;(rendered-var-title . ,(lambda (x) (concat "<a href=\"" x "\">" x
"</a>")))
    (vertical-align-sub . ,(lambda (x) (concat "<sub>" x "</sub>")))
    (vertical-align-sup . ,(lambda (x) (concat "<sup>" x "</sup>")))
    (vertical-align-baseline . ,(lambda (x) (concat "<span
style=\"baseline\">" x "</span>")))
    (display-left-margin . ,(lambda (x) (concat "\n    <div
class=\"csl-left-margin\">"
x "</div>")))
    (display-right-inline . ,(lambda (x) (concat "<div
class=\"csl-right-inline\">"
x "</div>\n  ")))
    (display-block . ,(lambda (x) (concat "\n\n    <div
class=\"csl-block\">"
 x "</div>\n")))
    (display-indent . ,(lambda (x) (concat "<div class=\"csl-indent\">" x
"</div>\n  ")))))

(defvar org-re-reveal-formatters-alist
  `((html . ,(citeproc-formatter-create
           :rt (citeproc-formatter-fun-create
org-re-reveal-citeproc-fmt-alist)
           :bib #'citeproc-fmt--html-bib-formatter))))

(defun org-re-reveal-export-to-html
    (&optional async subtreep visible-only body-only ext-plist backend)
  "Export current buffer to a reveal.js HTML file.
Optional ASYNC, SUBTREEP, VISIBLE-ONLY, BODY-ONLY, EXT-PLIST are passed
to `org-export-to-file'.
Optional BACKEND must be `re-reveal' or a backend derived from it."
  (interactive)
  (let* ((backend (or backend 're-reveal))
         (extension (concat "." org-html-extension))
         (client-ext (concat org-re-reveal-multiplex-client-ext extension))
         (file (org-export-output-file-name extension subtreep))
         (clientfile (org-export-output-file-name client-ext subtreep))
         (org-html-container-element "div")
         (citeproc-fmt--formatters-alist org-re-reveal-formatters-alist))

    (setq org-re-reveal-client-multiplex nil)
    (org-export-to-file backend file
      async subtreep visible-only body-only ext-plist)

    ;; Export the client HTML file if org-re-reveal-client-multiplex is set
true
    ;; by previous call to org-export-to-file
    (if org-re-reveal-client-multiplex
        (org-export-to-file backend clientfile
          async subtreep visible-only body-only ext-plist))
    file))
------------------------

On Sat, Jul 3, 2021 at 3:53 AM Jens Lechtenboerger <
lechten@wi.uni-muenster.de> wrote:

> On 2021-07-02, Matt Price wrote:
>
> > Hi,
> >
> > (cc:ing Jens L. in case this is relevant for his dev work on
> org-re-reveal).
>
> Hi Matt,
>
> just a quick reply: Yes, that is certainly relevant for me, but I do
> not have the time to investigate this at the moment.  Note that I
> use references with org-ref and org-re-reveal-ref (for which Bruce
> opened an issue for org-cite support [1]).  Currently, I configure
> org-ref-ref-html (although its doc string suggests otherwise).
>
> Best wishes
> Jens
>
> [1] https://gitlab.com/oer/org-re-reveal-ref/-/issues/2
>

[-- Attachment #2: Type: text/html, Size: 6788 bytes --]

Re: modify citation links in a derived HTML backend

[Jens Lechtenboerger]

[-- Attachment #1: Type: text/plain, Size: 1038 bytes --]

On 2021-07-03, Matt Price wrote:

> I've added some comments in the issue you linked to, but in the meantime
> I've also come up with what seems to be at least a semi-viable hack for
> adding native CSL citation support to org-re-reveal. It involves creating
> two new variables and then let-setting `citeproc-fmt--formatters-alist` in
> `org-re-reveal-export-to-html`. Something similar could presumably be done
> in other derived backends.
>
> I find it quite hackish and I don't know whether perhaps some more general
> solution could be found, but in any case here is the code, which I have
> inserted into org-re-reveal.el locally:

Thank you for sharing your code, Matt!

What is the general state of this new citation handling with respect
to export backends?  Did you create the settings for HTML from
scratch or did you take inspiration from HTML export functionality?
I guess that basic support should go into ox-html, while small
modifications could than take care of specifics for reveal.js
presentations...

Best wishes
Jens

[-- Attachment #2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 5290 bytes --]

Re: modify citation links in a derived HTML backend

[Matt Price]

[-- Attachment #1: Type: text/plain, Size: 5228 bytes --]

On Sun, Jul 4, 2021 at 8:56 AM Jens Lechtenboerger <
lechten@wi.uni-muenster.de> wrote:

> On 2021-07-03, Matt Price wrote:
>
> > I've added some comments in the issue you linked to, but in the meantime
> > I've also come up with what seems to be at least a semi-viable hack for
> > adding native CSL citation support to org-re-reveal. It involves creating
> > two new variables and then let-setting `citeproc-fmt--formatters-alist`
> in
> > `org-re-reveal-export-to-html`. Something similar could presumably be
> done
> > in other derived backends.
> >
> > I find it quite hackish and I don't know whether perhaps some more
> general
> > solution could be found, but in any case here is the code, which I have
> > inserted into org-re-reveal.el locally:
>
> Thank you for sharing your code, Matt!
>
> What is the general state of this new citation handling with respect
> to export backends?  Did you create the settings for HTML from
> scratch or did you take inspiration from HTML export functionality?
> I guess that basic support should go into ox-html, while small
> modifications could than take care of specifics for reveal.js
> presentations...
>
> Best wishes
> Jens
>

Thanks Jens!

So, there is a rather complicated chain of dependencies and I'm not sure
how best to procee in the specific case of org-re-reveal.

Here is how I understand the current state of affairs (and I think Bruce,
Nicolas, and Andras are all likely to have corrections to my explanation):

- the new syntax and processors are available in the wip-cite-new branch of
hte org git repo, and will likely be merged into the master branch pretty
soon.
- at present, and likely for some time, the best citation processor for
html export is defined in `oc-csl.el` and relies on the citeproc-el
library.  My code will only have an effect if the org file contains lines
like
--------------
#+bibliography: food-studies.bib
#+cite_export: csl "/home/matt/src/styles/chicago-author-date-mod.csl"
----------------
- oc-csl.el relies on citeproc-el to actually process the citations.
- citeproc-el is a fairly complex package with many moving parts. It
supports processing of citations in html and latex backends, but not in any
others (I think this is right!)
- citation formatting is handled in the file citation-formatters. el (
https://github.com/andras-simonyi/citeproc-el/blob/master/citeproc-formatters.el),
which, importantly, uses lexical binding. That file defines:
  -  a *structure* citeproc-formatter (
https://github.com/andras-simonyi/citeproc-el/blob/0857973409e3ef2ef0238714f2ef7ff724230d1c/citeproc-formatters.el#L35
),
 - a *function* citeproc-formatter-fun-create (
https://github.com/andras-simonyi/citeproc-el/blob/0857973409e3ef2ef0238714f2ef7ff724230d1c/citeproc-formatters.el#L51
)
- a *constant* citeproc-fmt--html-alist (
https://github.com/andras-simonyi/citeproc-el/blob/0857973409e3ef2ef0238714f2ef7ff724230d1c/citeproc-formatters.el#L142
)
- and a *variable* citeproc-fmt--formatters-alist (
https://github.com/andras-simonyi/citeproc-el/blob/0857973409e3ef2ef0238714f2ef7ff724230d1c/citeproc-formatters.el#L232)
that creates a set of formatters using citeproc-formmater-fun-create,
bassing it the value of citeproc-fmt--html-alist as raw material for the
html formatter.

The latter is what we need to change for our export -- we want to change
just one of the lambda functions used by the formatter for the duration of
export, without updating the global value of citeproc-fmt--formatters-alist.

Because all these variables are lexically bound -- making the resultant
closure values pretty confusing for me to inspect -- and because the
process of creating a formatter is a bit complex, I was a little  confused
about how best to modify the code, and I'm still not quite sure how to go
about it.  It's pretty easy to do this using the dash library:

-----
(let ((org-re-reveal-citeproc-fmt-alist
       (--map-when (eq  (car it) 'cited-item-no)
              `(cited-item-no . ,(lambda (x y) (concat "<a
href=\"#slide-bibliography\">" x "</a>")))
              citeproc-fmt--html-alist)))
 [do some exporting stuff])
-------
or just

-----
(defcustom org-re-reveal-citeproc-fmt-alist
 (--map-when (eq  (car it) 'cited-item-no)
              `(cited-item-no . ,(lambda (x y) (concat "<a
href=\"#slide-bibliography\">" x "</a>")))
              citeproc-fmt--html-alist)
:group org-re-reveal
:type alist)
------

But I'm not sure how best to do it without that.

In any case, the code I have provided here and in gitlab (
https://gitlab.com/oer/org-re-reveal/-/merge_requests/33) is quite hackish
and doubtless likely to error out in many circumstances. Probably I should,
in org-re-reveal-export-to-html,  at least test if the function
citeproc-formatter-fun-create is bound, so:

----------
(let ((citeproc-fmt--formatters-alist
          (and (functionp 'citeproc-formatter-create)
               `((html . ,(citeproc-formatter-create
                  :rt (citeproc-formatter-fun-create
org-re-reveal-citeproc-fmt-alist)
                  :bib #'citeproc-fmt--html-bib-formatter))))))
....do stuff)

(actually, I simplified my merge request to use all this code).

Does that help the explanation? And what do you think?

[-- Attachment #2: Type: text/html, Size: 7687 bytes --]