[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [O] Citation syntax: a revised proposal
From: |
Nicolas Goaziou |
Subject: |
Re: [O] Citation syntax: a revised proposal |
Date: |
Sun, 15 Feb 2015 18:19:16 +0100 |
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
- Re: [O] Citation syntax: a revised proposal, (continued)
Re: [O] Citation syntax: a revised proposal, Tory S. Anderson, 2015/02/15
Re: [O] Citation syntax: a revised proposal, Rasmus, 2015/02/15
Re: [O] Citation syntax: a revised proposal, Nicolas Goaziou, 2015/02/15
Re: [O] Citation syntax: a revised proposal,
Nicolas Goaziou <=
- Re: [O] Citation syntax: a revised proposal, Rasmus, 2015/02/15
- Re: [O] Citation syntax: a revised proposal, Richard Lawrence, 2015/02/15
- Re: [O] Citation syntax: a revised proposal, Nicolas Goaziou, 2015/02/15
- Re: [O] Citation syntax: a revised proposal, Aaron Ecay, 2015/02/15
- Re: [O] Citation syntax: a revised proposal, Nicolas Goaziou, 2015/02/15
- Re: [O] Citation syntax: a revised proposal, Aaron Ecay, 2015/02/15
- Re: [O] Citation syntax: a revised proposal, Nicolas Goaziou, 2015/02/15
- Re: [O] Citation syntax: a revised proposal, Rasmus, 2015/02/15