Suggested edit to simple table cross-referencing documentation

[DanOvando]

Given the new interactive table generator in the RStudio preview visual markdown editor, it seems like those sorts of simple tables might get an uptick in use (I find them really handy for generating text-heavy tables, as opposed to trying to shoehorn the content into a dataframe and passing to knitr::kable)

I found the cross-referencing documentation for these types of tables to be a little confusing though. I would suggest something like this instead (this could be updated once the visual markdown editor becomes part of the standard RStudio release to reflect the format created by the interactive table generator?)

Pandoc supports several types of Markdown tables, such as simple tables, multiline tables, grid tables, and pipe tables. You can write your own simple table directly in markdown like this:

Table:(\#tab:simple-table) A simple table in Markdown.
 Sepal.Length   Sepal.Width   Petal.Length   Petal.Width
-------------  ------------  -------------  ------------
          5.1           3.5            1.4           0.2
          4.9           3.0            1.4           0.2
          4.7           3.2            1.3           0.2
          4.6           3.1            1.5           0.2
          5.0           3.6            1.4           0.2
          5.4           3.9            1.7           0.4

Which will produce this table when the document is knit

Table:(#tab:simple-table) A simple table in Markdown.

Sepal.Length Sepal.Width Petal.Length Petal.Width

---

      5.1           3.5            1.4           0.2
      4.9           3.0            1.4           0.2
      4.7           3.2            1.3           0.2
      4.6           3.1            1.5           0.2
      5.0           3.6            1.4           0.2
      5.4           3.9            1.7           0.4

You can then cross-reference this simple table using \@ref(tab:simple-table), creating Table.@ref(tab:simple-table).

bookdown/inst/examples/02-components.Rmd

Line 556 in 74c8bef

Table: A simple table in Markdown.

[cderv]

For reference, this is following a question in the Community : https://community.rstudio.com/t/cross-referencing-tables-generated-by-rstudio-preview-version/83575/2

And also the referencing for new visual editor is mentioned here: https://rstudio.github.io/visual-markdown-editing/#/markdown?id=cross-references

And @DanOvando , the bookdown book already mentioned the Pandoc different tables, and what to add in the caption for referencing. It is at the bottom here: https://bookdown.org/yihui/bookdown/tables.html

Your suggestion is to mention the visual editor ?

[DanOvando]

Ha thanks @cderv, sorry forgot to reference the discussion from the RStudio community page! I agree that the documentation as is does cover the topic, but I found it a bit confusing at first read. Because the simple table is referenced as an output of knitr::kable(), some users might not realize that they can create this themselves directly in the markdown document, outside of a code chunk. For the captioning, I think that an explicit example like Table:(\#tab:simple-table) A simple table in Markdown. that matches the text of the generated table would just make it a bit more clear that the user themselves can enter that, and the Table: A simple table in Markdown was not something just printed to the console by knitr? Particularly since all the other figures and tables involve naming chunks, so being that simple tables work a little differently I think it might be worth being very explicit in the documentation.

For the visual editor, once that comes out, yes I'd agree that some specific comment in the bookdown documentation to that would be helpful, e.g. as you pointed out not writing (#label) instead of (\#label) if created via the interactive table generator.

Both are minor points, so understood if you don't feel they are needed at the moment