emacs-orgmode
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Expanding how the new cite syntax is used to include cross-reference


From: John Kitchin
Subject: Re: Expanding how the new cite syntax is used to include cross-references - thoughts?
Date: Tue, 12 Oct 2021 17:16:19 -0400

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


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 links 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.  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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]