From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: Re: Citation syntax: a revised proposal Date: Sun, 15 Feb 2015 18:19:16 +0100 Message-ID: <87zj8fjdnv.fsf@nicolasgoaziou.fr> References: <87k2zjnc0e.fsf@berkeley.edu> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:54695) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YN2ph-0002od-QC for emacs-orgmode@gnu.org; Sun, 15 Feb 2015 12:18:18 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YN2pc-0003NM-EP for emacs-orgmode@gnu.org; Sun, 15 Feb 2015 12:18:13 -0500 Received: from relay6-d.mail.gandi.net ([2001:4b98:c:538::198]:55358) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YN2pc-0003N9-4t for emacs-orgmode@gnu.org; Sun, 15 Feb 2015 12:18:08 -0500 In-Reply-To: <87k2zjnc0e.fsf@berkeley.edu> (Richard Lawrence's message of "Sat, 14 Feb 2015 18:29:05 -0800") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Richard Lawrence Cc: emacs-orgmode@gnu.org Hello, Richard Lawrence 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: [@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. > (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