From mboxrd@z Thu Jan 1 00:00:00 1970 From: Matt Price Subject: Re: Citations, continued Date: Mon, 2 Feb 2015 10:09:14 -0500 Message-ID: References: <87vbjmn6wy.fsf@berkeley.edu> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary=089e0112c4ae59c130050e1c56b3 Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:47421) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YIIco-0008AY-3N for emacs-orgmode@gnu.org; Mon, 02 Feb 2015 10:09:20 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YIIcl-0005Zq-CA for emacs-orgmode@gnu.org; Mon, 02 Feb 2015 10:09:17 -0500 Received: from mail-la0-x231.google.com ([2a00:1450:4010:c03::231]:48071) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YIIck-0005Zj-UE for emacs-orgmode@gnu.org; Mon, 02 Feb 2015 10:09:15 -0500 Received: by mail-la0-f49.google.com with SMTP id gf13so41586453lab.8 for ; Mon, 02 Feb 2015 07:09:14 -0800 (PST) In-Reply-To: <87vbjmn6wy.fsf@berkeley.edu> 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: Org Mode --089e0112c4ae59c130050e1c56b3 Content-Type: text/plain; charset=UTF-8 I have very little of substance to say, but many thanks to Richard for raising the level of discourse to a much more sophisticated one than I was able to achieve in my initial post. I don't feel qualified to comment on whether links or a new citation syntax is appropriate. But I do think that Richard and the rest of you have identified the key features that any future syntax should follow. I guess I would emphasize that Richard's insistence on the experience of a document writer is very important -- it should be straightforward to add citations from whatever sources we use, to read and work with those citations in org itself, and to export them painlessly to the other major formats in which our work is shared (I think the main ones right now and for the foreseeable future are LaTex, ODT/Docx, and HTML). And that should be true even for people who are not so good at fiddling with presentation details. >From my perspective, citation support is really the only writerly feature "missing" from org; if it can be put in place, I will be thrilled and thankful. Finally, I did want to describe one other syntax I've recently learned about, which is used by Zotero's odf-scan plugin ( http://zotero-odf-scan.github.io/zotero-odf-scan/); these are text citations of this type: {pre | -Author (Date) | p. XX | post | ZOTEROKEY } The scanner will convert these to ODT citations, and multiple citations strung together will be formatted as a multi-source citation. I find these pretty easy to read, though there is certainly room for improvement. On Sat, Jan 31, 2015 at 1:26 PM, Richard Lawrence < richard.lawrence@berkeley.edu> wrote: > Hi all, > > I wanted to continue the discussion that began in this thread about > adding citation support to Org: > http://thread.gmane.org/gmane.emacs.orgmode/94352/focus=94412 > > Here are some thoughts I have after reviewing that discussion: > > 1) Lots of people seem to need/want better support for citations in Org > documents. Other projects (Pandoc among them) already have support for > citations which is good enough that at least some people are using them > to fill this perceived gap in Org's support. > > 2) There are at least several different backend reference database > formats (BibTeX, Zotero, etc.) used by Orgsters. Not all such databases > use human-readable keys. Org also has a nice internal format for > storing reference information: org-bibtex. > > 3) There are also several different frontend solutions for making > citations in Org documents (org-ref, various `home-brewed' solutions, > raw LaTeX \cite commands, etc.). The variety here is at least in part > due to our different requirements for the format of exported documents: > e.g., some people only care about exporting to LaTeX, others need > something that will work for HTML or ODT; some people need to specify > pre- and post-text for citations; some people need to specify citation > types. > > 4) Because individual Orgsters have widely varying needs, there is some > disagreement about what `proper' citation support should look like. (Do > we need new syntax, or can existing syntax be used? Which features need > to be supported by Org, and which can be provided by external tools? > etc.) > > It seems there are three distinct but related problems: > - representing citations in Org documents > - exporting citations in an Org document to a backend document format > like LaTeX, ODT, or HTML > - searching for and manipulating keys in a reference database from > within Org, and otherwise fostering good communication between > such a database and citations in Org documents > > Here's my personal opinion about how we might solve them. > > As for the first problem, I think a good case can be made for adding new > syntax to Org to represent citations, instead of repurposing/extending > existing syntax (most notably, the link syntax). > > Here's why. Citations are complicated, and it's clear that some sort of > new syntax is needed to represent them. Even link-based solutions > introduce new syntax `inside' the link syntax, such as using `::' to > separate pre-text and post-text in a link description, as org-ref does. > Thus, the issue is not *whether* there should be additional syntax, but > just *how constrained* it should be. In particular, the question is > whether we want to make citation syntax a subset of link syntax, or > whether citations and links should be distinct types of syntactic > elements. > > It seems to me that the needs of citation users are wide enough and > complicated enough that it is worth shedding the constraints imposed by > the link syntax. Eventually, packing all the representations we need > for a general solution (citation type, pre- and post-text, suppressing > author name, etc. etc.) into the link syntax will tend to make citations > unreadable. > > Moreover, citations are not really links, even though it is often useful > to treat them (or parts of them) as links. For example, a link can only > point to one target; yet a single citation often points to multiple > sources. And what if you need different pre- or post-text for different > sources within the same citation, like ``See @Doe1999 for an overview; a > more extensive discussion is in @Foobar2000''? > > Finally, it seems to me that Org strives to be a document format which > is usable independently of any particular export format. This counts in > favor of having citation syntax as a first-class citizen in Org; at > present, Org documents can only contain citations through a combination > of extensions and external tools. > > For these reasons, I would support a separate citation syntax, but one > that can behave like a link when useful. For example, suppose we > borrowed the Pandoc [ ... @key1 ...; ... @key2 ...] syntax. When point > is on `@key1', C-c C-o could be bound to find the key in the reference > database, or another useful action, depending on the reference database > format. > > As I mentioned in the earlier thread, I think the Pandoc syntax is a > good place to start, and I think it would be valuable to have the two > syntaxes be compatible. But even Pandoc's citation syntax might not be > general enough to satisfy everyone's needs, so the first step for > introducing citation syntax to Org should be compiling a list of all the > things such a syntax should represent. > > The other problems, I think, must wait until a stable citation syntax > emerges -- export support in particular. (Using an existing syntax from > another project could help ease the transition here: if people can > export citations using an existing tool, they'll be able to switch to > that syntax immediately, and use the external tool in the meantime while > Org-internal support for it catches up.) > > I hope this is a useful starting point for further discussion! > > Best, > Richard > > > --089e0112c4ae59c130050e1c56b3 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable
I have very little of substa= nce to say, but many thanks to Richard for raising the level of discourse t= o a much more sophisticated one than I was able to achieve in my initial po= st.=C2=A0

I don't feel qualified to comment on whether li= nks or a new citation syntax is appropriate.=C2=A0 But I do think that Rich= ard and the rest of you have identified the key features that any future sy= ntax should follow.=C2=A0 I guess I would emphasize that Richard's insi= stence on the experience of a document writer is very important -- it shoul= d be straightforward to add citations from whatever sources we use, to read= and work with those citations in org itself, and to export them painlessly= to the other major formats in which our work is shared (I think the main o= nes right now and for the foreseeable future are LaTex, ODT/Docx, and HTML)= . And that should be true even for people who are not so good at fiddling w= ith presentation details.

From my perspective, citation suppor= t is really the only writerly feature "missing" from org; if it c= an be put in place, I will be thrilled and thankful.=C2=A0

Fi= nally, I did want to describe one other syntax I've recently learned ab= out, which is used by Zotero's odf-scan plugin (http://zotero-odf-scan.github.io/zot= ero-odf-scan/); these are text citations of this type:

{pr= e | -Author (Date) | p. XX | post | ZOTEROKEY }

The scanner w= ill convert these to ODT citations, and multiple citations strung together = will be formatted as a multi-source citation.=C2=A0

I find th= ese pretty easy to read, though there is certainly room for improvement.

On Sat, Ja= n 31, 2015 at 1:26 PM, Richard Lawrence <richard.lawrence@berk= eley.edu> wrote:
Hi all,<= br>
I wanted to continue the discussion that began in this thread about
adding citation support to Org:
http://thread.gmane.org/gmane.emacs.orgmode/94352/focus= =3D94412

Here are some thoughts I have after reviewing that discussion:

1) Lots of people seem to need/want better support for citations in Org
documents.=C2=A0 Other projects (Pandoc among them) already have support fo= r
citations which is good enough that at least some people are using them
to fill this perceived gap in Org's support.

2) There are at least several different backend reference database
formats (BibTeX, Zotero, etc.) used by Orgsters.=C2=A0 Not all such databas= es
use human-readable keys.=C2=A0 Org also has a nice internal format for
storing reference information: org-bibtex.

3) There are also several different frontend solutions for making
citations in Org documents (org-ref, various `home-brewed' solutions, raw LaTeX \cite commands, etc.).=C2=A0 The variety here is at least in part=
due to our different requirements for the format of exported documents:
e.g., some people only care about exporting to LaTeX, others need
something that will work for HTML or ODT; some people need to specify
pre- and post-text for citations; some people need to specify citation
types.

4) Because individual Orgsters have widely varying needs, there is some
disagreement about what `proper' citation support should look like.=C2= =A0 (Do
we need new syntax, or can existing syntax be used?=C2=A0 Which features ne= ed
to be supported by Org, and which can be provided by external tools?
etc.)

It seems there are three distinct but related problems:
=C2=A0 - representing citations in Org documents
=C2=A0 - exporting citations in an Org document to a backend document forma= t
=C2=A0 =C2=A0 like LaTeX, ODT, or HTML
=C2=A0 - searching for and manipulating keys in a reference database from =C2=A0 =C2=A0 within Org, and otherwise fostering good communication betwee= n
=C2=A0 =C2=A0 such a database and citations in Org documents

Here's my personal opinion about how we might solve them.

As for the first problem, I think a good case can be made for adding new syntax to Org to represent citations, instead of repurposing/extending
existing syntax (most notably, the link syntax).

Here's why.=C2=A0 Citations are complicated, and it's clear that so= me sort of
new syntax is needed to represent them.=C2=A0 Even link-based solutions
introduce new syntax `inside' the link syntax, such as using `::' t= o
separate pre-text and post-text in a link description, as org-ref does.
Thus, the issue is not *whether* there should be additional syntax, but
just *how constrained* it should be.=C2=A0 In particular, the question is whether we want to make citation syntax a subset of link syntax, or
whether citations and links should be distinct types of syntactic
elements.

It seems to me that the needs of citation users are wide enough and
complicated enough that it is worth shedding the constraints imposed by
the link syntax.=C2=A0 Eventually, packing all the representations we need<= br> for a general solution (citation type, pre- and post-text, suppressing
author name, etc. etc.) into the link syntax will tend to make citations unreadable.

Moreover, citations are not really links, even though it is often useful to treat them (or parts of them) as links.=C2=A0 For example, a link can on= ly
point to one target; yet a single citation often points to multiple
sources.=C2=A0 And what if you need different pre- or post-text for differe= nt
sources within the same citation, like ``See @Doe1999 for an overview; a more extensive discussion is in @Foobar2000''?

Finally, it seems to me that Org strives to be a document format which
is usable independently of any particular export format.=C2=A0 This counts = in
favor of having citation syntax as a first-class citizen in Org; at
present, Org documents can only contain citations through a combination
of extensions and external tools.

For these reasons, I would support a separate citation syntax, but one
that can behave like a link when useful.=C2=A0 For example, suppose we
borrowed the Pandoc [ ... @key1 ...; ... @key2 ...] syntax.=C2=A0 When poin= t
is on `@key1', C-c C-o could be bound to find the key in the reference<= br> database, or another useful action, depending on the reference database
format.

As I mentioned in the earlier thread, I think the Pandoc syntax is a
good place to start, and I think it would be valuable to have the two
syntaxes be compatible.=C2=A0 But even Pandoc's citation syntax might n= ot be
general enough to satisfy everyone's needs, so the first step for
introducing citation syntax to Org should be compiling a list of all the things such a syntax should represent.

The other problems, I think, must wait until a stable citation syntax
emerges -- export support in particular.=C2=A0 (Using an existing syntax fr= om
another project could help ease the transition here: if people can
export citations using an existing tool, they'll be able to switch to that syntax immediately, and use the external tool in the meantime while Org-internal support for it catches up.)

I hope this is a useful starting point for further discussion!

Best,
Richard



--089e0112c4ae59c130050e1c56b3--