[wip-cite-new] New natbib processor

[wip-cite-new] New natbib processor

[Nicolas Goaziou]

Hello,

Another thread! Yay!

I just added a new `natbib' processor in "wip-cite-new" branch, in the
file "oc-natbib.el"

--8<---------------cut here---------------start------------->8---
This library registers the `natbib' citation processor, which provides
the "export" capability for citations.

The processor relies on "natbib" LaTeX package. As such it ensures that
the package is properly required in the generated document. More
precisely, it will use any "\\usepackage{natbib}" command already
present in the document (e.g., through `org-latex-packages-alist'), or
insert one using options defined in `org-cite-natbib-options'.

It supports the following citation styles, in addition to the default
author-year format: "text" or "t", "author" or "a", "year" or "y".

It also supports the following sub-styles: "caps", "alt", and
"full".

Bibliography accepts any style supported by natbib package.
--8<---------------cut here---------------end--------------->8---

As noted, this processor implements "sub-styles", i.e. additional styles
separated with forward slash character. E.g.,

  [cite/text/alt/full:...]  => \citealt*{...}

  [cite//alt/caps:...]      => \Citealp{...}   (// means default style)

However, I'm not convinced by them. 

On the bright side, sub-styles can be put in any order, so we're
avoiding combinatorial explosion of commands.

However, they do not play well with shortcuts. For example, if shortcut
for "caps" is "C" and "full" is "F",

  [cite/text/caps/full:...] is equivalent to [cite/t/C/f:...]

which is not great. Also it introduces ambiguities in style inheritance.
For example, if I add

  #+cite_export: natbib plainnat text

would 

  [cite//alt/caps:...]

mean

  [cite/text/alt/caps:...]   (i.e., \Citealt{...})

or really

  [cite//alt/caps:]          (i.e., \Citealp{...})

?

I'd favor keeping only one level for styles is more reasonable. It means
implementing one style for each variant, e.g., "text-alt-caps" where the
order matters ("text-caps-alt" may not be supported), but it permits
more compact shortcuts, e.g., "Alt" for "text-alt-caps"). It also
eschews the inheritance pitfall above.

Also, completion front-ends can alleviate the burden of memorizing all
those styles.

Anyway, for now it's sub-styles. Please let me know what you think about
them, and about the processor, in general. I couldn't test it much
because the test bibliography I have is apparently "not compatible with
author-year citations".

As a reminder, to test it, you (require 'oc-natbib) to register the
processor, and add "#+cite_export: natbib" in your document (or set
`org-cite-export-processor' to (natbib)).

Regards,
-- 
Nicolas Goaziou

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

On Wed, May 5, 2021 at 10:53 AM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:

> Another thread! Yay!

We should be close to the finish line!

> I just added a new `natbib' processor in "wip-cite-new" branch, in the
> file "oc-natbib.el"

Awesome!

> However, I'm not convinced by them [sub-styles].
>
> On the bright side, sub-styles can be put in any order, so we're
> avoiding combinatorial explosion of commands.
>
> However, they do not play well with shortcuts. For example, if shortcut
> for "caps" is "C" and "full" is "F",
>
>   [cite/text/caps/full:...] is equivalent to [cite/t/C/f:...]
>
> which is not great.

I'm just going to focus on these points.

The question comes down to whether to support sub-styles or not, and
if yes, what the syntax should be.

I think it makes more sense to include them because otherwise you end
up with an insanely long list of styles, which won't map well onto
different kinds of output formats.

E.g. biblatex users will want like 20 commands available, which won't
all work with other formats.

Also consider that for processors, they're going to have to map those
internally to something like styles+sub-styles anyway.

So I think sub-styles are good for users and developers alike.

Syntax?

I see your point on short-cuts; maybe your previous idea would work
better; a plus-separated list?

[cite:t/a+f+c]

... and the full names:

[cite:text/alt+full+caps]

Even if not perfect, I think it's a small price to pay for the benefits.

Bruce

Re: [wip-cite-new] New natbib processor

[Bastien]

"Bruce D'Arcus" <bdarcus@gmail.com> writes:

> On Wed, May 5, 2021 at 10:53 AM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
>
>> Another thread! Yay!
>
> We should be close to the finish line!

We should boost our media coverage for such efforts :)

Joke aside, thank you both very much for keeping the ball rolling,
it's nice to see this area stabilizing, I'm sure it'll be a great
addition for Org 9.5.

-- 
 Bastien

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

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

On Wed, May 5, 2021 at 10:53 AM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:

> As a reminder, to test it, you (require 'oc-natbib) to register the
> processor, and add "#+cite_export: natbib" in your document (or set
> `org-cite-export-processor' to (natbib)).

I did some basic testing, and it seems to work well in general, though
natbib folks will have to report on how well the sub-styles work, in
terms of mapping them to the natbib commands.

Attaching a screenshot with a few input/output variations, and at the
bottom is what the style selection UI I came up with for
bibtex-actions looks like.

Bruce

[-- Attachment #2: Screenshot from 2021-05-05 14-06-59.png --]
[-- Type: image/png, Size: 103195 bytes --]

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

On Wed, May 5, 2021 at 2:08 PM Bruce D'Arcus <bdarcus@gmail.com> wrote:

> I did some basic testing, and it seems to work well in general ...

That was just looking at the citation output, of course.

Now I did the real test: would LaTeX -> PDF work.

Answer: not ATM.

Here's my minimal document:

----
[cite/text/alt:see ;@mann-68]

[cite//alt/caps:@mann-68]

[cite//full:@mann-68]

[cite//caps:@mann-68]

#+cite_export: natbib
#+bibliography: test.bib
----

... but when I run the export, I get an "undefined citation" error.

The key is correct, as is the file name, which is in the same directly
as the test file.

What am I missing?

Bruce

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

BTW, if anyone else wants to test this but wasn't sure how, I put
together this little gist with a minimal init and instructions.

https://gist.github.com/bdarcus/2645f99363fc47ddab2aae24c5d9e66c

Bruce

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

On Wed, May 5, 2021 at 5:25 PM Bruce D'Arcus <bdarcus@gmail.com> wrote:

> Now I did the real test: would LaTeX -> PDF work.
>
> Answer: not ATM.

Probably user error, as I've not compiled bibtex + latex documents in
a long time.

But it doesn't appear the bib file specified in the org file gets
passed to the latex output.

Bruce

Re: [wip-cite-new] New natbib processor

[Denis Maier]

Am 05.05.2021 um 23:25 schrieb Bruce D'Arcus:
> On Wed, May 5, 2021 at 2:08 PM Bruce D'Arcus <bdarcus@gmail.com> wrote:
> 
>> I did some basic testing, and it seems to work well in general ...
> 
> That was just looking at the citation output, of course.
> 
> Now I did the real test: would LaTeX -> PDF work.
> 
> Answer: not ATM.
> 
> Here's my minimal document:
> 
> ----
> [cite/text/alt:see ;@mann-68]
> 
> [cite//alt/caps:@mann-68]
> 
> [cite//full:@mann-68]
> 
> [cite//caps:@mann-68]
> 
> #+cite_export: natbib
> #+bibliography: test.bib
> ----
> 
> ... but when I run the export, I get an "undefined citation" error.
> 
> The key is correct, as is the file name, which is in the same directly
> as the test file.
> 
> What am I missing?

Bruce has sent me his test files, and it turned out to be the bibstyle 
(humannat), which apparently isn't included in current tex distributions.
Question: I can't see why this style should be used according to the 
minimal example Bruce has shared. Is this style added as the default 
style by the exporter? Or did you, Bruce, specify it somewhere?

Denis

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

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

To come back to this ....

On Wed, May 5, 2021, 10:53 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

Also it introduces ambiguities in style inheritance.
> For example, if I add
>
>   #+cite_export: natbib plainnat text
>
> would
>
>   [cite//alt/caps:...]
>
> mean
>
>   [cite/text/alt/caps:...]   (i.e., \Citealt{...})
>
> or really
>
>   [cite//alt/caps:]          (i.e., \Citealp{...})
>
> ?


I added the following to the wiki page, which I think addresses this:

Note that `text/alt` would not make sense, as the sub-style in this case
would override the style.

Bruce

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

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

On Thu, May 6, 2021 at 3:36 AM Denis Maier
<denis.maier.lists@mailbox.org> wrote:

> Bruce has sent me his test files, and it turned out to be the bibstyle
> (humannat), which apparently isn't included in current tex distributions.
> Question: I can't see why this style should be used according to the
> minimal example Bruce has shared. Is this style added as the default
> style by the exporter? Or did you, Bruce, specify it somewhere?

If I add plainnat as style to the org file, I still get the undefined
citation error.

Here's the current file:

[cite/text/alt:see ;@einstein]

[cite//alt/caps:@einstein]

[cite//full:@einstein]

[cite//caps:@einstein]

#+cite_export: natbib plainnat
#+bibliography: test.bib

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

On Thu, May 6, 2021 at 6:06 AM Bruce D'Arcus <bdarcus@gmail.com> wrote:

> If I add plainnat as style to the org file, I still get the undefined
> citation error.

So two things:

1. the bib file isn't include in the latex output
2. Denis noticed bibtex doesn't seem to run; maybe the pdf output
option for latex should use latexmk?

Bruce

Re: [wip-cite-new] New natbib processor

[Nicolas Goaziou]

Hello,

"Bruce D'Arcus" <bdarcus@gmail.com> writes:

> On Wed, May 5, 2021 at 2:08 PM Bruce D'Arcus <bdarcus@gmail.com> wrote:
>
>> I did some basic testing, and it seems to work well in general ...
>
> That was just looking at the citation output, of course.
>
> Now I did the real test: would LaTeX -> PDF work.
>
> Answer: not ATM.
>
> Here's my minimal document:
>
> ----
> [cite/text/alt:see ;@mann-68]
>
> [cite//alt/caps:@mann-68]
>
> [cite//full:@mann-68]
>
> [cite//caps:@mann-68]
>
> #+cite_export: natbib
>
> #+bibliography: test.bib
> ----
>
> ... but when I run the export, I get an "undefined citation" error.
>
> The key is correct, as is the file name, which is in the same directly
> as the test file.
>
> What am I missing?

Your document doesn't contain a "#+print_bibliography" keyword. It is
responsible for adding the "\\bibliography{...}" macro. I don't think it
is possible to produce a PDF without it.

Regards,
-- 
Nicolas Goaziou

Re: [wip-cite-new] New natbib processor

[Nicolas Goaziou]

Hello,

"Bruce D'Arcus" <bdarcus@gmail.com> writes:

> To come back to this ....
>
> On Wed, May 5, 2021, 10:53 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
> wrote:
>
> Also it introduces ambiguities in style inheritance.
>> For example, if I add
>>
>>   #+cite_export: natbib plainnat text
>>
>> would
>>
>>   [cite//alt/caps:...]
>>
>> mean
>>
>>   [cite/text/alt/caps:...]   (i.e., \Citealt{...})
>>
>> or really
>>
>>   [cite//alt/caps:]          (i.e., \Citealp{...})
>>
>> ?
>
>
> I added the following to the wiki page, which I think addresses this:
>
> Note that `text/alt` would not make sense, as the sub-style in this case
> would override the style.

The first case means inheritance ignores sub-styles. Those are added as
a second pass. The second case means anything with a sub-style is
excluded from inheritance. Both make sense.

Did I say I don't like sub-styles already? :)

Regards,
-- 
Nicolas Goaziou

Re: [wip-cite-new] New natbib processor

[Nicolas Goaziou]

Hello,

"Bruce D'Arcus" <bdarcus@gmail.com> writes:

> The question comes down to whether to support sub-styles or not, and
> if yes, what the syntax should be.
>
> I think it makes more sense to include them because otherwise you end
> up with an insanely long list of styles, which won't map well onto
> different kinds of output formats.

I think only oc-citeproc (and oc-basic) may be targetting multiple
output formats. I doubt it would even use styles; I assume that is
entirely determined by the CSL file.

> E.g. biblatex users will want like 20 commands available, which won't
> all work with other formats.

So you would have 20 styles, with shortcuts for the most commons. This
is not insane, and the mapping is done only once.

Styles do not need to be compatible between processors. As a reminder,
there's the "fallback rule". According to it, each processor must:
- provide a default styles;
- map any unknown style to the style above.

Thanks to this, there will not be any incompatibility between documents
upon switching processors.

Agreeing on a small set of common styles is a good thing; this is what
your doing on your wiki. But there is nothing wrong to map
"text-alt-full" style to the default one in another processor. 

Of course, the default style may be unrelated to "text", but is it
a problem in practice? If you switch processor and use complex styles
(here style + sub-styles), you will need to change them anyway, because
the compatibility is so low.

> Also consider that for processors, they're going to have to map those
> internally to something like styles+sub-styles anyway.

Exactly. For developers, it doesn't make a huge difference here.

> Even if not perfect, I think it's a small price to pay for the
> benefits.

I'm still not convinced by the benefits. Could you describe a situation
where sub-styles would be really beneficial?

Regards,
-- 
Nicolas Goaziou

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

Your other message, Nicolas, came in as I finished this, but I'll post
this anyway.

On Thu, May 6, 2021 at 8:11 AM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:

> > I added the following to the wiki page, which I think addresses this:
> >
> > Note that `text/alt` would not make sense, as the sub-style in this case
> > would override the style.
>
> The first case means inheritance ignores sub-styles. Those are added as
> a second pass. The second case means anything with a sub-style is
> excluded from inheritance. Both make sense.
>
> Did I say I don't like sub-styles already? :)

What about a middle-ground, which would be a flat list of sub-styles, like:

- alt
- alt-caps
- alt-caps-full
- caps
- caps-full
- full

You still need to realize the "alt" options don't apply to the text
style, but this is at least simpler?

Bruce

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

On Thu, May 6, 2021 at 8:29 AM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
>
> Hello,
>
> "Bruce D'Arcus" <bdarcus@gmail.com> writes:
>
> > The question comes down to whether to support sub-styles or not, and
> > if yes, what the syntax should be.
> >
> > I think it makes more sense to include them because otherwise you end
> > up with an insanely long list of styles, which won't map well onto
> > different kinds of output formats.
>
> I think only oc-citeproc (and oc-basic) may be targetting multiple
> output formats. I doubt it would even use styles; I assume that is
> entirely determined by the CSL file.

Actually, no; it's determined (mostly) by the processor.

A CSL style defines a single default citation layout, which the
processor modifies depending on what variants it supports.

So most of them support a citet-like option, but it's currently
implemented in the processor; not the style.

> > E.g. biblatex users will want like 20 commands available, which won't
> > all work with other formats.
>
> So you would have 20 styles, with shortcuts for the most commons. This
> is not insane, and the mapping is done only once.

In the UI I'm working on for inserting org-cite citations, I have the
small handful of styles, that users can complete.

https://github.com/bdarcus/bibtex-actions/pull/113

It's simple, and clean; the list of style fits on a single line.

Aside: no, I'm not currently planning to include sub-styles here; was
thinking to allow users to add them after if needed. But that could
change of course.

These will work across the different output formats we've discussed,
so I don't need to add different config options for different targets,
and user documents don't have to change to accommodate them.

> Styles do not need to be compatible between processors. As a reminder,
> there's the "fallback rule". According to it, each processor must:
> - provide a default styles;
> - map any unknown style to the style above.

OK, but that is only a single required default style then.

...

> > Even if not perfect, I think it's a small price to pay for the
> > benefits.
>
> I'm still not convinced by the benefits. Could you describe a situation
> where sub-styles would be really beneficial?

Say a natbib user has a document, maybe even a book, that makes common
use of the text style + some examples of sub-styles.

They want to export that document to both HTML and to PDF.

Using styles + sub-styles means she can use the same source to get
both; the first using the citeproc-org processor, and the second
oc-natbib.

Admittedly, a long list of flat styles could still accommodate this (I
think), but I go back to my UI and config point above.

Do note my suggestion on the previous message that we could simplify
sub-styles and still get these benefits. I do agree it's not necessary
to treat sub-styles as an unordered list.

WDYT of that?

Bruce

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

On Thu, May 6, 2021 at 8:05 AM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:

> Your document doesn't contain a "#+print_bibliography" keyword. It is
> responsible for adding the "\\bibliography{...}" macro. I don't think it
> is possible to produce a PDF without it.

I paste my input/output below.

Shouldn't the output include ...

\bibliography{test}

...?

--- source ---
[cite/text/alt:see ;@einstein]

[cite//alt/caps:@einstein]

[cite//full:@einstein]

[cite//caps:@einstein]

#+print_bibliography

#+cite_export: natbib plainnat
#+bibliography_export: natbib
#+bibliography: test.bib

--- results ---

% Created 2021-05-06 Thu 09:04
% Intended LaTeX compiler: lualatex
\documentclass[11pt]{article}
\usepackage{graphicx}
\usepackage{grffile}
\usepackage{longtable}
\usepackage{wrapfig}
\usepackage{rotating}
\usepackage[normalem]{ulem}
\usepackage{amsmath}
\usepackage{textcomp}
\usepackage{amssymb}
\usepackage{capt-of}
\usepackage{hyperref}
\author{Bruce D'Arcus}
\date{\today}
\title{}
\hypersetup{
 pdfauthor={Bruce D'Arcus},
 pdftitle={},
 pdfkeywords={},
 pdfsubject={},
 pdfcreator={Emacs 27.2 (Org mode 9.4.5)},
 pdflang={English}}
\usepackage[]{natbib}
\begin{document}

\tableofcontents

\citealt{einstein}

\Citealp{einstein}

\citep*{einstein}

\Citep{einstein}

\#+print\textsubscript{bibliography}
\end{document}

Re: [wip-cite-new] New natbib processor

[Nicolas Goaziou]

"Bruce D'Arcus" <bdarcus@gmail.com> writes:

> On Thu, May 6, 2021 at 8:05 AM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
>
>> Your document doesn't contain a "#+print_bibliography" keyword. It is
>> responsible for adding the "\\bibliography{...}" macro. I don't think it
>> is possible to produce a PDF without it.
>
> I paste my input/output below.
>
> Shouldn't the output include ...
>
> \bibliography{test}
>
> ...?
>
> --- source ---
> [cite/text/alt:see ;@einstein]
>
> [cite//alt/caps:@einstein]
>
> [cite//full:@einstein]
>
> [cite//caps:@einstein]
>
> #+print_bibliography

You're missing the colon at the end of the keyword. Note that `org-lint'
warns you about it.

Regards,

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

On Thu, May 6, 2021 at 10:12 AM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:

> You're missing the colon at the end of the keyword. Note that `org-lint'
> warns you about it.

Ugh; sorry about that.

I'm getting out of my depth, as I no longer use LaTeX much, but WYDT
about using latexmk for export -> latex -> pdf, so that bibtex and
such is properly run?

Regardless of the solution, right now the user will get an error with
that export option.

Bruce

Re: [wip-cite-new] New natbib processor

[Nicolas Goaziou]

"Bruce D'Arcus" <bdarcus@gmail.com> writes:

> On Thu, May 6, 2021 at 10:12 AM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
>
>> You're missing the colon at the end of the keyword. Note that `org-lint'
>> warns you about it.
>
> Ugh; sorry about that.
>
> I'm getting out of my depth, as I no longer use LaTeX much, but WYDT
> about using latexmk for export -> latex -> pdf, so that bibtex and
> such is properly run?

This is controlled by `org-latex-pdf-process'; modifying it is out of
the scope of the Org Cite library.

> Regardless of the solution, right now the user will get an error with
> that export option.

I think the default value of the variable above handles BibTeX calls.

Regards,

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

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

On Thu, May 6, 2021 at 12:20 PM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> > I'm getting out of my depth, as I no longer use LaTeX much, but WDYT
> > about using latexmk for export -> latex -> pdf, so that bibtex and
> > such is properly run?
>
> This is controlled by `org-latex-pdf-process'; modifying it is out of
> the scope of the Org Cite library.

Makes sense.

But, and I just put this out there really for more serious LaTeX users to
advocate for this if they think it's a good idea ...

... might it be within scope of org more broadly to consider before
releasing 9.5?

Anyway, I updated my cite-init.el file to include this, and it does indeed
work as expected now.

https://gist.github.com/bdarcus/2645f99363fc47ddab2aae24c5d9e66c

Bruce

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

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

On Thu, May 6, 2021 at 8:37 AM Bruce D'Arcus <bdarcus@gmail.com> wrote:

> On Thu, May 6, 2021 at 8:11 AM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:

> > Did I say I don't like sub-styles already? :)
>
> What about a middle-ground, which would be a flat list of sub-styles, like:

Thinking about it more, some of the intricacies are likely specific to
author-date, and maybe note, styles.

Maybe it's fine to drop them.

There are pros and cons to each; sub-styles just moves some of the
less-common variants there, so the style list can be simpler.

With only styles, however, would probably want to add something like
these, with their possible shortcuts:

- Text (T)
- text-full (tf)
- Text-full (Tf)
- alt (-)
- may also need some alt variants; not sure ATM

Also not sure if additional are needed for the other styles; a "caps" default?

Bruce

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

On Fri, May 7, 2021 at 7:37 AM Bruce D'Arcus <bdarcus@gmail.com> wrote:

> Maybe it's fine to drop them (sub-styles_.
...

> Also not sure if additional are needed for the other styles; a "caps" default?

I can't figure this bit out though.

'[cite:/Text@doe]' is obvious and elegant enough, but how do you do
the same thing for default?

But with some kind of sub-style, you can do:

[cite//c:@doe]

Bruce

Re: [wip-cite-new] New natbib processor

[Nicolas Goaziou]

Hello,

"Bruce D'Arcus" <bdarcus@gmail.com> writes:

> On Fri, May 7, 2021 at 7:37 AM Bruce D'Arcus <bdarcus@gmail.com> wrote:
>
>> Maybe it's fine to drop them (sub-styles_.
> ...
>
>> Also not sure if additional are needed for the other styles; a "caps" default?
>
> I can't figure this bit out though.
>
> '[cite:/Text@doe]' is obvious and elegant enough, but how do you do
> the same thing for default?

This is no longer the default style, but a "caps" style, so it would be

  [cite/caps:...]

>
> But with some kind of sub-style, you can do:
>
> [cite//c:@doe]
>
> Bruce
>

Regards,
-- 
Nicolas Goaziou

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

On Sun, May 9, 2021 at 4:57 AM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
>
> Hello,
>
> "Bruce D'Arcus" <bdarcus@gmail.com> writes:
>
> > On Fri, May 7, 2021 at 7:37 AM Bruce D'Arcus <bdarcus@gmail.com> wrote:

> >> Also not sure if additional are needed for the other styles; a "caps" default?
> >
> > I can't figure this bit out though.
> >
> > '[cite:/Text@doe]' is obvious and elegant enough, but how do you do
> > the same thing for default?
>
> This is no longer the default style, but a "caps" style, so it would be
>
>   [cite/caps:...]

Right.

I tried to summarize the current state here:

https://github.com/bdarcus/bibtex-actions/wiki/Org-cite#variants

To bottom line it, seems the decision comes down to something like
these three choices:

1. no change; keep sub-styles as they are ATM
2. change sub-styles to a simple string. So [cite/text/caps+full:...],
where sub-style is the string "caps+full"; short cut would be
something like [cite:/t/c+f:...]
2. remove sub-styles entirely; just have things like
[cite/text+caps-full:...], where the style is "text+caps-full"; or
with shortcuts [cite/t+c-f:...]

Any of them seem reasonable to me.

Maybe 2 is the best balance of flexibility and simplicity?

Bruce

Re: [wip-cite-new] New natbib processor

[Nicolas Goaziou]

Hello,

"Bruce D'Arcus" <bdarcus@gmail.com> writes:

> To bottom line it, seems the decision comes down to something like
> these three choices:
>
> 1. no change; keep sub-styles as they are ATM
> 2. change sub-styles to a simple string. So [cite/text/caps+full:...],
> where sub-style is the string "caps+full"; short cut would be
> something like [cite:/t/c+f:...]
> 2. remove sub-styles entirely; just have things like
> [cite/text+caps-full:...], where the style is "text+caps-full"; or
> with shortcuts [cite/t+c-f:...]
>
> Any of them seem reasonable to me.
>
> Maybe 2 is the best balance of flexibility and simplicity?

But there are two 2 ;)

I think that sub-styles as currently implemented, i.e., per processor,
are not useful. They could as well be replaced by a list of regular
styles (e.g., "text-caps-full").

Completion is not really an issue either. We could require
export-oriented citation processors to declare the styles they support
through a dedicated keyword in `org-cite-register-processor'.
Completions utilities, like the function you wrote, could then read from
that list.

The question you raise about compatibility between processors is
interesting however. Without sub-styles, non-standard styles (roughly
anything but default, text, author and year) would, as you noted,
fallback to default style upon switching citation processors. E.g.,
"text-caps-full" would become default. With sub-styles, OTOH, fallback
mechanism would be able to grab root style and try using it before
dropping the ball to default. E.g., "text/caps-full" could gracefully
degrade to "text", and, if not supported, default.

Sub-styles buy us nicer switching between processors, indeed. But they
come at a price, too. In particular, we need to re-define inheritance
between styles defined in `org-cite-export-processor', "cite_export"
keyword and the citation object. As I wrote earlier in this thread,
there are multiple ways to deal with it, so a clear design is in order.

Plain styles already exist. Sub-styles requires more work. Does the
benefit outweigh it? If so, what do you suggest for the inheritance
problem?

Regards,
-- 
Nicolas Goaziou

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

On Sun, May 9, 2021 at 4:25 PM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
>
> Hello,
>
> "Bruce D'Arcus" <bdarcus@gmail.com> writes:
>
> > To bottom line it, seems the decision comes down to something like
> > these three choices:
> >
> > 1. no change; keep sub-styles as they are ATM
> > 2. change sub-styles to a simple string. So [cite/text/caps+full:...],
> > where sub-style is the string "caps+full"; short cut would be
> > something like [cite:/t/c+f:...]
> > 3. remove sub-styles entirely; just have things like
> > [cite/text+caps-full:...], where the style is "text+caps-full"; or
> > with shortcuts [cite/t+c-f:...]
> >
> > Any of them seem reasonable to me.
> >
> > Maybe 2 is the best balance of flexibility and simplicity?
>
> But there are two 2 ;)

The nice thing about a wiki is one can always edit one's mistakes!

But I did correct the quoted text above, so I meant the first "2".

See below however ...

...

> Sub-styles buy us nicer switching between processors, indeed. But they
> come at a price, too. In particular, we need to re-define inheritance
> between styles defined in `org-cite-export-processor', "cite_export"
> keyword and the citation object. As I wrote earlier in this thread,
> there are multiple ways to deal with it, so a clear design is in order.
>
> Plain styles already exist. Sub-styles requires more work. Does the
> benefit outweigh it? If so, what do you suggest for the inheritance
> problem?

I guess the question is really about the logic in this function?

(defun org-cite-natbib--style-to-command (style)
  "Return command name to use according to STYLE string."
  (let ((base
         (if (org-cite-natbib--has-substyle-p style "caps")
             "Cite"
           "cite"))
        (alt
         (and (org-cite-natbib--has-substyle-p style "alt")
              "al"))
        (main (pcase (org-cite-natbib--main-style style)
                ((or "text" "t") "t")
                ((or "author" "a") "author")
                ((or "year" "y") "year")
                (_ "p")))
        (star
         (and (org-cite-natbib--has-substyle-p style "full")
              "*")))
    (concat "\\" base alt main star)))

My read of the natbib docs is this should work correctly, except for
the 'year' style, for which 'full' and 'caps' do not apply because
there are no authors output in those styles.

Indeed, if you do something like \Citeyear you will get an error from LaTeX.

So I think you need a conditional that ignores those for that style.

But otherwise, I think this should be fine.

The example you raised in the first post in this thread was the following:

> Also it introduces ambiguities in style inheritance.
> For example, if I add
>
>  #+cite_export: natbib plainnat text

So the default style is "text."

> would
>
>  [cite//alt/caps:...]
>
> mean
>
>  [cite/text/alt/caps:...]   (i.e., \Citealt{...})
>
> or really
>
>  [cite//alt/caps:]          (i.e., \Citealp{...})
>
> ?

First, I am thinking "bare" would be more clear than "alt", at least
if we're shooting for names that are clear outside the content of a
particular output format. WDYT?

On the more important output question, do not those two natbib
commands generate the same final output in the end?

As in, this ambiguity is in natbib itself?

That aside, I think just logically the first makes more sense, because
nowhere does the style or sub-styles specify the "citep" style.
Indeed, that style doesn't exist in the current list. This is what the
code currently produces.

Am I missing something there?

Bruce

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

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

Minor suggestion Nicolas:

Currently, oc-natbib ignores global affixes.

This makes some sense given natbib has no notion of global vs per-cite
affixes.

But it seems ideally the code would preprend the global prefix to the local
prefix of the first cite.

So [cite:global ;local @doe] should yield \citep[global local ][]{doe}.

Not sure about suffixes; maybe (?) those are best ignored.

Bruce

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

Re: [wip-cite-new] New natbib processor

[Nicolas Goaziou]

Hello,

"Bruce D'Arcus" <bdarcus@gmail.com> writes:

> Minor suggestion Nicolas:
>
> Currently, oc-natbib ignores global affixes.

It is slightly more subtle. It ignores global affixes when there is
a single citation reference. With multiple keys, it ignores local
affixes and uses global ones instead.

> But it seems ideally the code would preprend the global prefix to the local
> prefix of the first cite.
>
> So [cite:global ;local @doe] should yield \citep[global local ][]{doe}.

The [cite:global ;local @doe] construct sounds odd. I also find the
current state predictable.

Do you still find concatenation prefix-only concatenation more
appropriate? Also, what would happen with multiple keys?

Regards,
-- 
Nicolas Goaziou

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

On Mon, May 10, 2021 at 4:22 PM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
>
> Hello,
>
> "Bruce D'Arcus" <bdarcus@gmail.com> writes:
>
> > Minor suggestion Nicolas:
> >
> > Currently, oc-natbib ignores global affixes.
>
> It is slightly more subtle. It ignores global affixes when there is
> a single citation reference. With multiple keys, it ignores local
> affixes and uses global ones instead.

I keep forgetting the limitations of natbib; namely, it has no
per-item affixes, so you can't separately specify locators for
individual items when there is more than one in a citation.

E.g. natbib itself only has global affixes, in practice, so the
question is just how to map the more expressive (biblate-inspired)
model of org-cite to that.

Maybe what you have now is good for a first release. We'll have to see
how people respond probably.

Bruce

Re: [wip-cite-new] New natbib processor

[Eric S Fraga]

Just to say that, for my simple use case(s), the latest version in
wip-cite-new is working very well indeed!  Thank you.

-- 
: Eric S Fraga via Emacs 28.0.50, Org release_9.4.5-400-gc88b58

Re: [wip-cite-new] New natbib processor

[Nicolas Goaziou]

Hello,

"Bruce D'Arcus" <bdarcus@gmail.com> writes:

> I guess the question is really about the logic in this function?

No, not really. It was a more general question about handling
style+variant between local specification and global one, independently
on the processor.

> First, I am thinking "bare" would be more clear than "alt", at least
> if we're shooting for names that are clear outside the content of a
> particular output format. WDYT?

OK for "bare".

> That aside, I think just logically the first makes more sense, because
> nowhere does the style or sub-styles specify the "citep" style.
> Indeed, that style doesn't exist in the current list. This is what the
> code currently produces.

Fair enough.

I pushed in "wip-cite-new" an attempt to parse styles as a pair (name .
variant). I also updated oc-natbib.el and oc-basic.el accordingly.

Now, in oc-natbib.el, the LaTeX command is selected like this:

--8<---------------cut here---------------start------------->8---
  (pcase style
    ;; "text" style.
    (`(,(or "text" "t") . ,(or "bare" "b")) "\\citealt")
    (`(,(or "text" "t") . ,(or "caps" "c")) "\\Citet")
    (`(,(or "text" "t") . ,(or "full" "f")) "\\citet*")
    (`(,(or "text" "t") . ,(or "bare-caps" "bc")) "\\Citealt")
    (`(,(or "text" "t") . ,(or "bare-full" "bf")) "\\citealt*")
    (`(,(or "text" "t") . ,(or "caps-full" "cf")) "\\Citet*")
    (`(,(or "text" "t") . ,(or "bare-caps-full" "bcf")) "\\Citealt*")
    (`(,(or "text" "t") . ,_) "\\citet")
    ;; "author" style.
    (`(,(or "author" "a") . ,(or "caps" "c")) "\\Citeauthor")
    (`(,(or "author" "a") . ,(or "full" "f")) "\\citeauthor*")
    (`(,(or "author" "a") . ,_) "\\citeauthor")
    ;; "year" style.
    (`(,(or "year" "y") . ,(or "bare" "b")) "\\citeyear")
    (`(,(or "year" "y") . ,_) "\\citeyearpar")
    ;; Default ("nil") style.
    (`(,_ . ,(or "bare" "b")) "\\citealp")
    (`(,_ . ,(or "caps" "c")) "\\Citep")
    (`(,_ . ,(or "full" "f")) "\\citep*")
    (`(,_ . ,(or "bare-caps" "bc")) "\\Citealp")
    (`(,_ . ,(or "bare-full" "bf")) "\\citealp*")
    (`(,_ . ,(or "caps-full" "cf")) "\\Citep*")
    (`(,_ . ,(or "bare-caps-full" "bcf")) "\\Citealp*")
    (`(,_ . ,_) "\\citep")
    ;; This should not happen.
    (_ (error "Invalid style: %S" style)))
--8<---------------cut here---------------end--------------->8---

So now, you can write a cryptic [cite/t/bcf:@key] and get
\Citealt*{key}.

Feedback welcome, as always.

Regards,
-- 
Nicolas Goaziou

Re: [wip-cite-new] New natbib processor

[Bruce D'Arcus]

On Sat, May 15, 2021 at 5:29 PM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:

...

> I pushed in "wip-cite-new" an attempt to parse styles as a pair (name .
> variant). I also updated oc-natbib.el and oc-basic.el accordingly.

Looks good to me, and seems a good balance.

You mention it was "an attempt"; WDYT of the result?

Bruce

Re: [wip-cite-new] New natbib processor

[Nicolas Goaziou]

Hello,

"Bruce D'Arcus" <bdarcus@gmail.com> writes:

> On Sat, May 15, 2021 at 5:29 PM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
>> I pushed in "wip-cite-new" an attempt to parse styles as a pair (name .
>> variant). I also updated oc-natbib.el and oc-basic.el accordingly.
>
> Looks good to me, and seems a good balance.

Thanks.

> You mention it was "an attempt"; WDYT of the result?

I like simplicity; plain styles are simple.

I cannot tell if it is really useful yet. This change is supposed to
ease switching from one processor to another, but no other processor is
relying on variants so far. Someone™ needs to write "oc-citeproc.el" or
"oc-biblatex.el" to see them in action.

So, I'll defer to your judgement.

Regards,
-- 
Nicolas Goaziou