Re: [O] Citation syntax: a revised proposal

[Richard Lawrence]

Hi Nicolas and all,

Nicolas Goaziou <address@hidden> writes:

> Richard Lawrence <address@hidden> writes:
>
>> Actually, your post has convinced me that it may be worth allowing some
>> explicit name for a type in the [cite: ...] part of the syntax, although
>> I am still leery about what this would mean for non-LaTeX backends.
>
> Each back-end can decide to use it or simply ignore it. Also [cite:...]
> should be equivalent to [cite:default: ...], for some value of "default"
> decided by the target back-end.

I know that this is technically easy to handle from the backend's
perspective.  But I have a concern related to Stefan's: 

Stefan Nobis <address@hidden> writes:

> The drawback is that now subtype is hard or even impossible to vary
> for different backends. Therefore I would suggest that either org has
> to define the allowed values of subtype or else we should define that
> subtype has to be handled by the user (e.g. for use in private filter
> functions) and is out of the scope of org (maybe this would be a good
> place of extensions like org-ref to plug in their machinery).

Basically, I am worried that neither of these options is very good.  

If the subtype is interpreted by backends, I think it will become hard
to use as an author.  If each backend treats different subtypes as
significant, but some backends overlap in which subtypes they accept,
then as an author you have to keep track of which subtypes work in which
backends, and which don't, and whether the default behavior is OK for
your citations in backends you care about.  If you are targeting more
than one backend, that could mean a lot of trips to the manual.  And if
user-supplied subtypes are also permissible, you have to keep track of
the distinction between `official' subtypes and your own.

On the other hand, if the subtype is just a user-supplied label, which
can be interpreted by a filter but which backends will otherwise ignore,
things are nice and simple.  You just don't use a subtype unless you are
also supplying a way to interpret it on every backend that you care
about.  But that kind of situation is exactly what the extra-info part
of the syntax is for; in that case,

  [cite/my-subtype: ...] 

would just be an exceptional way of writing

  [cite: ...]{:type my-subtype}

or whatever.  I'm not totally convinced yet that the convenience of the
former is worth blurring the line between `stuff that definitely works
on all backends' and `stuff that might not work on all backends'.

> Moreover [cite: ...]{...} syntax really makes sense if it is the
> equivalent to #+attr_... keywords, so we can generalize it to links. As
> a consequence, {...} should include a reference to back-end. E.g.,
>
>   [cite:...]{latex :color pink}

We have already seen a couple of examples in this thread of properties
that one might want to specify in a backend-agnostic way:
  - special-case capitalization
  - user-defined type/command/label/etc.

Other things one might want to do include:
  - indicating when a citation should be placed in a footnote 
  - extracting arbitrary bibliographic field(s)
  - providing an overlay string for displaying complicated/ugly citations 

And I think there is no reason, at the moment, to expect that these are
the only possible uses for arbitrary backend-agnostic properties that a
user can interpret, either via export filters or via in-buffer
customizations.

So I suggest that we also allow backend-agnostic properties here in
addition to backend-specific ones.  My preference would be that we just
let these backend-agnostic properties occur at the front, and separate
the backend-specific ones with labeled pipes, like you suggested
earlier:

  [cite: ...]{:my-key1 my-val1 ... |latex: :lkey1 lval1 ... |html: ...} 

I'm OK with disallowing the backend-agnostic properties for other types
of objects if that is necessary, though I don't see how it would hurt to
allow them, as long as it's not Org's responsibility to interpret them.
 
Best,
Richard