Re: Citation syntax: a revised proposal

[Richard Lawrence <richard.lawrence@berkeley.edu>]

Hi Rasmus,

Rasmus <rasmus@gmx.us> writes:

> 0
>
> Parts I like:  
>
>    1) a parenthetical citation for a single work with no prefix and
>       suffix may be written by just surrounding the key with brackets,
>       like: [@Doe99].
>    2) an in-text citation for a single work with no prefix and suffix
>       may be written as a /bare/ key, without brackets, like: @Doe99.
>
> I recently cracked up something similar for a paper we are working on, and
> I think it's nice.  I have yet to get the verdict from my coauthor,
> though.

Cool. :)

> Parts that I don't care for:
>
>      [cite: whatever (@Doe99) whatever]
>
> Not intuitive to me, but I could get used to it.

It's not super intuitive to me either, and it just occurred to me
yesterday, so maybe there's a better way.  The reason I went this way
was so that we could represent the difference between parenthetical and
in-text citations without moving the cite key and without using
different tags (citet: vs. citep:).  That makes it easy to write a
function that will quickly switch a citation between the two styles,
without using the tag to express the difference, which Nicolas was
worried would slow down the parser.

> Parts I hate:
>
>     The flag is either `@' or `&'.  `@' [...] The optional hyphen (`-') 
>
> Too many weird symbols that I won't be able to remember, much less explain
> to somebody else.

I don't love these either, but I am not sure what a better alternative
would be.  The `@' is vestigial inspiration from Pandoc, and is used
infrequently enough elsewhere in Org syntax that Nicolas at one point
said it would be OK performance-wise to have `@key' appear alone in the
text.  `&' seemed like a natural counterpart for the same reasons, but I
agree it isn't terribly intuitive.  (Though maybe there's one supporting
intuition: `&' is used to introduce keys in URL parameters...)

I disagree with you about the hyphen, but I wouldn't use it enough to
lobby for it (it is just vestigial Pandoc).  If others think we should
take it out, that's fine with me.

>     `%%( ... )'.
>
> Just too odd.  Extensibilty should not be delegated to some weird
> construct outside of the element in question.

Again, I don't exactly love this either, but I chose this syntax because
%%(...) is already used elsewhere in Org to represent embedded
s-expressions (notably in timestamps -- see section 8.1 of the manual).
%(...) is also used for s-expressions in capture templates, though I'm
not sure why the first case uses two `%'s and the second only one.

The only reason to use these delimiters is consistency; I'm not opposed
to something prettier if there's a better alternative.

Keeping this part of the syntax outside the [cite: ...] brackets allows
it to be used with bare keys for simple in-text citations, and prevents
a further syntactic restriction on prefix/suffix text inside the
brackets.  I'm not opposed to moving it inside if that seems really
important, but these two considerations weigh against it in my opinion.

Best,
Richard