Re: Chiming in [Re: org-cite not mentioned in ORG-NEWS for 9.5]
Hi Bruce and Emmanuel, "Bruce D'Arcus" writes: > Finally, a question: what's the best way to do complex-ish > documentation like this collaboratively? Is there an alternative to > email + patches for the create, comment, revise cycle of refining > this? I'm sending you (and Timothy and Nicolas) a link off-list. > And related: if the goal is to finish this week (?), do we have time > to do comprehensive documentation? I'm a little skeptical. The goal is to have something by tomorrow afternoon, of course it does not need to be "finished" in any sense, it just needs to be better than what is already committed. *Thanks*! -- Bastien
Re: Chiming in [Re: org-cite not mentioned in ORG-NEWS for 9.5]
Great start! A few quick comments: 1. I'm not sure we should call them "citation links", since they aren't really links. 2. "four bibliograhic backends are available": a) note typo (which I think I saw elsewhere; there are a number of spelling errors throughout), b) "available" -> "included" (in org) More generally, it has also occurred to me that some of what Timothy wrote for this might be repurposed for here: https://blog.tecosaur.com/tmio/2021-07-31-citations.html Finally, a question: what's the best way to do complex-ish documentation like this collaboratively? Is there an alternative to email + patches for the create, comment, revise cycle of refining this? And related: if the goal is to finish this week (?), do we have time to do comprehensive documentation? I'm a little skeptical. On Mon, Sep 27, 2021 at 10:04 AM Emmanuel Charpentier wrote: > > As reported by Bastien, I started a documentation for the current state of > the citation engine(s). I intended to complete it, but got "a little" > sidetracked. > > Enclosed is a patch of where I was in August. > > Bastien made the following remarks, which I mostly intended to follow : > > === > > Je pense qu'à ce stade, le mieux est de soumettre ce document sur la > liste de diffusion. > > En attendant, j'ai quelques remarques, en vrac : > > - Je pense que le titre "Working with…" n'est pas assez explicite. Par > ailleurs, le chapitre précédent commence aussi par "Working with…". > Par conséquent, je propose d'intervertir la description et le titre : > > * Citations and references > :PROPERTIES: > :DESCRIPTION: Working with other people's work > :END: > > - Il faut penser à mettre deux espaces entre deux phrases. > > - =Org= -> Org > > - J'enlèverais la partie introductive expliquant pourquoi il est utile > de citer le travail d'autrui. Ceci dit, il vaut mieux attendre l'avis > d'autres personnes concernées par la fonctionnalité. > > [ Emmanuel Charpentier : I think that this justification may be helpful to a > lot of non-scholar org users, who could benefit from org-cite. Advice > sollicited... ] > > - Je pense qu'il faut éviter de parler ce "citation link", car cela peut > engendrer de la confusion avec "link" qui est une structure proche, > mais différent. Peut-être faut-il parler de "citation object". > > - Dans Texinfo, les phrases doivent être séparées par deux espaces. > > === > > What still lacks : > > an explanation of the four possible functions of an engine ; > current functionalities of the currently available engines ; > an org-guide sized summary. > > > Anyone is welcome to propose modifications. Someone should take the task of > collating the propositions and consolidate a final text ; I am reluctant to > take this task, given my RL tasks... > > Comments, remarks, criticisms, lazzi, etc... all welcome. > > -- > Emmanuel Charpentier
Chiming in [Re: org-cite not mentioned in ORG-NEWS for 9.5]
As reported by Bastien, I started a documentation for the current state of the citation engine(s). I intended to complete it, but got "a little" sidetracked. Enclosed is a patch of where I was in August. Bastien made the following remarks, which I mostly intended to follow : === Je pense qu'à ce stade, le mieux est de soumettre ce document sur la liste de diffusion. En attendant, j'ai quelques remarques, en vrac : - Je pense que le titre "Working with…" n'est pas assez explicite. Par ailleurs, le chapitre précédent commence aussi par "Working with…". Par conséquent, je propose d'intervertir la description et le titre : * Citations and references :PROPERTIES: :DESCRIPTION: Working with other people's work :END: - Il faut penser à mettre deux espaces entre deux phrases. - =Org= -> Org - J'enlèverais la partie introductive expliquant pourquoi il est utile de citer le travail d'autrui. Ceci dit, il vaut mieux attendre l'avis d'autres personnes concernées par la fonctionnalité. [ Emmanuel Charpentier : I think that this justification may be helpful to a lot of non-scholar org users, who could benefit from org-cite. Advice sollicited... ] - Je pense qu'il faut éviter de parler ce "citation link", car cela peut engendrer de la confusion avec "link" qui est une structure proche, mais différent. Peut-être faut-il parler de "citation object". - Dans Texinfo, les phrases doivent être séparées par deux espaces. === What still lacks : * an explanation of the four possible functions of an engine ; * current functionalities of the currently available engines ; * an org-guide sized summary. Anyone is welcome to propose modifications. Someone should take the task of collating the propositions and consolidate a final text ; I am reluctant to take this task, given my RL tasks... Comments, remarks, criticisms, lazzi, etc... all welcome. -- Emmanuel Charpentier From f4d5b9f7d2a57a588fd72c4074a6b1ed018cf29f Mon Sep 17 00:00:00 2001 From: Emmanuel Charpentier Date: Mon, 27 Sep 2021 15:46:51 +0200 Subject: [PATCH] Embryo of a doc for the citation engine(s). --- doc/org-manual.org | 239 + 1 file changed, 239 insertions(+) diff --git a/doc/org-manual.org b/doc/org-manual.org index d34d33561..265d5f33a 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -18622,6 +18622,245 @@ emacs -Q --batch --eval " " "$@" #+end_example +* Working with other people's work +:PROPERTIES: +:DESCRIPTION: Manage citations and references +:END: +#+cindex: other people's work, working with + +Citations and references are a crucial part of almost any writing +(scholarly or otherwise): citing previous works relieves you from the +burden of discussing or defending what you cite. This relief comes at +a price: referring your reader to your source (thus transferring the +burden to check your statements in the original source to +him/her). This is usually done by separing a brief indication of the +work you use (a /citation/), part of the text, from the detailed +description of this work and of the means to retrieve it (the +/reference/), given out of the text (in footnotes and/or at the end of +the text). + +In everyday writing, citations and references may be vague, often +reduced to a handwave. In many domains, however, and most notably in +academic writing, precision in citing and referring is crucial. Citing +and referring conventions have therefore evolved since the beginnings +of writing, and are highly formalized in many domains. + +These conventions, answering different needs in different domains, are +different from domain to domain. For various reasons, they also vary +according to the intended use of the writing (academic work, +scientific paper, report, journal article, book or book chapter, +etc...). Following these sets of conventions (aka /styles/) can be +highly labor intensive. + +=Org= bibliographic tools use sets of reference informations and +formatting directives to easily insert succinct indications of a work +and forat theminto style-compliant citation and reference and insert +them in the correct place in the text. + +** Overview +:PROPERTIES: +:DESCRIPTION: Basic concepts of citation handling +:END: +#+cindex: bibliography +#+cindex: citation +#+cindex: reference +#+cindex: style + +A few definitions are in order : + + * Bibliography :: Conceptually, it is the set of /all/ previous +works supporting one's work, /whether you cite them explicitly or +not/. It might also denote a list of all such work, possibly with +notes related to each of them. + +This word also denotes a bibliography list referring /all/ the +works (cited or not) used in the development of one's work ; this +is a requirement of some (mostly scholarly) styles. + + * Reference :: The information the information pertaining to a given +work,
Chiming in [Re: org-cite not mentioned in ORG-NEWS for 9.5]
As reported by Bastien, I started a documentation for the current state of the citation engine(s). I intended to complete it, but got "a little" sidetracked. Enclosed is a patch of where I was in August. Bastien made the following remarks, which I mostly intended to follow : === Je pense qu'à ce stade, le mieux est de soumettre ce document sur la liste de diffusion. En attendant, j'ai quelques remarques, en vrac : - Je pense que le titre "Working with…" n'est pas assez explicite. Par ailleurs, le chapitre précédent commence aussi par "Working with…". Par conséquent, je propose d'intervertir la description et le titre : * Citations and references :PROPERTIES: :DESCRIPTION: Working with other people's work :END: - Il faut penser à mettre deux espaces entre deux phrases. - =Org= -> Org - J'enlèverais la partie introductive expliquant pourquoi il est utile de citer le travail d'autrui. Ceci dit, il vaut mieux attendre l'avis d'autres personnes concernées par la fonctionnalité. [ Emmanuel Charpentier : I think that this justification may be helpful to a lot of non-scholar org users, who could benefit from org-cite. Advice sollicited... ] - Je pense qu'il faut éviter de parler ce "citation link", car cela peut engendrer de la confusion avec "link" qui est une structure proche, mais différent. Peut-être faut-il parler de "citation object". - Dans Texinfo, les phrases doivent être séparées par deux espaces. === What still lacks : * an explanation of the four possible functions of an engine ; * current functionalities of the currently available engines ; * an org-guide sized summary. Anyone is welcome to propose modifications. Someone should take the task of collating the propositions and consolidate a final text ; I am reluctant to take this task, given my RL tasks... Comments, remarks, criticisms, lazzi, etc... all welcome. -- Emmanuel Charpentier From f4d5b9f7d2a57a588fd72c4074a6b1ed018cf29f Mon Sep 17 00:00:00 2001 From: Emmanuel Charpentier Date: Mon, 27 Sep 2021 15:46:51 +0200 Subject: [PATCH] Embryo of a doc for the citation engine(s). --- doc/org-manual.org | 239 + 1 file changed, 239 insertions(+) diff --git a/doc/org-manual.org b/doc/org-manual.org index d34d33561..265d5f33a 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -18622,6 +18622,245 @@ emacs -Q --batch --eval " " "$@" #+end_example +* Working with other people's work +:PROPERTIES: +:DESCRIPTION: Manage citations and references +:END: +#+cindex: other people's work, working with + +Citations and references are a crucial part of almost any writing +(scholarly or otherwise): citing previous works relieves you from the +burden of discussing or defending what you cite. This relief comes at +a price: referring your reader to your source (thus transferring the +burden to check your statements in the original source to +him/her). This is usually done by separing a brief indication of the +work you use (a /citation/), part of the text, from the detailed +description of this work and of the means to retrieve it (the +/reference/), given out of the text (in footnotes and/or at the end of +the text). + +In everyday writing, citations and references may be vague, often +reduced to a handwave. In many domains, however, and most notably in +academic writing, precision in citing and referring is crucial. Citing +and referring conventions have therefore evolved since the beginnings +of writing, and are highly formalized in many domains. + +These conventions, answering different needs in different domains, are +different from domain to domain. For various reasons, they also vary +according to the intended use of the writing (academic work, +scientific paper, report, journal article, book or book chapter, +etc...). Following these sets of conventions (aka /styles/) can be +highly labor intensive. + +=Org= bibliographic tools use sets of reference informations and +formatting directives to easily insert succinct indications of a work +and forat theminto style-compliant citation and reference and insert +them in the correct place in the text. + +** Overview +:PROPERTIES: +:DESCRIPTION: Basic concepts of citation handling +:END: +#+cindex: bibliography +#+cindex: citation +#+cindex: reference +#+cindex: style + +A few definitions are in order : + + * Bibliography :: Conceptually, it is the set of /all/ previous +works supporting one's work, /whether you cite them explicitly or +not/. It might also denote a list of all such work, possibly with +notes related to each of them. + +This word also denotes a bibliography list referring /all/ the +works (cited or not) used in the development of one's work ; this +is a requirement of some (mostly scholarly) styles. + + * Reference :: The information the information pertaining to a given +
