From: John Kitchin <jkitchin@andrew.cmu.edu>
To: Richard Lawrence <richard.lawrence@berkeley.edu>
Cc: "emacs-orgmode@gnu.org" <emacs-orgmode@gnu.org>
Subject: Re: Citations, continued
Date: Sun, 1 Feb 2015 17:06:23 -0500 [thread overview]
Message-ID: <CAJ51ETqNEfabHqYZusXutjnNDgsxSqkGdBV1Asd8ZhUH-+-E0A@mail.gmail.com> (raw)
In-Reply-To: <87vbjmn6wy.fsf@berkeley.edu>
[-- Attachment #1: Type: text/plain, Size: 9293 bytes --]
>
>
>
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).
>
I think links are remarkable flexible, and solve most of the pre/post text
issue. You can use literal links if you don't want to see them collapsed.
Links already have a type, so they are easily differentiable from other
links and elements. The only limitation I can see is your example below
where I couldn't put two pre/post text citations in one link. I would write
that as:
See cite:Doe1999 for an overview; a more extensive discussion is in
cite:Foobar2000
if the pre/post text is really critical somehow, you can do this.
[[cite:Doe1999][See::for an overview]]; a more extensive discussion is in
cite:Foobar2000
I guess this would also be ok in orgref:
[[cite:Doe1999][See::for an overview]][[cite:Foobar2000][; a more extensive
discussion is in]]
Depending on your backend and citation style, it might be necessary to use
Ref. citenum:Foobar2000 for it to look right on export.
Either way, none of these are more readable than the first one I think, and
they would probably all render the same in any backend.
> 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.
>
Making anything unreadable should be avoided at all cost!
> 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''?
>
An org link can point to many targets. An org-mode link executes code,
which can give you many options to consider. In your example, I would
consider that two citations. Even a single cite link in org-ref considers
each comma-separated key a separate clickable entity; the code figures out
which key you clicked on, and gives you several options of what to do with
it, like open the entry, the pdf, etc... which it figures out how to do
based on the key.
>
> 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.
>
How does the pandoc syntax handle different link types. e.g. the 40ish
different types supported by biblatex? Links manage this easily, and with
the export framework, you can convert them to all kinds of other formats.
It looks to me like the pandoc syntax is too simple for that.
'("cite" "nocite" ;; the default latex cite commands
;; natbib cite commands,
http://ctan.unixbrain.com/macros/latex/contrib/natbib/natnotes.pdf
"citet" "citet*" "citep" "citep*"
"citealt" "citealt*" "citealp" "citealp*"
"citenum" "citetext"
"citeauthor" "citeauthor*"
"citeyear" "citeyear*"
"Citet" "Citep" "Citealt" "Citealp" "Citeauthor"
;; biblatex commands
;; http://ctan.mirrorcatalogs.com/macros/latex/contrib/biblatex/doc/biblatex.pdf
"Cite"
"parencite" "Parencite"
"footcite" "footcitetext"
"textcite" "Textcite"
"smartcite" "Smartcite"
"cite*" "parencite*" "supercite"
"autocite" "Autocite" "autocite*" "Autocite*"
"Citeauthor*"
"citetitle" "citetitle*"
"citedate" "citedate*"
"citeurl"
"fullcite" "footfullcite"
;; "volcite" "Volcite" cannot support the syntax
"notecite" "Notecite"
"pnotecite" "Pnotecite"
"fnotecite"
;; multicites. Very limited support for these.
"cites" "Cites" "parencites" "Parencites"
"footcites" "footcitetexts"
"smartcites" "Smartcites" "textcites" "Textcites"
"supercites" "autocites" "Autocites"
;; for the bibentry package
"bibentry"
)
I think you need a citation type for the backend, because you often need
more than one type in a document, e.g. the regular citations, sometimes a
citation number, author or year. For a pandoc like link you could consider
(adapted from the pandoc examples):
cite@key1,key2,key3
[optional pre text citenum@key optional post text]
or a group like this
[see citetext@item1 p. 34-35; also citet*@item3 chap. 3].
where optional text might include additional citations
cite@key[citeauthor@key2, p. 30; see also Ref. citenum@key3)]
I can't say I look forward to figuring out how to convert that to latex (or
what the latex equivalent even is!)). There would have to be some mechanism
to define new citation types, analogous to adding new link types. I suppose
if org-element-map parsed these into data structures it might not be too
bad.
These look alot like replacing : with @ in a link to me, but maybe the
added flexibility is worth it. The simplest cases would act like links.
Looking back at this, I am not seeing a critical advantage over the links,
other than eliminating the :: separator in the description. Except for the
last example. I would never dream of writing a citation like that though!
We never use pre/post text in citations in our work, and they don't even
make sense with all citation formats, e.g. superscripted numbers. Maybe
someone could provide some real life citation examples that links can't
handle?
I suspect a lot of pre/post text issues can be solved manually as:
(see cite:key1, pg33-4; also cite:key2, chapter 3)
and you will get what you want in the output.
I have no idea how hard it would be to implement something like that
syntax.
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 backend responsible for rendering the citation needs:
1. how to render the citation in the text (some hint about a type, pre and
post text)
2. how to render the citation in the bibliography (it will get all the
information from somewhere, based on the key of the citation, and prepare
the citation).
In Latex, you specify a style somewhere that says how to format a cite,
cite*, citenum, etc... and what the bibliography entries look like (unless
you use thebibliography, in which case you do that work yourself).
in org-ref, it gets the type from a link, the key from the link, and
pre/post text from the link, and converts that to the latex form needed by
the latex bibliography backend. Something similar happens in the html
export, except I build the bibliography from the bibtex file, and then go
back and put html links in place for citations. nothing fancy.
In word, I suppose there are little fields in the main document, and you
run some function that fires up zotero/endnote/mendeley, etc... that does
the formatting.
>
> 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!
>
So, after working through all that, I still think links are good enough for
a large portion of citations. org should not try to solve all of these
problems. That said, I would be interested again to see real life citation
needs that links are too awkward to handle.
>
> Best,
> Richard
>
>
>
[-- Attachment #2: Type: text/html, Size: 19589 bytes --]
next prev parent reply other threads:[~2015-02-01 22:06 UTC|newest]
Thread overview: 104+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-01-31 18:26 Citations, continued Richard Lawrence
2015-01-31 18:42 ` Nicolas Goaziou
2015-02-01 22:07 ` Richard Lawrence
2015-02-02 13:52 ` Rasmus
2015-02-02 17:25 ` Richard Lawrence
2015-02-02 18:09 ` Rasmus
2015-02-02 15:45 ` Erik Hetzner
2015-02-01 22:06 ` John Kitchin [this message]
2015-02-02 1:41 ` Richard Lawrence
2015-02-02 4:43 ` Thomas S. Dye
2015-02-02 13:56 ` John Kitchin
2015-02-02 18:11 ` Thomas S. Dye
2015-02-02 19:38 ` John Kitchin
2015-02-02 19:51 ` John Kitchin
2015-02-02 22:47 ` Rasmus
2015-02-03 0:54 ` Thomas S. Dye
2015-02-03 1:36 ` John Kitchin
2015-02-02 14:17 ` Rasmus
2015-02-02 16:58 ` Richard Lawrence
2015-02-02 14:07 ` Rasmus
2015-02-02 13:51 ` Rasmus
2015-02-02 15:09 ` Matt Price
2015-02-02 18:02 ` Richard Lawrence
2015-02-02 19:55 ` Rasmus
2015-02-03 1:56 ` Richard Lawrence
2015-02-03 2:08 ` Vikas Rawal
2015-02-03 10:55 ` Rasmus
2015-02-04 10:35 ` Julian M. Burgos
2015-02-04 16:34 ` John Kitchin
2015-02-03 10:35 ` Rasmus
2015-02-03 12:00 ` Eric S Fraga
2015-02-03 16:27 ` Richard Lawrence
2015-02-03 17:25 ` Eric S Fraga
2015-02-03 3:58 ` Erik Hetzner
2015-02-03 4:41 ` Richard Lawrence
2015-02-03 7:30 ` Erik Hetzner
2015-02-03 16:11 ` Richard Lawrence
2015-02-04 6:30 ` Erik Hetzner
2015-02-04 12:06 ` Nicolas Goaziou
2015-02-04 16:45 ` Richard Lawrence
2015-02-06 10:27 ` Nicolas Goaziou
2015-02-06 22:41 ` Richard Lawrence
2015-02-07 22:43 ` Nicolas Goaziou
2015-02-08 2:46 ` Richard Lawrence
2015-02-08 9:46 ` John Kitchin
2015-02-08 17:09 ` Richard Lawrence
2015-02-08 22:23 ` Thomas S. Dye
2015-02-09 8:46 ` e.fraga
2015-02-09 10:50 ` Rasmus
2015-02-09 11:20 ` Nicolas Goaziou
2015-02-09 11:37 ` Rasmus
2015-02-10 9:06 ` Nicolas Goaziou
2015-02-09 15:09 ` Thomas S. Dye
2015-02-10 8:55 ` Nicolas Goaziou
2015-02-10 9:22 ` Rasmus
2015-02-10 9:41 ` Nicolas Goaziou
2015-02-10 10:01 ` Rasmus
2015-02-10 15:32 ` Thomas S. Dye
2015-02-10 1:50 ` John Kitchin
2015-02-09 17:46 ` Richard Lawrence
2015-02-09 20:13 ` Rasmus
2015-02-10 1:32 ` John Kitchin
2015-02-10 4:04 ` Richard Lawrence
2015-02-10 5:23 ` John Kitchin
2015-02-10 6:20 ` Thomas S. Dye
2015-02-08 9:58 ` Nicolas Goaziou
2015-02-08 17:18 ` Richard Lawrence
2015-02-08 18:18 ` Nicolas Goaziou
2015-02-08 9:28 ` Rasmus
2015-02-08 10:18 ` Nicolas Goaziou
2015-02-08 10:50 ` Rasmus
2015-02-08 12:36 ` Nicolas Goaziou
2015-02-08 13:40 ` Rasmus
2015-02-08 16:11 ` Nicolas Goaziou
2015-02-09 10:02 ` Rasmus
2015-02-08 17:02 ` Nicolas Goaziou
2015-02-08 17:29 ` Rasmus
2015-02-10 1:54 ` John Kitchin
2015-02-10 8:49 ` Nicolas Goaziou
2015-02-10 9:20 ` Rasmus
2015-02-10 10:05 ` Nicolas Goaziou
2015-02-10 10:36 ` Rasmus
2015-02-10 10:53 ` Andreas Leha
2015-02-10 15:03 ` John Kitchin
2015-02-10 15:54 ` Rasmus
2015-02-10 16:14 ` John Kitchin
2015-02-10 16:22 ` Richard Lawrence
2015-02-10 16:44 ` Stefan Nobis
2015-02-11 2:07 ` Richard Lawrence
2015-02-11 10:19 ` Stefan Nobis
2015-02-11 16:51 ` Richard Lawrence
2015-02-13 2:31 ` Matt Price
2015-02-11 10:47 ` Aaron Ecay
2015-02-11 11:32 ` Rasmus
2015-02-10 16:04 ` Richard Lawrence
2015-02-11 2:10 ` Thomas S. Dye
2015-02-11 2:48 ` Richard Lawrence
2015-02-11 3:53 ` Thomas S. Dye
2015-02-06 23:37 ` Rasmus
2015-02-06 23:16 ` Rasmus
2015-02-04 17:44 ` Erik Hetzner
2015-02-04 15:59 ` Richard Lawrence
2015-02-04 17:58 ` Erik Hetzner
2015-02-04 19:24 ` Richard Lawrence
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CAJ51ETqNEfabHqYZusXutjnNDgsxSqkGdBV1Asd8ZhUH-+-E0A@mail.gmail.com \
--to=jkitchin@andrew.cmu.edu \
--cc=emacs-orgmode@gnu.org \
--cc=richard.lawrence@berkeley.edu \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).