From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: Re: Citation syntax: a revised proposal Date: Wed, 18 Feb 2015 20:42:12 +0100 Message-ID: <87twyjnh0r.fsf@nicolasgoaziou.fr> References: <87k2zjnc0e.fsf@berkeley.edu> <87bnkvm8la.fsf@berkeley.edu> <87zj8co3se.fsf@berkeley.edu> <87ioezooi2.fsf@berkeley.edu> <87mw4bpaiu.fsf@nicolasgoaziou.fr> <8761aznpiq.fsf@berkeley.edu> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:39442) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YOAUl-0003PK-7B for emacs-orgmode@gnu.org; Wed, 18 Feb 2015 14:41:16 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YOAUg-0005I7-0C for emacs-orgmode@gnu.org; Wed, 18 Feb 2015 14:41:15 -0500 Received: from relay6-d.mail.gandi.net ([2001:4b98:c:538::198]:48830) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YOAUf-0005Hz-Ci for emacs-orgmode@gnu.org; Wed, 18 Feb 2015 14:41:09 -0500 In-Reply-To: <8761aznpiq.fsf@berkeley.edu> (Richard Lawrence's message of "Wed, 18 Feb 2015 08:38:37 -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 Richard Lawrence writes: > I know that this is technically easy to handle from the backend's > perspective. But I have a concern related to Stefan's: > > Stefan Nobis writes: > >> The drawback is that now subtype is hard or even impossible to vary >> for different backends. Therefore I would suggest that either org has >> to define the allowed values of subtype or else we should define that >> subtype has to be handled by the user (e.g. for use in private filter >> functions) and is out of the scope of org (maybe this would be a good >> place of extensions like org-ref to plug in their machinery). > > Basically, I am worried that neither of these options is very good. > > If the subtype is interpreted by backends, I think it will become hard > to use as an author. If each backend treats different subtypes as > significant, but some backends overlap in which subtypes they accept, > then as an author you have to keep track of which subtypes work in which > backends, and which don't, and whether the default behavior is OK for > your citations in backends you care about. If you are targeting more > than one backend, that could mean a lot of trips to the manual. And if > user-supplied subtypes are also permissible, you have to keep track of > the distinction between `official' subtypes and your own. I wasn't clear. Subtype should be interpreted by back-ends means it has no impact on syntax. However a user should be able to dictate what the back-end should do with it, much like `org-add-link-type'. A new library, e.g. "org-cite.el" would provide all the tools necessary to build custom handlers for subtypes. Thus, power users can do whatever they want with cite objects. Nevertheless, Org needs to provide at least one built-in handler so casual users are not required to do anything when writing [cite: see @Doe98 p.87] or even @Doe99. This default handler may be also customized by power users, but we're not there yet. > On the other hand, if the subtype is just a user-supplied label, which > can be interpreted by a filter but which backends will otherwise ignore, > things are nice and simple. You just don't use a subtype unless you are > also supplying a way to interpret it on every backend that you care > about. But that kind of situation is exactly what the extra-info part > of the syntax is for; in that case, > > [cite/my-subtype: ...] > > would just be an exceptional way of writing > > [cite: ...]{:type my-subtype} > > or whatever. I'm not totally convinced yet that the convenience of the > former is worth blurring the line between `stuff that definitely works > on all backends' and `stuff that might not work on all backends'. > >> Moreover [cite: ...]{...} syntax really makes sense if it is the >> equivalent to #+attr_... keywords, so we can generalize it to links. As >> a consequence, {...} should include a reference to back-end. E.g., >> >> [cite:...]{latex :color pink} > > We have already seen a couple of examples in this thread of properties > that one might want to specify in a backend-agnostic way: > - special-case capitalization > - user-defined type/command/label/etc. > > Other things one might want to do include: > - indicating when a citation should be placed in a footnote > - extracting arbitrary bibliographic field(s) I disagree. These properties should be associated to the subtype. Having two places to set them is asking for trouble. IMO, there is little incentive to define a set of options for a single use. Creating a dedicated subtype /once/ makes more sense. Also the syntax stays clean. > - providing an overlay string for displaying complicated/ugly > citations I don't think Org should provide this. Overlays are slow. Also, there is no good default for displaying citations. However, an external library could do that. > And I think there is no reason, at the moment, to expect that these are > the only possible uses for arbitrary backend-agnostic properties that a > user can interpret, either via export filters or via in-buffer > customizations. Export filters are orthogonal to the problem at hand. They are applied after handlers. We are discussing about handlers here (e.g., there are custom link types and export filters for links). > So I suggest that we also allow backend-agnostic properties here in > addition to backend-specific ones. My preference would be that we just > let these backend-agnostic properties occur at the front, and separate > the backend-specific ones with labeled pipes, like you suggested > earlier: > > [cite: ...]{:my-key1 my-val1 ... |latex: :lkey1 lval1 ... |html: ...} > > I'm OK with disallowing the backend-agnostic properties for other types > of objects if that is necessary, though I don't see how it would hurt to > allow them, as long as it's not Org's responsibility to interpret > them. I think we should postpone the idea of attributes for object, as it gets in the way of the discussion. IMO, [cite/subtype: ...] is all we need, syntax-wise. Regards,