s-u
commented
10 months ago Most of the above are indeed bugs in rjtools. I'll comment on some that I could trace, but authors of rjtools are needed to fix them - most of them stem from either the template and metadata processing.
-
[x] html text in the subtitle is replaced with "
published in The R Journal." and the actual subtitle is incorrectly pushed to the "abstract" field:</p> <pre><code> title: Changes on CRAN subtitle: 2023-05-01 to 2023-09-30</code></pre> <h1>Changes on CRAN</h1> <p>“Changes on CRAN” published in The R Journal.</p> <p><b>Abstract:</b> 2023-05-01 to 2023-09-30 <hr>but should be:</p> <h1>Changes on CRAN</h1> <p>2023-05-01 to 2023-09-30</p> </li> <li> <p>[x] "Citation" entry in the footer duplicates the journal - likely from the title mangling:</p> <p>For attribution, please cite this work as</p><pre class="citation-appendix short">Hornik, et al., "The R Journal: Changes on CRAN", The R Journal, 2023</pre> </li> <li> <p>[ ] References in the html version have a several issues (see above) - they are not consistent with the PDF version and include</p> <ul> <li>incorrect case</li> <li>different (e.g., superfluous) tags</li> </ul> </li> </ul> <p>Issues from above that may not be directly <code>rjtools</code>-related:</p> <ul> <li>supplementaries are missing if they are not mentioned in the <code>DESCRIPTION</code>. However, this is legal if they consist of the single <code>.R</code> file, e.g. from <code>.Rmd</code>, so this is more likely an <code>rj</code> bug where it fails to create the ZIP file in those cases. (For the current issue I have created them by hand).</li> <li>The C443 had odd case which was partially corrected, but apparently not everywhere.</li> </ul> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/s-u"><img src="https://avatars.githubusercontent.com/u/2073427?v=4" />s-u</a> commented <strong> 10 months ago</strong> </div> <div class="markdown-body"> <p>On the wrong title issue - this seems to come from <code>distill::qualified_title</code> <a href="https://github.com/rstudio/distill/blob/d88adcaacd6b3b4e96e3f2b88449b4b839ddff0a/R/metadata.R#L870-L876">https://github.com/rstudio/distill/blob/d88adcaacd6b3b4e96e3f2b88449b4b839ddff0a/R/metadata.R#L870-L876</a> but I don't see neither the logic nor a way to disable it so it looks like a "feature" of distill that cannot be disabled. I fail to see how that is helpful since the title is always wrong in citations, no matter what, as the journal name is never part of the article title when citing. The site title is used in other contexts so we cannot just remove it from the site config - it looks like a bad design. For the R Journal we just have to use modified distill - fixed in this fork <a href="https://github.com/rjournal/distill/commit/72c26ad4b916420bf23739ce26342dcb97382453">https://github.com/rjournal/distill/commit/72c26ad4b916420bf23739ce26342dcb97382453</a> </p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/s-u"><img src="https://avatars.githubusercontent.com/u/2073427?v=4" />s-u</a> commented <strong> 10 months ago</strong> </div> <div class="markdown-body"> <p>Abstract handling is a mess, but <a href="https://github.com/rjournal/rjtools/commit/5f0fe0d44153fc42d88d274c486ddd022f0f613f">https://github.com/rjournal/rjtools/commit/5f0fe0d44153fc42d88d274c486ddd022f0f613f</a> at least fixes the look in the web output. It really needs a re-write to handle abstracts natively in cooperation with distill.</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/huizezhang-sherry"><img src="https://avatars.githubusercontent.com/u/36781502?v=4" />huizezhang-sherry</a> commented <strong> 10 months ago</strong> </div> <div class="markdown-body"> <p>first dot point under <em>Issues in our color paper</em>: The table reference will show in the html version if </p> <ol> <li>the markdown caption has a label, e.g. <code>Table: (\#tab:foo) An overview …</code>, and</li> <li>proper in-text citation is used, i.e. <code>The table \@ref(tab:foo) below summarizes</code></li> </ol> <p>I will keep tracking on the other raised issues. </p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/zeileis"><img src="https://avatars.githubusercontent.com/u/61125774?v=4" />zeileis</a> commented <strong> 10 months ago</strong> </div> <div class="markdown-body"> <p>Sherry, thanks for the information. It would be good to add some guidance on this in the documentation. I had checked out <a href="https://rjournal.github.io/rjtools/articles/format-details.html#tables">https://rjournal.github.io/rjtools/articles/format-details.html#tables</a> and also tried</p> <pre><code>knitr::kable(head(cars), format = "markdown", caption = "Cars data", label = "cars")</code></pre> <p>In general it would be helpful to have more guidance on how to write content in Markdown directly (as opposed to generating content via R).</p> <p>Simon, I don't want to add to all the time you already spent on this. If you want to update the .Rmd for our color paper, great - if not, no problem either. I would use</p> <pre><code>Table: (\#tab:overview) An overview ...</code></pre> <p>and</p> <pre><code>Table \@ref(tab:overview) below summarizes ...</code></pre> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/huizezhang-sherry"><img src="https://avatars.githubusercontent.com/u/36781502?v=4" />huizezhang-sherry</a> commented <strong> 10 months ago</strong> </div> <div class="markdown-body"> <p>added in commit b45333139850f331ac0c8f5f324c862c5475ecb2.</p> <p>If using <code>knitr::kable()</code> with the <code>label</code> argument, the following also works: </p> <ul> <li> <p><code>Table \@ref(tab:cars) says ....</code></p> </li> <li> <p><code>knitr::kable(head(cars), format = "markdown", caption = "Cars data", label = "cars")</code></p> </li> </ul> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/s-u"><img src="https://avatars.githubusercontent.com/u/2073427?v=4" />s-u</a> commented <strong> 10 months ago</strong> </div> <div class="markdown-body"> <p>@zeileis sure, I have modified the sources accordingly (<a href="https://github.com/rjournal/rjournal.github.io/commit/c13141a97c83d7499baea6eb1832d76da988e5c3">https://github.com/rjournal/rjournal.github.io/commit/c13141a97c83d7499baea6eb1832d76da988e5c3</a>) - it seems to do the trick, thanks.</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/s-u"><img src="https://avatars.githubusercontent.com/u/2073427?v=4" />s-u</a> commented <strong> 10 months ago</strong> </div> <div class="markdown-body"> <p>I have filed the distill citation bug as <a href="https://github.com/rstudio/distill/issues/504">https://github.com/rstudio/distill/issues/504</a></p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/huizezhang-sherry"><img src="https://avatars.githubusercontent.com/u/36781502?v=4" />huizezhang-sherry</a> commented <strong> 10 months ago</strong> </div> <div class="markdown-body"> <p>second dot point under Issues in our color paper - Wikipedia URL display in web format</p> <p>I suspect this might also be a distill issue that the <code>howpublished</code> field is not supported in the citation (need confirmation here). </p> <p>A workaround here is to use the <code>url</code> field: </p> <pre><code>@Misc{Wiki+HCL, author = {Wikipedia}, title = {{HCL Color Space} --- {W}ikipedia{,} The Free Encyclopedia aksdjflksjdfl}, year = {2023}, url = {https://en.wikipedia.org/wiki/HCL_color_space}, note = {accessed 2023-07-12} } </code></pre> <p>I also added this instruction to the journal format detail vignette 78171684acd40e55675e4d4e9257a4b34457e378.</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/zeileis"><img src="https://avatars.githubusercontent.com/u/61125774?v=4" />zeileis</a> commented <strong> 10 months ago</strong> </div> <div class="markdown-body"> <p>In a plain <code>distill_article</code> I don't have any problems with the <code>howpublished</code> field. Using a slightly adapted example from <a href="https://rstudio.github.io/distill/citations.html">https://rstudio.github.io/distill/citations.html</a> I get:</p> <p><img src="https://github.com/rjournal/rjtools/assets/61125774/97c3b1d1-250f-40d3-8017-e43d450b947b" alt="Screenshot from distill document with Wikipedia HCL reference" /></p> <p>The source code of the document is from the link above, just modified to use the <code>color.bib</code> file from our paper.</p> <pre><code>--- title: "Distill for R Markdown" description: | Scientific and technical writing, native to the web output: distill::distill_article date: May 4, 2018 author: - name: Nora Jones url: https://example.com/norajones affiliation: Spacely Sprockets affiliation_url: https://example.com/spacelysprokets bibliography: color.bib --- This is in @Wiki+HCL.</code></pre> </div> </div> <div class="page-bar-simple"> </div> <div class="footer"> <ul class="body"> <li>© <script> document.write(new Date().getFullYear()) </script> Githubissues.</li> <li>Githubissues is a development platform for aggregating issues.</li> </ul> </div> <script src="https://cdn.jsdelivr.net/npm/jquery@3.5.1/dist/jquery.min.js"></script> <script src="/githubissues/assets/js.js"></script> <script src="/githubissues/assets/markdown.js"></script> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.4.0/build/highlight.min.js"></script> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.4.0/build/languages/go.min.js"></script> <script> hljs.highlightAll(); </script> </body> </html>
When proofreading my contributions in the draft for R Journal 2023-3 at https://rjournal.github.io/issues/2023-3/ I noticed various issues that are likely caused by
rjtoolsand/ordistill. Hence Simon @s-u advised me to also post my feedback to him here.General issues
In general, the "Citation" generated at the end of every contribution should be fixed. The
journalfield "The R Journal" is repeated incorrectly at the beginning of thetitlefield. Both in the text and in the BibTeX version.In several papers, inconsistencies in the "References" occur between the HTML and the PDF version. Book, manual and proceedings titles are written in title case in the PDF version. In the HTML version, however, they are coerced to sentence case which sometimes leads to proper names being written in lower case. An example is "vienna, austria" in the Ihaka (2003) reference in our color paper, see: https://rjournal.github.io/articles/RJ-2023-071/ But I also noticed other cases (e.g., "Writing r extensions" in the Zhang et al. paper).
In several papers the "supplements" link does not work. For example, in our color paper: https://rjournal.github.io/articles/RJ-2023-060/RJ-2023-060.zip But I noticed the same problem for several other papers.
Issues in our color paper
https://rjournal.github.io/articles/RJ-2023-071/
The table at the end is labeled "Table 1" in the PDF while it has no label in the HTML version. Is this difference intentional? (We noticed this already when writing the paper, so that the text says "table below" which is correct in both versions.)
The URL and the access date in the Wikipedia reference is shown in the PDF version but not in the HTML version. The access date is not so crucial but the URL should really be displayed.
Other issues
In the "C443" paper the title is in sentence case while all the remaining titles are in title case. Also "R-package is hyphenated throughout the paper while it is typically not hyphenated elsewhere. In summary, the title should be: "C443: An R Package to See a Forest for the Trees"
I found a small problem with the HTML version of our "Changes on CRAN" contribution. The subtitle and abstract have been interchanged, see: https://rjournal.github.io/news/RJ-2023-3-cran/ Some additional details are described below.
The article has the subtitle "2023-05-01 to 2023-09-30" and no abstract.
This is shown correctly in the PDF version.
The HTML that I submitted showed the subtitle correctly and added the default abstract: "Changes on CRAN" published in The R Journal. This is ok.
But the current draft has now switched subtitle and abstract. Please revert this change.