Description

Authors should be able to cite their assets (figures, figure supplements, tables, videos, video supplements, asset-source files, source data, source code, supplementary files, reporting standard files, equations, appendices, boxes) anywhere in their main text, section titles, appendices, and asset titles and legends.

[UPDATED: 18/06/2019 to add boxes as a citable item]

User Stories

Author

As an author, I want to be able to add a citation to a figure, table or another asset so that I can reference a relevant item.
As an author, I want to be able to remove an asset citation so that I can correct mistakes.
As an author, I want to be able to cite specific panels or parts of an asset so that I can direct readers to specific points. (e.g. "Figure 1B", "Figure 2C—D", "Supplementary file 1B")
As an author, I want to be able to cite ranges of assets so that I can reference multiple assets at once. (e.g. "Figure 1—figure supplements 1, 2 and 3" or "Tables 1—9" )
As an author, I want to be able to cite ranges of assets and parts of an asset simultaneously so that I can reference specific parts of multiple assets at once. (e.g "Figure 1A, 2C, 8D" )
As an author, I want to be able to edit an existing citation so that I can correct errors.

Production staff

But what if . . . ?

Considerations

We'll want asset citations to update automatically following changes to asset numbering/ordering so that the authors don't have to individually change every single citation!
What do we want to happen with combined citations? Do we want them to point to all the figures present, just the first one mentioned or what? Bear in mind that at present, the website will only jump to the first asset cited (assets are fixed and so one cannot really view multiple at once).
One thing that the current proofing system does is that if you click an asset citation, it brings up the figure/video/table in a right-hand panel next to the text. This allows one to see both asset and citation at the same time, rather than just jumping back and forth.
eLife does not currently support multi-panel figures but authors will still add part labels within single figure images. This means that any citations of, say, Figure 1A will be exactly equivalent to citations of Figure 1, just with different display text.
SourceData does support multi-panel figures, meaning a citation of Figure 1A will point to panel A in Figure 1.

XML requirements

These are captured as simple xref elements, with an appropriate @ref-type and an @rid whose value is the same as the @id of the asset.

<xref ref-type="fig" rid="fig1">Figure 1B</xref>

eLife uses the following ref-type attribute values (for assets):

fig
supplementary-material
video
table
other (for boxes)

figure examples

<xref ref-type="fig" rid="fig7s1">Figure 7—figure supplement 1A</xref>

<xref ref-type="fig" rid="fig6">Figure 6I,J</xref>

<title>Two photon experiments (<xref ref-type="fig" rid="fig1s3">Figure 1—figure supplement 3A</xref>)</title>

<xref ref-type="fig" rid="fig1 fig2 fig3 fig4 fig5">Figures 1-5</xref>

supplementary-material examples

<p> ... <xref ref-type="supplementary-material" rid="supp1">Supplementary file 1</xref> and <xref ref-type="supplementary-material" rid="scode2">Source code 2</xref> ... </p>

<xref ref-type="supplementary-material" rid="fig4sdata2">Figure 4—source data 2</xref>

<xref ref-type="supplementary-material" rid="SD7-data">Table 1—Source code 1</xref>

video examples

<p> ... <xref ref-type="video" rid="video3">Videos 3</xref>, <xref ref-type="video" rid="video4">4</xref>, and <xref ref-type="video" rid="video5">5</xref> ... </p>

<xref ref-type="video" rid="fig7video1">Figure 7—video 1</xref>

table examples

<xref ref-type="table" rid="app1table1">Appendix 1—table 1</xref>

<p> ... <xref ref-type="table" rid="table1 table2 table3">Tables 1–3</xref> ... </p>

appendix example

<xref ref-type="app" rid="app1">Appendix 1</xref>

boxed-text example

<xref ref-type="other" rid="box1">Box 1</xref>

[These ref-type values are also allowed for non-assets:

other
fn
disp-formula
sec
bibr
aff
app]

As specified above the content of the citations should contain the label of the object that it cites, but this content needs to be editable to that more or less information can be added.

xref placement

eLife requires xref to be allowed in the following elements:

p
td
th
title
formatting elements (such as italic, bold, underline, sc etc.)
license-p
attrib

(as well as fig-group,fig,table-wrap, and media - although see this ticket for context).

substance / texture

Asset citations #1284