emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* Should wip-cite branch be merged to master?
@ 2018-04-20 23:01 tumashu
  2018-04-21  7:26 ` Nicolas Goaziou
  0 siblings, 1 reply; 9+ messages in thread
From: tumashu @ 2018-04-20 23:01 UTC (permalink / raw)
  To: emacs-orgmode

[-- Attachment #1: Type: text/plain, Size: 139 bytes --]

There is a package which support wip-cite: https://github.com/andras-simonyi/citeproc-org, should wip-cite branch
be merged to master now?

[-- Attachment #2: Type: text/html, Size: 354 bytes --]

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Should wip-cite branch be merged to master?
  2018-04-20 23:01 Should wip-cite branch be merged to master? tumashu
@ 2018-04-21  7:26 ` Nicolas Goaziou
  2018-04-21  8:43   ` Christian Moe
                     ` (2 more replies)
  0 siblings, 3 replies; 9+ messages in thread
From: Nicolas Goaziou @ 2018-04-21  7:26 UTC (permalink / raw)
  To: tumashu; +Cc: emacs-orgmode, Simonyi András, John Kitchin

Hello,

tumashu <tumashu@163.com> writes:

> There is a package which support wip-cite: https://github.com/andras-simonyi/citeproc-org, should wip-cite branch
> be merged to master now?

Merging wip-cite branch with master, and integration of citeproc-org
into Org core, could be discussed with the author of the library, and,
of course, with anyone interested in using the @cite syntax. For
example, I need to know if that syntax, along with citeproc-org, covers
enough use-cases for citations, if it brings more value than using,
e.g., Org Ref, which already exists, how it could be improved, etc.

I also remember that Christian Moe suggested an alternate syntax for
citations. He might want to point out what is missing from @cite syntax
and if he still prefers his idea.

I have the feeling that it is a bit early for Org 9.2. Anyway, I'm
Cc'ing András and John for their opinion about it. I'd love to hear from
everyone involved in the last round of discussion about the subject,
too.

Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Should wip-cite branch be merged to master?
  2018-04-21  7:26 ` Nicolas Goaziou
@ 2018-04-21  8:43   ` Christian Moe
  2018-04-22 18:17   ` András Simonyi
  2018-04-27 21:07   ` András Simonyi
  2 siblings, 0 replies; 9+ messages in thread
From: Christian Moe @ 2018-04-21  8:43 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: tumashu, emacs-orgmode, Simonyi András, John Kitchin


I have no opinion on whether it's time for a merge or not, but please
don't wait up for me.

Nicolas Goaziou writes:

> I also remember that Christian Moe suggested an alternate syntax for
> citations. He might want to point out what is missing from @cite syntax
> and if he still prefers his idea.

I did, but my suggestions did not get any traction back when a native
citation syntax was first being discussed on the list. Regrettably, I
have not managed to follow up my proposal properly, then or now -- not
even to the point of updating my own sample code after a Zotero
development broke it last year -- and I probably won't in the
foreseeable near future. So I wouldn't want to hold back a
community-developed solution on account that I had a different idea.

My proposal was for a different approach (parsing a "natural-looking"
citation syntax like (Smith 1990: p.3)), which I thought could be both
more user-friendly and more aesthetically pleasing in plain text.  It
was not for improvements to the @cite syntax, so I don't actually know
what is missing from the latter, if anything. I was very excited about
the citeproc contributon, but I have not found the time to test it out.

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Should wip-cite branch be merged to master?
  2018-04-21  7:26 ` Nicolas Goaziou
  2018-04-21  8:43   ` Christian Moe
@ 2018-04-22 18:17   ` András Simonyi
  2018-04-23 19:42     ` John Kitchin
  2018-04-25 19:19     ` Richard Lawrence
  2018-04-27 21:07   ` András Simonyi
  2 siblings, 2 replies; 9+ messages in thread
From: András Simonyi @ 2018-04-22 18:17 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: tumashu, emacs-orgmode, John Kitchin

Dear All,

thanks for bringing this up. I definitely agree that it'd be too early to merge
the wip-cite branch. In fact, having added (experimental) support for it in
citeproc-org I've been planning to propose some changes/extensions to the syntax
but I wanted to wait until citeproc-org and citeproc-el become available as
MELPA packages which still isn't the case (citeproc-el is already there but
citeproc-org still needs some work before I can submit it). Anyhow, since the
topic has come up, here is how I see the situation (sorry for the length):

From the citeproc-el/CSL point of view, the current syntax is perfect with the
notable exception of the provided citation commands. Currently only `cite' and
`(cite)' are supported, where the latter seems to be intended to provide the
parenthetical version of a basic citation, e.g. in an author-date style `cite'
would produce something like `Smith 2018` while `(cite)' `(Smith 2018)'. Now I
think that for author-date styles `cite' should produce the parenthetical
version and that `(cite)' probably shouldn't be among the commands at all. The
main reason is that most citation processors (biblatex, CSL processors etc.)
support not only author-date citation styles but footnote-based ones as well,
and the concept of a `parenthetical citation' doesn't really make sense for the
latter. A more abstract characterization which is applicable to all styles is
that normally references are not part of the main text, they are set off either
by brackets or in a note. Since this is the most frequent, basic form, I think
this the one which should be produced by the `cite' syntax, that is, when used
in normal text `cite' should produce something like `(Smith 2018)' for
author-date styles and a note with the reference for note styles.

In addition to `cite', the following additional variants would be very
useful, and would probably cover the majority of use-cases:

- "bare cite": the same as cite, but doesn't separate the reference from
   the main text (no brackets/note);

- "suppress author": removes the author's name from the citation.

- "textual cite": includes the author's name in the main text but sets
  off the rest of the citation.

A proposal for the syntax of the additional forms: bare cite could be indicated
by a `-' suffix, suppress author by a `*' and textual cite by a `t' resulting in
the variants

| command       | result in author-date styles |
|---------------+------------------------------|
| cite          | (Smith 2017)                 |
| citet         | Smith (2017)                 |
| cite-         | Smith 2017                   |
| cite*         | (2017)                       |
| cite*-/cite-* | 2017                         |

(omitting some combinatorial possibilities that don't make practical sense). 

It would be a nice extra to also provide commands for adding an item to the list
of references without actually citing it (`nocite' command), and for adding
literal cites (that provide the full text of the citation, and whose sole
function is to let the processor know that a citation occurred at a certain
location) but these are obviously not so important as the ones in the above
table.

The citeproc-el wiki contains a bit more information about this proposal:

https://github.com/andras-simonyi/citeproc-el/wiki/Citation-types-and-commands

I'd be glad to hear your views regarding these issues.

best regards,

András

  >> There is a package which support wip-cite:
  >> https://github.com/andras-simonyi/citeproc-org, should wip-cite
  >> branch be merged to master now?

  > Merging wip-cite branch with master, and integration of citeproc-org
  > into Org core, could be discussed with the author of the library, and,
  > of course, with anyone interested in using the @cite syntax. For
  > example, I need to know if that syntax, along with citeproc-org, covers
  > enough use-cases for citations, if it brings more value than using,
  > e.g., Org Ref, which already exists, how it could be improved, etc.

  > I have the feeling that it is a bit early for Org 9.2. Anyway, I'm
  > Cc'ing András and John for their opinion about it. I'd love to hear from
  > everyone involved in the last round of discussion about the subject,
  > too.



  > Regards,

  > --
  > Nicolas Goaziou

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Should wip-cite branch be merged to master?
  2018-04-22 18:17   ` András Simonyi
@ 2018-04-23 19:42     ` John Kitchin
  2018-04-25 19:19     ` Richard Lawrence
  1 sibling, 0 replies; 9+ messages in thread
From: John Kitchin @ 2018-04-23 19:42 UTC (permalink / raw)
  To: András Simonyi; +Cc: tumashu, emacs-orgmode, Nicolas Goaziou

[-- Attachment #1: Type: text/plain, Size: 8924 bytes --]

I don't have any objections to merging now, or in the future. org-ref
addresses a fairly specific need, which is simple citations that ultimately
end up being processed by bib(la)tex/latex. It does a mediocre job
supporting footnote style citations, and limitations of the link format it
uses make it challenging to better support those. It has had limited
support for citeproc like capability for other formats. Hopefully what
András is doing will be the right size nucleus to keep growing to
completion. Some of this limitation is due to the complexity of a citeproc
engine that fully supports all types of citations, some of it to
limitations in the link syntax (which may be solved by a new syntax),
choices about what dependencies get added as a result of the citeproc
engine, and some of it is the backend where bibliographic data is stored
(e.g. how do you store markup of titles, author names in bibtex, zotero,
etc... It might depend on the final output, e.g. latex, html,...). More
progress on my end is certainly limited by it not being critical to the
kind of work I have been doing. org-ref has been relatively stable lately,
and is likely to stay that way for the foreseeable future.

I would be happy to stop using links in org-ref, in favor of a new syntax
(especially if it provided better support for footnote citations), provided
it doesn't reduce the functionality I use and rely on already in org-ref.
Here is my take on the important capabilities that make org-ref so useful
to us.

1. functional citations that provide a UI to elisp functions that do
something useful to the author about the citation at point. This is
currently provided in org-ref via links that use color to indicate they are
citations, as well as when they are broken, tooltips to provide a
bibliographic representation, clicking to activate a menu of actions, and
keybindings to facilitate citation manipulation and navigation.

I would expect the new citation syntax to (eventually) support all of these
capabilities, otherwise it would be a regression in functionality in my
opinion (except for the part about supporting footnote citations). I am
aware this probably makes the new cite syntax look a lot like a more
generalized link. I think it is worth considering the other cross-reference
needs of documents in this context too, notably references to figures,
equations, tables, etc. These aren't  generally supported in org-mode in a
way that meets the needs of technical documents, and so I have analogous
links defined in org-ref for them. They have similar functionalities as the
cite links.

2. A UI that uses some completion backend to insert citations. This is
currently done with helm/ivy-bibtex, or an ivy backend I created for
org-ref.

This is not part of the syntax exactly, except that the syntax has to be
programmatically constructable at least for the easy cases.

3. Support for export that provides styling of citations and the
bibliography. This is where a citeproc like solution is needed.

This is also not part of the syntax exactly, but without this as part of
the solution, we would still basically be stuck with exporting to latex, or
with ad hoc/partial support for other formats. Since these citations must
be exportable to different backends, it feels like it has to be part of the
solution.

4. org-element support. This is currently provided by the link, and it
enables a lot of the functionality to be possible, as well as other
external possibilities like linting, storing all citations in a database,
etc...

I presume this is part of the syntax/org integration, but it is important
that citations/bibliography elements be first-class citizens.

Those are my thoughts at the moment. I don't want to delay the integration
of this because of org-ref if it leads to better support for citeproc and
footnote citations. If the new syntax eventually enables org-ref++ it will
be progress.


John

-----------------------------------
Professor John Kitchin
Doherty Hall A207F
Department of Chemical Engineering
Carnegie Mellon University
Pittsburgh, PA 15213
412-268-7803
@johnkitchin
http://kitchingroup.cheme.cmu.edu


On Sun, Apr 22, 2018 at 11:17 AM, András Simonyi <simonyi@all.hu> wrote:

> Dear All,
>
> thanks for bringing this up. I definitely agree that it'd be too early to
> merge
> the wip-cite branch. In fact, having added (experimental) support for it in
> citeproc-org I've been planning to propose some changes/extensions to the
> syntax
> but I wanted to wait until citeproc-org and citeproc-el become available as
> MELPA packages which still isn't the case (citeproc-el is already there but
> citeproc-org still needs some work before I can submit it). Anyhow, since
> the
> topic has come up, here is how I see the situation (sorry for the length):
>
> From the citeproc-el/CSL point of view, the current syntax is perfect with
> the
> notable exception of the provided citation commands. Currently only `cite'
> and
> `(cite)' are supported, where the latter seems to be intended to provide
> the
> parenthetical version of a basic citation, e.g. in an author-date style
> `cite'
> would produce something like `Smith 2018` while `(cite)' `(Smith 2018)'.
> Now I
> think that for author-date styles `cite' should produce the parenthetical
> version and that `(cite)' probably shouldn't be among the commands at all.
> The
> main reason is that most citation processors (biblatex, CSL processors
> etc.)
> support not only author-date citation styles but footnote-based ones as
> well,
> and the concept of a `parenthetical citation' doesn't really make sense
> for the
> latter. A more abstract characterization which is applicable to all styles
> is
> that normally references are not part of the main text, they are set off
> either
> by brackets or in a note. Since this is the most frequent, basic form, I
> think
> this the one which should be produced by the `cite' syntax, that is, when
> used
> in normal text `cite' should produce something like `(Smith 2018)' for
> author-date styles and a note with the reference for note styles.
>
> In addition to `cite', the following additional variants would be very
> useful, and would probably cover the majority of use-cases:
>
> - "bare cite": the same as cite, but doesn't separate the reference from
>    the main text (no brackets/note);
>
> - "suppress author": removes the author's name from the citation.
>
> - "textual cite": includes the author's name in the main text but sets
>   off the rest of the citation.
>
> A proposal for the syntax of the additional forms: bare cite could be
> indicated
> by a `-' suffix, suppress author by a `*' and textual cite by a `t'
> resulting in
> the variants
>
> | command       | result in author-date styles |
> |---------------+------------------------------|
> | cite          | (Smith 2017)                 |
> | citet         | Smith (2017)                 |
> | cite-         | Smith 2017                   |
> | cite*         | (2017)                       |
> | cite*-/cite-* | 2017                         |
>
> (omitting some combinatorial possibilities that don't make practical
> sense).
>
> It would be a nice extra to also provide commands for adding an item to
> the list
> of references without actually citing it (`nocite' command), and for adding
> literal cites (that provide the full text of the citation, and whose sole
> function is to let the processor know that a citation occurred at a certain
> location) but these are obviously not so important as the ones in the above
> table.
>
> The citeproc-el wiki contains a bit more information about this proposal:
>
> https://github.com/andras-simonyi/citeproc-el/wiki/
> Citation-types-and-commands
>
> I'd be glad to hear your views regarding these issues.
>
> best regards,
>
> András
>
>   >> There is a package which support wip-cite:
>   >> https://github.com/andras-simonyi/citeproc-org, should wip-cite
>   >> branch be merged to master now?
>
>   > Merging wip-cite branch with master, and integration of citeproc-org
>   > into Org core, could be discussed with the author of the library, and,
>   > of course, with anyone interested in using the @cite syntax. For
>   > example, I need to know if that syntax, along with citeproc-org, covers
>   > enough use-cases for citations, if it brings more value than using,
>   > e.g., Org Ref, which already exists, how it could be improved, etc.
>
>   > I have the feeling that it is a bit early for Org 9.2. Anyway, I'm
>   > Cc'ing András and John for their opinion about it. I'd love to hear
> from
>   > everyone involved in the last round of discussion about the subject,
>   > too.
>
>
>
>   > Regards,
>
>   > --
>   > Nicolas Goaziou
>

[-- Attachment #2: Type: text/html, Size: 10433 bytes --]

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Should wip-cite branch be merged to master?
  2018-04-22 18:17   ` András Simonyi
  2018-04-23 19:42     ` John Kitchin
@ 2018-04-25 19:19     ` Richard Lawrence
  2018-04-26 23:34       ` Bastien
  1 sibling, 1 reply; 9+ messages in thread
From: Richard Lawrence @ 2018-04-25 19:19 UTC (permalink / raw)
  To: András Simonyi, Nicolas Goaziou; +Cc: tumashu, emacs-orgmode, John Kitchin

[-- Attachment #1: Type: text/plain, Size: 5364 bytes --]

Hi everyone,

I don't have too much to add to this, though I do want to thank 
everyone for their continued interest in citations, and the work 
that has been done!

Since the question of syntax has come up again, I guess I want to 
address one point that András made:
 
András Simonyi <simonyi@all.hu> writes:

> From the citeproc-el/CSL point of view, the current syntax is 
> perfect with the notable exception of the provided citation 
> commands. Currently only `cite' and `(cite)' are supported, 
> where the latter seems to be intended to provide the 
> parenthetical version of a basic citation, e.g. in an 
> author-date style `cite' would produce something like `Smith 
> 2018` while `(cite)' `(Smith 2018)'. Now I think that for 
> author-date styles `cite' should produce the parenthetical 
> version and that `(cite)' probably shouldn't be among the 
> commands at all. The main reason is that most citation 
> processors (biblatex, CSL processors etc.)  support not only 
> author-date citation styles but footnote-based ones as well, and 
> the concept of a `parenthetical citation' doesn't really make 
> sense for the latter. 

I think this actually gets at one of the fundamental problems with 
citations, namely, they resist attempts to separate 'content' from 
'style'.  It is hard to insert citations into a document without 
making any assumptions about how they will be rendered by the 
citation processor.  And so it is hard to come up with a syntax 
that is general enough to represent widely different citation 
styles, in a way that makes those assumptions explicit in the 
syntax of the unprocessed citation, so that the content of the 
citation can be separated from how it will be rendered.  Thus we 
see the huge proliferation of different citation commands in 
e.g. BibLaTeX, natbib, and similar packages.  András' proposal 
would reintroduce some of the complexity of BibLaTeX citation 
commands at the level of Org syntax.

Maybe having multiple citation commands is ultimately the best way 
to go, but I want to point out that one of the goals of the 
original discussion to come up with an Org syntax that is simpler 
and does a better job of separating content and style.  Anyway, 
that was one of my goals in synthesizing people's various 
suggestions and needs into a concrete syntax proposal.  I think we 
should try to avoid proliferation of citation commands.

If that is a reasonable goal, then I think there is really just 
one distinction that deserves to be represented at the level of 
citation commands: the distinction between 'in text' and 
'parenthetical' citations, that is, the distinction between 
'cite:' and '(cite):' in the current syntax in wip-cite.  That 
brings me to this point:

> A more abstract characterization which is applicable to all 
> styles is that normally references are not part of the main 
> text, they are set off either by brackets or in a note. Since 
> this is the most frequent, basic form, I think this the one 
> which should be produced by the `cite' syntax, that is, when 
> used in normal text `cite' should produce something like `(Smith 
> 2018)' for author-date styles and a note with the reference for 
> note styles.

I think András' abstract characterization is exactly right: the 
issue here is not really about whether the citation has brackets 
around it.  Instead, it is about whether the rendered citation is 
intended to be *read as part of the surrounding sentence* 
('in-text'), or whether it is *grammatically independent* of the 
main text ('parenthetical').  I disagree, however, that 
'parenthetical' citations are the normal or usual case; I think 
that depends completely on one's field, writing style, etc.  (In 
my dissertation, for example, in-text citations outnumber 
parenthetical citations roughly 3:2.) 

The 'in-text' vs. 'parenthetical'/'out-of-text' distinction is 
really the fundamental one that you can't abstract from as an 
author.  And it seems to me that apart from this decision, most of 
the other decisions about styling can handed off to the citation 
processor, via a choice of CSL file, at least for the out-of-text 
case: is it a note-based style, or a Harvard-like one? etc.

The in-text case is a little trickier because you need a way to 
represent the different kinds of data that might be intended to 
fit into the surrounding sentence (author name? year? both? just a 
number? etc.).  But there are many many possibilities here, and 
for that reason I think it is better to avoid making them 
primitive citation commands.  Instead we should just stick to one 
command for the in-text case, and have some extensible way to 
represent the data that should be rendered, e.g. maybe like

[cite: @Jones2018 :year]

or (as I think was proposed at one point):

[cite:author @Jones2018]

Again, maybe it's worth having some shortcuts here for the common 
cases, but I think in general we want to try to avoid 
proliferation of basic citation commands.  So for that reason I 
think we should just stick with the 'cite'/'(cite)' distinction as 
the two basic commands, perhaps with a more 
extensible/compositional syntax in each case for expressing the 
variations on these two basic types of citation.

-- 
Best,
Richard

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Should wip-cite branch be merged to master?
  2018-04-25 19:19     ` Richard Lawrence
@ 2018-04-26 23:34       ` Bastien
  0 siblings, 0 replies; 9+ messages in thread
From: Bastien @ 2018-04-26 23:34 UTC (permalink / raw)
  To: Richard Lawrence
  Cc: tumashu, emacs-orgmode, Nicolas Goaziou, András Simonyi,
	John Kitchin

Hi all,

Richard Lawrence <richard.lawrence@berkeley.edu> writes:

> I don't have too much to add to this, though I do want to thank
> everyone for their continued interest in citations, and the work that
> has been done!

+1!

With Org 9.2 knocking at the door, we can let users Org 9.2 a few
months before integrating such big features -- especially if they
come with new syntax.

In any case, great to see this moving forward!

Best,

-- 
 Bastien

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Should wip-cite branch be merged to master?
  2018-04-21  7:26 ` Nicolas Goaziou
  2018-04-21  8:43   ` Christian Moe
  2018-04-22 18:17   ` András Simonyi
@ 2018-04-27 21:07   ` András Simonyi
  2018-04-27 23:34     ` Nicolas Goaziou
  2 siblings, 1 reply; 9+ messages in thread
From: András Simonyi @ 2018-04-27 21:07 UTC (permalink / raw)
  To: Richard Lawrence
  Cc: Bastien, tumashu, emacs-orgmode, Nicolas Goaziou, John Kitchin

Dear All,

thanks for your responses. I find John's list of the most important
capabilities of org-ref very useful and agree that in the long run we
should aim at providing all of these functionality for the new syntax as
well. One point where this might prove to be difficult is precisely the
set of provided citation commands since org-ref, being bib(la)tex
focused, can support all BibTeX/biblatex commands via its citation
links. This leads to Richard's comments on this topic:

  > one of the fundamental problems with citations, namely, they resist
  > attempts to separate 'content' from 'style'. It is hard to insert
  > citations into a document without making any assumptions about how they
  > will be rendered by the citation processor. And so it is hard to come up
  > with a syntax that is general enough to represent widely different
  > citation styles, in a way that makes those assumptions explicit in the
  > syntax of the unprocessed citation, so that the content of the citation
  > can be separated from how it will be rendered. Thus we see the huge
  > proliferation of different citation commands in e.g. BibLaTeX, natbib,
  > and similar packages. András' proposal would reintroduce some of the
  > complexity of BibLaTeX citation commands at the level of Org syntax.

These are very good points and I agree that the used citation style can
influence the way of writing to a large extent, which makes it virtually
impossible to devise a citation syntax using which one could switch any
document to a totally different style (say from author-date to footnote)
without any rewrites. I suppose in this respect (i.e., 'separating
content and style') our aim can only be to provide those few
style-independent abstractions that are possible to minimize the amount
of changes needed, plus perhaps some style-dependent constructs.

  > I want to point out that one of the goals of the original discussion
  > to come up with an Org syntax that is simpler and does a better job
  > of separating content and style.

  > I think we should try to avoid proliferation of citation commands.

  > If that is a reasonable goal, then I think there is really just
  > one distinction that deserves to be represented at the level of
  > citation commands: the distinction between 'in text' and
  > 'parenthetical' citations, that is, the distinction between
  > 'cite:' and '(cite):' in the current syntax in wip-cite.  That
  > brings me to this point:

I agree both that we should avoid having too many citation commands and
that the most important distinction is that of between 'parenthetical'
and '(partly) in main text'. As for the concrete choice of these two
commands, it seems that I misunderstood the intended semantics of the
commands in the current wip-cite syntax because I thought that 'cite'
isn't supposed to produce an 'in main text' citation but a
'bare'/bracketless one, i.e., in the case of author-date styles, 'Smith
2018' instead of '(Smith 2018)'. If, on the contrary, 'cite' was
intended to stand for 'in text' citations then it is indeed a question
which part of the citation should be part of the main text -- e.g., how
should [cite: @Smith2018] be rendered by an author-date style? Since the
typical choice is the author's name, this would probably be a good
default.

  > we should just stick to one command for the in-text case, and have some
  > extensible way to represent the data that should be rendered, e.g. maybe
  > like

  > [cite: @Jones2018 :year]

  > or (as I think was proposed at one point):

  > [cite:author @Jones2018]

  > Again, maybe it's worth having some shortcuts here for the common cases,
  > but I think in general we want to try to avoid proliferation of basic
  > citation commands. So for that reason I think we should just stick with
  > the 'cite'/'(cite)' distinction as the two basic commands, perhaps with
  > a more extensible/compositional syntax in each case for expressing the
  > variations on these two basic types of citation.

Again, I very much agree with the general direction of these proposals,
but doesn't this mean that the citation element should have an attribute
to represent which parts of an 'in text' citation are meant to be in the
main text? (I think currently the only citation-specific attributes in
the wip-cite branch are 'prefix', 'suffix' and 'parenthetical'.)

Finally, to (at least roughly) conform with Wadler's law of language
design :-), just for the record, a few words about the choice of the
concrete commands for 'parenthetical' and 'in main text' citations.
Although Richard is right that the ratio of 'parenthetical' vs '(partly)
in main text' citations

  > depends completely on one's field, writing style, etc. (In my
  > dissertation, for example, in-text citations outnumber parenthetical
  > citations roughly 3:2.)

I still think a case can be made for making the 'parenthetical' one the
default/basic (and, consequently, interpreting the simplest/shortest
citation command as 'parenthetical').

First, I suspect that in documents using a note citation style 'partly
in main text' citations are quite rare. Second, although I couldn't find
any general frequency data on this, it seems that well established style
guides such as the Chicago Manual of Style consider 'parenthetical'
citations the basic/usual ones even in the case of author-date
citations. E.g., the CMS (16th ed.) writes that

'In the author-date system, a citation in the text usually appears in
parentheses and includes only the first elements in a reference list --
the author and the year of publication (15.7) [...] 15.21 *Text citatons --
basic form.* An author-date citation in running text or at the end of a
block quotation consists of the last (family) name of the author
followed by the year of publication'

Of course, it can be argued that this indicates only conceptual priority
and not frequency but I think this conceptual priority in itself is a
good argument for associating this type of citation with the basic
command, especially in view of the fact that 'partly in main text'
variants need the additional specification of what goes into the main
text.

Last but not least an 'argument from authority': the CSL plugins I know
of all default to inserting 'parenthetical' citations regardless of the
used style, and biblatex's basic high-level/style-independent command,
'autocite' also behaves that way.

I'd like to add that I don't consider the choice of the two citation
commands a crucial one, 'cite' as 'in main text' and '(cite)' as
'parenthetical' could also be a perfectly usable syntax/semantics,
especially if -- as Richard suggests -- we provide extension points to
cover more complex use cases.

best wishes,

András

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: Should wip-cite branch be merged to master?
  2018-04-27 21:07   ` András Simonyi
@ 2018-04-27 23:34     ` Nicolas Goaziou
  0 siblings, 0 replies; 9+ messages in thread
From: Nicolas Goaziou @ 2018-04-27 23:34 UTC (permalink / raw)
  To: András Simonyi; +Cc: Bastien, tumashu, emacs-orgmode, John Kitchin

Hello,

András Simonyi <andras.simonyi@gmail.com> writes:

>   > [cite:author @Jones2018]
>
>   > Again, maybe it's worth having some shortcuts here for the common cases,
>   > but I think in general we want to try to avoid proliferation of basic
>   > citation commands. So for that reason I think we should just stick with
>   > the 'cite'/'(cite)' distinction as the two basic commands, perhaps with
>   > a more extensible/compositional syntax in each case for expressing the
>   > variations on these two basic types of citation.
>
> Again, I very much agree with the general direction of these proposals,
> but doesn't this mean that the citation element should have an attribute
> to represent which parts of an 'in text' citation are meant to be in the
> main text? (I think currently the only citation-specific attributes in
> the wip-cite branch are 'prefix', 'suffix' and 'parenthetical'.)

IIRC, in the proposal above was, i.e., [cite:foo: @Jones2018], "foo"
would be a well-defined style. IOW, it could cover much more than
a simple "author".

> I'd like to add that I don't consider the choice of the two citation
> commands a crucial one, 'cite' as 'in main text' and '(cite)' as
> 'parenthetical' could also be a perfectly usable syntax/semantics,
> especially if -- as Richard suggests -- we provide extension points to
> cover more complex use cases.

The syntax above might be such an extension point. It requires, however,
to find a way to associate a style definition to a given key.

Thank you to the answers of everyone involved so far. It's nice to see
this moving forward.

Regards,

-- 
Nicolas Goaziou

^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2018-04-27 23:35 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-04-20 23:01 Should wip-cite branch be merged to master? tumashu
2018-04-21  7:26 ` Nicolas Goaziou
2018-04-21  8:43   ` Christian Moe
2018-04-22 18:17   ` András Simonyi
2018-04-23 19:42     ` John Kitchin
2018-04-25 19:19     ` Richard Lawrence
2018-04-26 23:34       ` Bastien
2018-04-27 21:07   ` András Simonyi
2018-04-27 23:34     ` Nicolas Goaziou

Code repositories for project(s) associated with this 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).