A few suggestions for cross referencing and text layout

[jjallaire]

Discussed in #1088

^{Originally posted by arnaudgallou June 7, 2022}
Here're a few suggestions/recommendations for possible improvements. I couldn't find easy solutions in the documentation to do what follows so I assume no proper solutions already exist.

Cross referencing

1. Being able to customize the text of the link when referencing a particular panels in a composite plot (e.g. generated by ggplot::facet_grid() or ggplot::facet_wrap()). The idea would be to have something that looks like Fig. 1A or Fig. 1A-B. I'm currently using [@fig-x]A-B which produces Fig. 1A-B but the unlinked plot tag looks ugly when the ref-hyperlink option is true. I was thinking to have something like @fig-x{A} or @fig-x{A-B} to append some text to the text link.

2. Somewhat similar to the first point. I'm missing a more flexible way to customize the prefix of supplementary figue/table refs. At the moment, using the fig-prefix option adds a space between the prefix and label. A solution could be to have no space as default prefix separator so that fig-prefix: "Fig. S" would produce Fig. Sx and add a space in the prefix if need be fig-prefix: "fig. ". Alternatively, we could have a yaml option to set the prefix separator. Currently using Fig. S[-@fig-x] which has the same ugly look when enabling hyperlinks.

3. Adding a x-title-template option for figures and tables to customize the text of figure/table titles easily and with more control. We could imagine something with a placeholder for the labelling. E.g. fig-title-template: "**Fig. S{label}.**" would produce Fig. S1. I can more or less do that with title-delim and fig-title, although I don't find it very convenient. However, I cannot figure out an easy way to have the fig-labels bold. Besides, I have the same spacing problem as mentioned in point 2 for supplementary figures/tables.

4. I'm missing an easy-to-use system for cross referencing between the supplementary materials and main text. Not sure what would be a simple solution for that because I assume cross references are generated during the rendering process. Ideally, I would imagine adding a yaml option in the main text file to link all references from a specific document (e.g. appendix: supplementary.qmd) and have a new tag for supplementary figures/tables (e.g. @fig-supp-x) for easy cross referencing in the main text.

5. Adding a way to have a cross reference and citation within the same pair of brackets. E.g.: blah blah Foo (1999; Fig. 1). Probably quite specific and not very common so not sure how relevant it is.

Text layout

1. Adding a yaml option to align figure/table captions to the left/right/center. This can easily be done with some css but such a trivial thing should be done with a yaml option in my opinion.

2. Adding a yaml option to justify the text of the document. Same as above, can easily be done with a line of css but having a yaml option to do it would make sense to me.

Other

In RStudio, that would be great to have the possibility to open a file that was included in a document using the {{< include >}} shortcode by clicking on it in the visual markdown editor. E.g.:

{{< include _file.qmd >}} # click the shortcode tag to open _file.qmd in a new tab

[simonjackman]

another/further suggestion: make the table/figure labelling/x-ref framework extensible, so that users can define new numbered objects (theorem, lemma, definition, algorithm etc), numbering style and section/chapter nesting options a la LaTeX. Or is this already possible?

[jjallaire]

Thanks, yes, more extensibility is definitely in order. There are some options currently available to customize numbering styles and labels: https://quarto.org/docs/authoring/cross-references.html#options

[arnaudgallou]

Just would like to make some corrections. I don't consider the "text layout" suggestions worth implementing anymore. I realise that every time I render something as HTML, I create a .css file anyway and it's just as easy to center and justify things in the .css directly.

What I could add to the suggestions would be to have an option to prepend nocite references to the bibliography instead of adding them after cited refs (see #1183). This is a requirement for some journals to have the list of all references in the appendix so that could definitely be useful. Not sure if should understand the answer on the thread as "this isn't possible" though, in which case just ignore the suggestion.

[Achuan-2]

@jjallaire I have a requirement. When number-sections: true is turned on, I want to generate a format like Figure 1-1 instead of Figure 1.1. What should I do for pdf and gfm output?

[jjallaire]

We don't currently have an option for that but will definitely do so when we work on other improvements to crossrefs (should be in the next couple of releases)

[perechen]

Was there a solution to a space between a title and a number, when using fig-title: "Figure S"? So that the output would be Figure S1, instead of Figure S 1.

[arnaudgallou]

@perechen In the meantime, you can use some LaTeX commands:

---
format:
  pdf:
    include-in-header:
      text: |
        \usepackage{caption}
        \DeclareCaptionLabelFormat{fig}{
          \textbf{#1 S#2}
        }
        \captionsetup[figure]{
          labelformat=fig
        }
---

#1 corresponds to the figure title while #2 is the figure number.

You can also save the LaTeX commands in a file (e.g. styles.tex) and import it.

---
format:
  pdf:
    include-in-header: styles.tex
---

[altonrus]

@perechen @arnaudgallou: Is there a workaround for the space between a title and number that will work when knitting to Microsoft Word? Here's the YAML header for my document where I'm commandeering the cor and lem crossrefs for my supplemental tables and figures, but end up with, e.g., "Table S 1" instead of "Table S1".

---
title: "Title"
format:
  docx: 
    reference-doc: word-style-reference-manuscript.docx
    execute:
      echo: false
      warning: false
crossref: 
  thm-title: "Table"
  thm-prefix: "Table"
  cor-title: "Table S"
  cor-prefix: "Table S"
  lem-title: "Figure S"
  lem-prefix: "Figure S"
---