Missing table in section 9.4 of Stan-Users-Guide

[enbrown]

Summary:

The table referenced in section 9.4 ("Coding Ragged Arrays") is present in the PDF output but not the HTML output.

Description:

The table present in the PDF user guide on page 129 with columns 'n', 'w[n]', and 'doc[n]' is missing from the HTML output.

A second, possibly related typography bug is that the PDF table typesets the characters 'n' where \texttt{n} and similar are likely better (so the typography would match the following text).

Additional Information:

The table missing is:

docs/src/stan-users-guide/clustering.Rmd

Lines 258 to 273 in 90cb5fd

	\begin{center}
	\begin{tabular}{r|cc}
	`n` & `w[n]` & `doc[n]` \\ \hline
	1 & $w_{1,1}$ & 1 \\
	2 & $w_{1,2}$ & 1 \\
	\vdots & \vdots & \vdots \\
	$N_1$ & $w_{1,N[1]}$ & 1 \\
	$N_1 + 1$ & $w_{2,1}$ & 2 \\
	$N_1 + 2$ & $w_{2,2}$ & 2 \\
	\vdots & \vdots & \vdots \\
	$N_1 + N_2$ & $w_{2,N[2]}$ & 2 \\
	$N_1 + N_2 + 1$ & $w_{3,1}$ & 3 \\
	\vdots & \vdots & \vdots \\
	$`N` = \sum_{m=1}^M N_m$ & $w_{M,N[M]}$ & $M$ \\
	\end{tabular}
	\end{center}

Current Version:

v2.19

[mcol]

That's not the only one. Also a table in 7.3 (Collective Cormack-Jolly-Seber Model) and one in 8.1 (Sparse Data Structures) missing. In all cases they use a Latex tabular (these are the only cases in the user's guide).

I've rewritten the table of 9.4 as a standard markdown table: the result in pdf is almost identical as the previous version (barring an extra horizontal line above the table and the lack of a vertical line after the first column). The html version is ok, perhaps it could be improved with a bit of css, but at least it's there now. If it's fine I could try to convert also the other ones (although one of them uses minipages, which I don't know if they would be rendered in html).

[bob-carpenter]

@mcol: converting more of these would be great. I'm embarassed I missed so many of them. I'm not sure how you can work from @enbrown's branch, but these don't all need to be fixed in the same PR.

[enbrown]

I think that these will come in through the same PR. Here's the HTML I came up with for the sparse data structure table:
https://github.com/enbrown/stan-docs/blob/cd453fc8075445d7db3f5409aceb8448e0373240/src/stan-users-guide/sparse-ragged.Rmd#L33-L66

And here's the HTML for the latent-discrete Rmd file:
https://github.com/enbrown/stan-docs/blob/cd453fc8075445d7db3f5409aceb8448e0373240/src/stan-users-guide/latent-discrete.Rmd#L488-L510

Of course, this isn't the only way of doing it. So if someone has a better idea, that's fine with me.

[mcol]

I didn't see that these were being fixed in the other PR. It's a matter of deciding whether there should be two specialized implementations of the same table (html and latex) or a plain one in markdown. My preference would be the unified approach for maintainability, but I can see that @enbrown's approach may look better.

[bob-carpenter]

Is there a way to have a unified source in markdown that doesn't require authors to write html directly? If so, I'd prefer to lower burden on authors than make it slightly better visualized. I'm thinking of the html docs as the primary ones these days, as they're what's searchable.

[enbrown]

The problem is that markdown syntax for tables is very limited. There is no markdown syntax to have cells span multiple columns or rows and none of the table borders/lines can be adjusted. So having column headers that span multiple columns (to group related columns) or doing something simple like having a border between the first and second columns (such as in the otherwise simple table in section 9.4) isn't possible. Even the many RMarkdown table-making packages seem to sometimes skip the markdown code and instead directly output HTML code to make a presentable table.

So I see three options (not mutually exclusive):

1. Use limited markdown tables that don't look good in either HTML or PDF but are easier to make
2. Use an R package that would generate each based on the output format (maybe xtable?)
3. Create markup in both HTML and LaTeX for the tables

Any other ideas?

[mcol]

If we go the package way, we could use knitr::kable and the kableExtra package (https://cran.r-project.org/web/packages/kableExtra/vignettes/awesome_table_in_html.html).

[betanalpha]

Having just done a long markdown doc with too many tables I can confirm that there really aren’t good markdown options for custom table styling. kable and its ilk are more focused on formatting of data frames into tables. Handwritten HTML was the only solution I could get to work.

…

On Jul 9, 2019, at 1:51 PM, Eric N. Brown ***@***.***> wrote: The problem is that markdown syntax for tables is very limited. There is no markdown syntax to have cells span multiple columns or rows and none of the table borders/lines can be adjusted. So having column headers that span multiple columns (to group related columns) or doing something simple like having a border between the first and second columns (such as in the otherwise simple table in section 9.4) isn't possible. Even the many RMarkdown table-making packages seem to sometimes skip the markdown code and instead directly output HTML code to make a presentable table. So I see three options (not mutually exclusive): Use limited markdown tables that don't look good in either HTML or PDF but are easier to make Use an R package that would generate each based on the output format (maybe xtable?) Create markup in both HTML and LaTeX for the tables Any other ideas? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#51?email_source=notifications&email_token=AALU3FTTMCSAXUOAWS6XNQLP6TF33A5CNFSM4H2V6GYKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODZRAUCA#issuecomment-509741576>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AALU3FV52SIDN2PIHGQBTI3P6TF33ANCNFSM4H2V6GYA>.

[mcol]

I've pushed another approach in #61 which allows nice formatting for both html and pdf documents based on kable. This avoids duplication of the code while making the tables still readable also when unformatted. It requires a bit of knitr magic in order to put tables side by side, as html_document doesn't show at all Latex minipages, while pdf_document completely ignores the html table markup.