From mboxrd@z Thu Jan 1 00:00:00 1970 From: Richard Lawrence Subject: Re: Citation syntax: a revised proposal Date: Sun, 15 Feb 2015 08:40:33 -0800 Message-ID: <87bnkvm8la.fsf@berkeley.edu> References: <87k2zjnc0e.fsf@berkeley.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:50155) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YN2GA-0001gR-Ll for emacs-orgmode@gnu.org; Sun, 15 Feb 2015 11:41:35 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YN2G5-0007g0-JU for emacs-orgmode@gnu.org; Sun, 15 Feb 2015 11:41:30 -0500 Received: from plane.gmane.org ([80.91.229.3]:54224) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YN2G5-0007fq-CW for emacs-orgmode@gnu.org; Sun, 15 Feb 2015 11:41:25 -0500 Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1YN2Fz-0006Ng-Nk for emacs-orgmode@gnu.org; Sun, 15 Feb 2015 17:41:19 +0100 Received: from c-67-169-117-151.hsd1.ca.comcast.net ([67.169.117.151]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Sun, 15 Feb 2015 17:41:19 +0100 Received: from richard.lawrence by c-67-169-117-151.hsd1.ca.comcast.net with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Sun, 15 Feb 2015 17:41:19 +0100 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: emacs-orgmode@gnu.org Hi Tom, tsd@tsdye.com (Thomas S. Dye) writes: > 0 > > A syntax that relegates citation commands to an extension that might not > export properly in future versions of Org mode isn't useful in my work. Sorry to disappoint! I tried really hard to represent in the [cite: ...] syntax all the particular cases of citation commands that people said were important, including the ones you suggested. But maybe I missed something, or maybe you have other suggestions. If so, I am happy to try again. It is true that the [cite: ...] syntax does not support specifying an arbitrary citation command. The point of this is to keep the number of features that Org would initially commit to making work in all backends at a reasonable level, while still encompassing all the important cases. If you need arbitrary extensions, that is what the %%(...) part of the syntax is for. Let me try to clarify what I was thinking about this, since I didn't say much about it in the proposal. I don't know if this will address your concern, but I hope it will at least partly do so. Basically, I'm thinking of the %%(...) part of the syntax as a kind of playground; it represents `everything we haven't decided about yet', and is meant to encompass both user-extensions and backend-specific extensions. If we treat %%(...) as an arbitrary s-expression, then it should already be flexible enough to allow people who need even the most esoteric citation commands to implement them via export filters. But like all user extensions that execute arbitrary code on arbitrary data, Org is not in a position to *guarantee* that it will work forevermore. (For example, your filter might call an Org function that could one day be removed or renamed, at which point it will break.) Hence this warning: > *At least for now*, any information supplied this way is /strictly the > user's responsibility/ to interpret (e.g., using an export filter). > This means that citations that have information like this are not > portable and might not be exported correctly: > - in other users' setups > - by particular backends > - by future versions of Org Note that exactly the same warning applies to links with custom types and similar user extensions, even if the manual is less explicit about it. In practice, I expect that the information in %%(...) clauses will be at least as stable and portable as information in custom links. (By the way, just to be super clear: `correctly' in the above warning means `handling the extra information correctly'. I didn't mean to imply that even the default export behavior could go awry.) Eventually, we may find that lots of people have similar needs that they are dealing with in %%(...) syntax. At that point, we may want to adopt stricter conventions for some parts of this syntax. For example, I assume we might eventually want a convention that the LaTeX backend will correctly handle properties that look like: %%(... :attr_latex (:command "\somecitecommand[%PRE][%POST]{%KEY}") ...) Once such a convention is discussed and adopted, Org could then officially support it, and the above warning would no longer apply, except the part about other backends. Likewise, if we find cases that are important enough that they need to work on all backends, representations for those cases could be added to the [cite: ...] part of the syntax. So really, the idea I had in splitting the syntax into [cite: ...] and %%(...) was to give us a good starting point that can be built on in the future -- not to relegate important features to the dustbin. Sorry that I did not make that clearer in the proposal! Best, Richard