oc: Enhance style UI

[bdarcus]

With the new "insert" processor I added, I am just using the same simple UI as oc-basic.

But there's room to do much more; say something like this mockup:

Here's what org-cite-supported-styles returns:

((("author" "a")
  ("caps" "c"))
 (("noauthor" "na")
  ("bare" "b"))
 (("nocite" "n"))
 (("note" "ft")
  ("caps" "c")
  ("bare-caps" "bc"))
 (("numeric" "nb"))
 (("text" "t")
  ("caps" "c")
  ("bare-caps" "bc"))
 (("nil")
  ("caps" "c")
  ("bare-caps" "bc")
  ("bare" "b")))

Possibilities:

1. allow users to configure whether to use full style name or shortcuts
2. support sub-style variants somehow (but would need to be elegant and efficient)
3. add annotations/affixations to make it easier for users to know what a given choice will result in; but this would have to be adjustable by style category (author-date, note, etc.), or be a kind of live preview (which would need to rely on citeproc/CSL, so not sure how general that could be)

[bdarcus]

@andras-simonyi - moving that sub-thread here, for consolidation.

https://github.com/andras-simonyi/citeproc-el/issues/15#issuecomment-882037958 https://github.com/andras-simonyi/citeproc-el/issues/15#issuecomment-882045167

For context, my (edited) question was:

I'm wanting to write a function that presents the list of styles + variants, but also includes a preview of the result.... Do you know of a clever way to do this that would work across processors?

And @andras-simonyi's response:

Depends on what you mean by "a preview of the result". Would the ensuing LaTeX citation command be an acceptable preview for the LaTeX processors?

Yes; in fact, that's what I want.

I do see there's the org-cite-natbib--style-to-command function, but not an equivalent for oc-biblatex, and not a public function (though that's a minor issue, and I imagine if this is generally valuable, it could be added).

For the CSL processor, on the other hand, it seems absolutely doable to provide a rendered preview as it is done by the CSL activation processor.

What's the best/easiest way to do that?

It doesn't have to be even close to perfect; it just has to allow the user to see what they are choosing in the completion UI, similar to org-cite-activate.

Ideally, I guess (?), if one had a consolidated list of styles/variants, it would display the preview of whatever export processors were supported.

So with the update to citeproc and oc-csl, and user had it and bibltatex configured, maybe:

text                   \textcite           Doa (2019)

... but if they only had oc-natbib configured, then:

text                   \citet        

Maybe could look something like this, where the highlighted fragment is for the currently active (or default?) mode?

Actually, if a style isn't supported, it will use default, if variant not supported, fallback to style.

So the UI would need to signal that too; perhaps with different faces.

[andras-simonyi]

@bdarcus wrote

I do see there's the org-cite-natbib--style-to-command function, but not an equivalent for oc-biblatex, and not a public function (though that's a minor issue, and I imagine if this is generally valuable, it could be added).

in oc-biblatex the biblatex command itself, without the leading slash and the arguments is generated by the large pcase expression in org-cite-natbib--style-to-command -- this could be extracted into a function.

For the CSL processor, on the other hand, it seems absolutely doable to provide a rendered preview as it is done by the CSL activation processor.

What's the best/easiest way to do that?

I think -- especially for a POC -- you can basically copy the beginning of org-cite-csl-activate, the only difference is that the rendering function will be simpler, i.e., instead of org-cite-csl-activate--fontify-rendered you will need something along the lines of

(defun csl-render-citation (citation)
  "Render CITATION."
  (let ((proc (your-cached-processor)))
    (citeproc-clear proc)
    (let* ((info (list :cite-citeproc-processor proc))
       (cit-struct (org-cite-csl--create-structure citation info)))
      (citeproc-append-citations (list cit-struct) proc)
      (car (citeproc-render-citations proc 'plain t)))))

[bdarcus]

I opened a branch to get started, and added a small question on the draft PR about the cached processor.

[bdarcus]

in oc-biblatex the biblatex command itself, without the leading slash and the arguments is generated by the large pcase expression in org-cite-natbib--style-to-command -- this could be extracted into a function.

Done.

We probably need an org-cite-style-to-command function.

[jkitchin]

I am not sure about this. \citet can look like lots of different things depending on the style that bib(la)tex uses. For me, it is almost always a number, with different kinds of brackets, superscripted, etc.

Personally I find the mapping of noauthor to citeyear unintuitive. what about citetitle, citedate, citeurl?

Your idea of annotating the styles to show what they map to is a good one though. I can also see that being in a tooltip on the cite style part.

[bdarcus]

I am not sure about this. \citet can look like lots of different things depending on the style that bib(la)tex uses. For me, it is almost always a number, with different kinds of brackets, superscripted, etc.

I will say in general, there are for sure details to figure out. But I thought this might be a productive alternative to having to do custom styles, and insert and export processors.

The mockup probably doesn't communicate it very well, but the columns are just designed to preview the output target of the processors a user has configured; for latex, it's the commands, and for CSL, it's the final output.

So that rendered column isn't intending to represent the output of the other column; it's simply what the user would get if they use the csl export processor.

One of those details I mention to figure out is how the style for those CSL previews is selected. Maybe it's what is default, or set in the document?

I did figure out that it makes sense to have the preview mappings be configurable. So currently in #182, they're just simple alists, which I can use for the completion-tables.

Personally I find the mapping of noauthor to citeyear unintuitive. what about citetitle, citedate, citeurl?

I'm not following the last fragment here. Certainly citedate seems like it might be reasonable, but title or url?

I will say the "noauthor" name was probably the most difficult, and it's not ideal. But it was intended to be more general in oc, so in some contexts will result in more than just a year or date. But we didn't notice a precise equivalent in natbib.

Aside: "noauthor" is really aka "suppress author" in the CSL world, which was partially a reasonable hack around the lack of formal support for \citet kind of commands. So you see that in pretty much all CSL implementations, including pandoc. But programmers figured out to extend a CSL implementation to cover \cite was trivial: cite/a/b + cite/na.

In general, though, we did what we could with the feedback we got. Certainly if something seems just wrong, it would make sense to report it as a bug.

I will also say I expect by far the most commonly used styles, that are most important to work consistently, are the default ones, and the "text" ones. It's for that reason I put those styles and variants at the top of the alists I mention above, though of course a good completion UI will sort by recency and such.

BTW, @andras-simonyi implemented support for many of the missing styles and variants in oc-csl, so that should be coming soon too. So that even if you focus on natbib or biblatex, the csl preview, including activation, should still be helpful.

Your idea of annotating the styles to show what they map to is a good one though. I can also see that being in a tooltip on the cite style part.

Yes.

So this is what I was meaning about trying to figure out a path forward that is modular.

I am not certain, but I am pretty sure that writing a style selection function as I am slowly working on in #182, should be portable across different implementations.

As in, I think you could drop it into your code (see org-cite-make-insert-processor), and it would work, since ivy supports completing-read.

[bdarcus]

Still more to do, but the basics of grouping and annotation are working:

[jkitchin]

Nice. I implemented this sort of in my inserter. I am not sure if I can do groups with ivy yet, but I like the idea. I am probably going to modify the styles to maximize compatibility with csl where possible.

[bdarcus]

Looking good!

I am probably going to modify the styles to maximize compatibility with csl where possible.

That would be great :-)

FWIW, I forget if I mentioned this, but @andras-simonyi merged support for wider range of styles and variants in the past few days:

https://github.com/andras-simonyi/citeproc-el/commit/0dcf371a34c54b20afd8fde9d0b3198c87d0eff1

This should make it into oc-csl.el "soon" hopefully, so would be a natural step to then add that to the previews.

I actually currently have the "preview-targets" configured in a defcustom, though am not sure if that's the best approach (it could be automated).

Edit: it is worth me making explicit what may not always be obvious:

From early on, CSL took a deliberately more minimalist approach to citation styles or commands, both for user simplicity, and also for output flexibility (that changing styles dramatically would still produce good output).

There has its cons for sure, but also big advantages as well.

I doubt oc-csl will ever support as many style and variant combination as oc-biblatex, nor will that support all the options available in biblatex. But I expect a nice balance to settle in, that combined with the fallback behavior of the processors (that if Andras doesn't support text/bcf, citeproc-el will still output text, for example) will gives users lots of flexibility, and a high degree of document portability across the export processors.

And we can tweak things as we learn.