From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0 ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id WHheDWn7ZWEV2AAAgWs5BA (envelope-from ) for ; Tue, 12 Oct 2021 23:17:29 +0200 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0 with LMTPS id oPMhCWn7ZWHiKQAA1q6Kng (envelope-from ) for ; Tue, 12 Oct 2021 21:17:29 +0000 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 8C0491294E for ; Tue, 12 Oct 2021 23:17:27 +0200 (CEST) Received: from localhost ([::1]:59188 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1maP9J-0007nr-Au for larch@yhetil.org; Tue, 12 Oct 2021 17:17:25 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:48578) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1maP8V-0007nS-Gw for emacs-orgmode@gnu.org; Tue, 12 Oct 2021 17:16:35 -0400 Received: from mail-wr1-x429.google.com ([2a00:1450:4864:20::429]:44765) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1maP8S-0005dy-Up for emacs-orgmode@gnu.org; Tue, 12 Oct 2021 17:16:35 -0400 Received: by mail-wr1-x429.google.com with SMTP id e3so1272493wrc.11 for ; Tue, 12 Oct 2021 14:16:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=andrew.cmu.edu; s=google-2021; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=qFK6zGZUxlF8Z5NdD6Q3hj7d+AtixMfSxvDGbjhonr0=; b=VwGGYQLR5BEBDms2hbytLRD/+DYMagEbnmgoBL8cyaxrf5voo56K8V4iAvh7muxU1m R7oxsTgMFgterkn6ssucNyi3012YTaNn4qG5+FEiXI1BneFfL4ZRAvBjwMMCus4xP48b m7OQktF7ApHJd5UP9WHc1QvUf9FIKEJjKIyPRjcUB1KVTE7gDuWXGDMLM/x9TYuoZw+q 49GjxlOVWPzQ7+fX2T/JTtymg7ljsVgpUHIuYzB0KROCIe/Gniux35+eF+qEDanbcNS4 j7y0mPSTNdIz+DOeW4pTX1N9rJag2mD+VXC8E2yLkf18b7juqKKnfWitS1Ix8ykUN1Wv ct1A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=qFK6zGZUxlF8Z5NdD6Q3hj7d+AtixMfSxvDGbjhonr0=; b=npkO6CNRCwOMURgDA0cTmYb7inTVk8yeivTtIWJ6fDVP/J5BKC7agt650dUP1oTupQ LDBgbR0z5LqBULoI5/OAqiQh4GEcRxe+XvehNzvhY0k/4sT1QGRxkuC+AwLPx1QMa1xm toD19hpJ2BCiM+kkyYBIHFa7TNqXWTvga1pPG/XOHS4pOk+08jaVZrBk338HylFQTAQw 0FrXvioeZEVtqp5ZePHp3vJhjxU17+//QKO435pNzCNcox18L5pfUqWDxms/oCZ4ZxB5 ohim/Cwoj43bQySnFa3M8sQim3GGrT9KISz4pjeLfAb73ASsNJs+Y7A6HCDrku6AIEk6 zEEQ== X-Gm-Message-State: AOAM532BK66WbQSwsNtNlOSfoSzSlxGKj5Deu5RyPB3cDsM8aLzIVP8H J4Y3SpdvlIgAHsoo4jSj3IFXlzn7il89sJ1sCak= X-Google-Smtp-Source: ABdhPJxVXfEFn4SWTQcJ8oPwwr23I803izOUDzR4bzzQPENz824Ep4iDuWph/zJOzFbjr2muDU7tCZ2iB4zzKkh/sY8= X-Received: by 2002:adf:ca09:: with SMTP id o9mr33620199wrh.303.1634073390964; Tue, 12 Oct 2021 14:16:30 -0700 (PDT) MIME-Version: 1.0 References: <87sfzdv083.fsf@ucl.ac.uk> In-Reply-To: From: John Kitchin Date: Tue, 12 Oct 2021 17:16:19 -0400 Message-ID: Subject: Re: Expanding how the new cite syntax is used to include cross-references - thoughts? To: "Bruce D'Arcus" Content-Type: multipart/alternative; boundary="0000000000000164ab05ce2e5c96" Received-SPF: pass client-ip=2a00:1450:4864:20::429; envelope-from=johnrkitchin@gmail.com; helo=mail-wr1-x429.google.com X-Spam_score_int: -14 X-Spam_score: -1.5 X-Spam_bar: - X-Spam_report: (-1.5 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, FREEMAIL_FORGED_FROMDOMAIN=0.25, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.249, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Tom Gillespie , Org Mode List Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: "Emacs-orgmode" X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1634073448; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=qFK6zGZUxlF8Z5NdD6Q3hj7d+AtixMfSxvDGbjhonr0=; b=cJrwnLJlXMVNv6Com7JPzfMBAqa+AXH2LR00ulxipJRR5Qzsnod71pLlRQPW+7mgXeywn4 vY3d9Jq1H17IbsL3prMadxerRIDiZIMPMLwIkgkn2PT4NjSRw2zO4dN5Z+5iZD5k1tvdGI Pvhs4yuGFWLT/EexeLGNh1zxi6f4uU6URmqBnR/ILtNtrqOFJSalKxAA0hOSLFdCOYcMJc deEvSdZj4hnwkAVl0Zg79w5qRYTvbfxesvAG/M6NBF7nPS2GFkS0sZlrIrDMOOIgNwfDNF V6atIhMFxfaAKvNPGElxSqQ/wlDTpqVCvCZlSErd4FfwVrWR0eQa+vzBXSlxkA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1634073448; a=rsa-sha256; cv=none; b=jrqPvNLzb85nVwSF0MLIFUkcnqIui6ODAem4EHB3DoNyV58aIG8fuSuwKwZdNFJ7W574/z HiG+UzQWCUsY4nQVoQ8+ViO1djhhk2drbc3dfEItzKiMi63IYttGCB/VLGoWwXFHcKjaa4 bDNRiZumZkYEEsMvSiU+Bk5meAb/K4FNtIIfCRkX8yH5FRg4qRzmNw39VQ4xk6Qu/9kla0 LzArI6RboQk3mWMYauM0VTMal0GBGj97RS2WHaI0fWh03dXcF7SFccr+R4fhtVOxkcf78G duylKVc5moR9SWSebrrFTU+QUa3ZQLwScOKSfwOdF1tdtB8vlavJgRQhARFyzA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=andrew.cmu.edu header.s=google-2021 header.b=VwGGYQLR; spf=pass (aspmx1.migadu.com: domain of emacs-orgmode-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=emacs-orgmode-bounces@gnu.org X-Migadu-Spam-Score: 1.19 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=andrew.cmu.edu header.s=google-2021 header.b=VwGGYQLR; dmarc=fail reason="SPF not aligned (relaxed)" header.from=andrew.cmu.edu (policy=none); spf=pass (aspmx1.migadu.com: domain of emacs-orgmode-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=emacs-orgmode-bounces@gnu.org X-Migadu-Queue-Id: 8C0491294E X-Spam-Score: 1.19 X-Migadu-Scanner: scn0.migadu.com X-TUID: KqxNydvfQG2x --0000000000000164ab05ce2e5c96 Content-Type: text/plain; charset="UTF-8" I think the existing link capability of org-mode is completely adequate for cross-references. LaTeX exports are almost completely covered in org-ref. I made a refproc ( https://github.com/jkitchin/org-ref/blob/org-ref-3/org-ref-refproc.el) that provides similar export behavior for other backends in a pre-processing hook. It supports the concepts in autoref and cleveref by replacing the org-links with an appropriate org syntax that then exports natively. For example, if cref:name references a table, it would get replaced by "Table [[name]]" in the buffer and then exported to the desired backend. All of these are references to two tables named b1 and b2 - ref :: ref:b1 - autoref :: autoref:b1 - nameref :: nameref:b1 - pageref :: pageref:b1 - cref :: cref:b1 - cref, two :: cref:b1,b2 - Cref :: Cref:b1 - Cref, two :: Cref:b1,b2 and they are converted to this plain org syntax (which basically mirrors what would happen in a LaTeX export). - ref :: [[b1]] - autoref :: Tab. [[b1]] - nameref :: [[b1][this is a table b1.]] - pageref :: [[b1]] - cref :: Tab. [[b1]] - cref, two :: Tabs. [[b1]] and [[b2]] - Cref :: Tab. [[b1]] - Cref, two :: Tabs. [[b1]] and [[b2]] There are some options to control if the clever parts are abbreviated and/or capitalized. This should be part of org-ref on Melpa next week. John ----------------------------------- Professor John Kitchin (he/him/his) Doherty Hall A207F Department of Chemical Engineering Carnegie Mellon University Pittsburgh, PA 15213 412-268-7803 @johnkitchin http://kitchingroup.cheme.cmu.edu On Sun, Oct 10, 2021 at 9:30 AM Bruce D'Arcus wrote: > Can we go back to this question of whether internal links are adequate > for cross-references, and if not, what's missing? > > On Fri, Aug 13, 2021 at 11:22 AM Eric S Fraga wrote: > > > > Hello John & co., > > > > I need to chime in when it comes to the UI: > > > > On Thursday, 12 Aug 2021 at 13:19, John Kitchin wrote: > > > I would say the UI that I like, have used for many years, and is the > > > default of org-ref is: > > > > > > 1. You type C-c ] to insert a citation > > > 2. You type C-u C-c ] to insert a cross-reference > > > 3. you type C-u C-u C-c ] to insert a new label. > > > > UI is a very personal thing. So long as there are 3 different functions > > that implement these actions, I would be happy... > > [snip] > > > In terms of the bigger picture, citations and cross-references, to me, > > are different things (one is external and the other usually internal, > > respectively) and I see no benefit in conflating them. I am also still > > not convinced that org links are not sufficient ... > > In reviewing and playing with this functionality a bit, it's clear to > me that internal links are intended to be cross-references, even if > they fall short for certain classes of users. > > Let's take a simple example of a figure, adapted from the manual: > > #+begin_example > #+CAPTION: This is the caption. > #+NAME: fig:SED-HR4049 > [[./img/a.jpg]] > > Here's a cross-reference to Figure [[fig:SED-HR4049]]. > #+end_example > > This internal link seems to produce consistent and correct output > across latex, html, and odt. > > The "fig" prefix is meaningful to ref in latex to enable it to type > that cross-reference. I'm unsure how typing in the odt context works, > but it does. > > The only downside is one has to manually, per the example, insert the > prefix (here "Figure ") in text (though this is a small price to pay > in my view). > > If one wants to use cleveref or autoref instead, as is now possible > with a recent commit, those packages handle that automatically. But of > course, this only works in latex, so you lose the consistency across > the backends. > > Also, you then need to be able to specify different variants locally > (for example, cref vs Cref), which is not possible currently. > > So I'm unclear: is that added functionality and complexity really > needed? Is there something else I'm missing? > > A separate, possibly more important (?), matter is UI and supporting > functionality. > > I think it would be nice to have better UI support for inserting these > references. > > To John's point, could we add interactive functions to insert labels > and cross-references (say as customizable functions?), using the > existing internal link support, and iterate that support over time? > > Bruce > --0000000000000164ab05ce2e5c96 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
I think the existing link capability of org-mode is comple= tely adequate for cross-references. LaTeX exports are almost completely cov= ered in org-ref. I made a refproc (https://github.com/jkitchin/org-r= ef/blob/org-ref-3/org-ref-refproc.el) that provides similar export beha= vior for other backends in a pre-processing hook. It supports the concepts = in autoref and cleveref by replacing the org-links with an appropriate org = syntax that then exports natively. For example, if cref:name references a t= able, it would get replaced by "Table [[name]]" in the buffer and= then exported to the desired backend.=C2=A0

All of thes= e are references to two tables named b1 and b2

- ref :: ref:b= 1
- autoref :: autoref:b1
- nameref :: nameref:b1
- pageref :: pag= eref:b1
- cref :: cref:b1
- cref, two :: cref:b1,b2
- Cref :: Cref= :b1
- Cref, two :: Cref:b1,b2

and they are converted to this plain org syntax (which ba= sically mirrors what would happen in a LaTeX export).

<= div>- ref :: [[b1]]
- autoref :: Tab. [[b1]]
- nameref :: [[b1][this = is a table b1.]]
- pageref :: [[b1]]
- cref :: =C2=A0Tab. [[b1]]
-= cref, two :: Tabs. [[b1]] and [[b2]]
- Cref :: Tab. [[b1]]
- Cref, t= wo :: Tabs. [[b1]] and [[b2]]

There are some o= ptions to control if the clever parts are abbreviated and/or capitalized.

This should be part of org-ref on Melpa next week.<= /div>

John

--------------------------= ---------
Professor John Kitchin (he/him/his)
Doherty Hall A207F
D= epartment of Chemical Engineering
Carnegie Mellon University
Pittsbur= gh, PA 15213
412-268-7803


On Sun, Oct 10= , 2021 at 9:30 AM Bruce D'Arcus <bdarcus@gmail.com> wrote:
Can we go back to this question of whether internal link= s are adequate
for cross-references, and if not, what's missing?

On Fri, Aug 13, 2021 at 11:22 AM Eric S Fraga <e.fraga@ucl.ac.uk> wrote:
>
> Hello John & co.,
>
> I need to chime in when it comes to the UI:
>
> On Thursday, 12 Aug 2021 at 13:19, John Kitchin wrote:
> > I would say the UI that I like, have used for many years, and is = the
> > default of org-ref is:
> >
> > 1. You type C-c ] to insert a citation
> > 2. You type C-u C-c ] to insert a cross-reference
> > 3. you type C-u C-u C-c ] to insert a new label.
>
> UI is a very personal thing.=C2=A0 So long as there are 3 different fu= nctions
> that implement these actions, I would be happy...

[snip]

> In terms of the bigger picture, citations and cross-references, to me,=
> are different things (one is external and the other usually internal,<= br> > respectively) and I see no benefit in conflating them.=C2=A0 I am also= still
> not convinced that org links are not sufficient ...

In reviewing and playing with this functionality a bit, it's clear to me that internal links are intended to be cross-references, even if
they fall short for certain classes of users.

Let's take a simple example of a figure, adapted from the manual:

#+begin_example
#+CAPTION: This is the caption.
#+NAME: fig:SED-HR4049
[[./img/a.jpg]]

Here's a cross-reference to Figure [[fig:SED-HR4049]].
#+end_example

This internal link seems to produce consistent and correct output
across latex, html, and odt.

The "fig" prefix is meaningful to ref in latex to enable it to ty= pe
that cross-reference. I'm unsure how typing in the odt context works, but it does.

The only downside is one has to manually, per the example, insert the
prefix (here "Figure ") in text (though this is a small price to = pay
in my view).

If one wants to use cleveref or autoref instead, as is now possible
with a recent commit, those packages handle that automatically. But of
course, this only works in latex, so you lose the consistency across
the backends.

Also, you then need to be able to specify different variants locally
(for example, cref vs Cref), which is not possible currently.

So I'm unclear: is that added functionality and complexity really
needed? Is there something else I'm missing?

A separate, possibly more important (?), matter is UI and supporting
functionality.

I think it would be nice to have better UI support for inserting these
references.

To John's point, could we add interactive functions to insert labels and cross-references (say as customizable functions?), using the
existing internal link support, and iterate that support over time?

Bruce
--0000000000000164ab05ce2e5c96--