A few suggestions for cross referencing and text layout

[jjallaire]

Discussed in https://github.com/quarto-dev/quarto-cli/discussions/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. 1]()A-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"
---

[eteitelbaum]

Are there plans to add left and right justification options for figure captions as suggested by the OP? I have seen some suggestions for how to do this with custom CSS but cannot find a good LaTeX solution. For example, I tried the caption package and it aligns the caption to the edge of the page rather than the edge of the image, e.g.

header-includes:
   - \usepackage{caption}
   - \captionsetup{justification = raggedright, singlelinecheck = false, skip = 0 pt}

[cscheid]

Are there plans to add left and right justification options for figure captions as suggested by the OP?

The problem with a direct implementation of this request is that the number of possible requests is infinite. What the new crossref system will offer is a way to render a crossreferenceable artifact in whatever way you see fit.

We still need to write up proper documentation for this, but the code will, more or less, look like this. Don't take this as documentation, just as a preview of how to do it:

-- my_custom_figure_renderer.lua
quarto._quarto.ast.add_renderer("FloatRefTarget", function(float)
  -- return true if you want to handle this specific float. In a renderer that replaces our default renderer, you'll probably
  -- want this to just "return true"
end, function(float)
  -- render your figure here, however you want. `float` is a Lua table with fields like `caption_long`, `content`, `identifier`, etc.
  local result = pandoc.Blocks({
    pandoc.RawInline("latex", "\begin{myfancyfigure}[myoptions]"),
    pandoc.RawInline("latex", "\mycustomcaption{\label{" .. float.identifier .. "}")
  })
  result.insert(float.caption_long)
  -- etc etc
  return result
end)

We'll have simple examples in our docs, but this is how it's going to be done. Header includes, etc, will be handled just like before.

[cscheid]

Part of this is now done in main, but the part that involves control over how the references themselves are rendered will be done in 1.5.