Re: [O] Citation syntax: a revised proposal

[Nicolas Goaziou]

Hello,

Richard Lawrence <address@hidden> writes:

> Since discussion seems to have petered out on the previous thread (see:
> http://thread.gmane.org/gmane.emacs.orgmode/94524), I took some time to
> go back over the discussion and write up a concrete proposal for
> citation syntax.
>
> This proposal represents my attempt to formulate a syntax that is easy
> to read, easy to parse, and covers all the use-cases that people
> mentioned as being important.  It is surely not perfect, but I learned a
> lot from the previous thread, and I hope something like this will serve
> the community's needs.

Thanks for your proposal. Some comments follow.

> The difference between parenthetical and in-text citations is
> expressed using parentheses around the /first/ citation key.  A
> parenthetical citation has such parentheses around the first citation
> key; an in-text citation lacks them.  (Parentheses around non-initial
> keys are permitted for visual consistency and to keep the grammar
> simple, but have no meaning.)

I think it would be nicer to differentiate between in-text and
parenthetical citations at the type level, e.g.:


  [cite: this @key citation is in-text]
  [(cite): this @key citation is parenthetical]

or, as already suggested

  [citet: ...]
  [citep: ...]

I prefer the former.

>   1) a parenthetical citation for a single work with no prefix and
>      suffix may be written by just surrounding the key with brackets,
>      like: address@hidden
>   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.
> (Thus, in both of the `simple' cases, one less level of bracketing is
> required.)

Sounds good.

> *** Syntax for extensions 
> Additional information can be supplied in a citation that may affect
> how export filters or particular backends format it.
>
> This additional information may be supplied following the brackets of
> a citation between the following delimiters: `%%( ... )'.

As pointed out, this is very odd. But I cannot see any clean solution.
However, it would be nice to integrate it somehow with the syntax. Maybe
something like

  [cite: ... @key ...; ... @key2 ... |latex: :prop val |html: :prop val]

> ** Outstanding issues
> It seems to me that there are potential problems with the above
> proposal in a number of areas, but I cannot tell how serious they are,
> or what changes (if any) should be made to solve them.  I don't
> pretend that this is an exhaustive list:
>   1) *Nesting.*  I have favored LaTeX compatibility for in-text
>      citations with multiple references; but this means there is no
>      way to `nest' citations.  Thus, there is no way to express (in
>      the main syntax) what Pandoc expresses as:
>         @Doe99 [p. 34; see also @DoeRoe2000]
>      which renders like:
>         Doe (1999, p. 34; see also Doe and Roe 2000)
>      Instead, since a citation is in-text or parenthetical as a whole,
>      the equivalent in the above syntax
>         [cite: @Doe99 p. 34; see also @DoeRoe2000]
>      should render like:
>       Doe (1999, p. 34), see also Doe and Roe (2000).
>      I am not certain if Pandoc-like output is important in this case.
>      The few people who commented on this said that it was not.

AFAIU, when using in-text citation, only the first key is extracted out
of the parenthesis, so

  [cite: @Doe99 p. 34; see also @DoeRoe2000]

should really render like

  Doe (1999, p. 34; see also Doe and Roe 2000).

IOW, why do you think that "a citation is in-text or parenthetical as
a whole"?

>   2) *Limitations on prefixes and suffixes.*  There may be legitimate
>      uses of `@', `;', `]', etc. inside prefix or suffix text that the
>      above syntax does not allow.  Examples might include:
>      - use of semi-colons as part of the prefix/suffix text
>      - footnotes, links, or timestamps inside a prefix/suffix
>      I am not certain how important these cases are.  If they are
>      important, some of them might be able to be worked around with
>      entities.

Indeed. Entities are the way to go. If it isn't sufficient we'll need to
provide an escaping mechanism. This may be used elsewhere in Org.

>   4) *Citation commands.*  Rather than introduce an explicit
>      representation for different citation commands/types, I have used
>      different parts of the syntax to express the common distinctions
>      that people mentioned.  I suggest that, for now, anything beyond
>      these basic distinctions be left to the user-extension syntax.
>      However, if it becomes clear in the future that there is a need
>      to add a representation for a command to the main syntax, there
>      is a natural place to do so: immediately after the `cite:' tag
>      (as Nicolas suggested).

With extensions, it is not necessary to support another location for
commands. E.g.,

  [cite: @Doe |latex: :command citedwim]

or whatever extension syntax is chosen.

> Also, I have not said anything in this proposal to address how other
> document metadata should be represented, which has not been discussed
> much on the list.  I think this should be discussed separately.

Indeed. One step at a time. And this one is rather big.


Regards,

-- 
Nicolas Goaziou