Suggested improvements for JSS support

[statibk]

By filing an issue to this repo, I promise that

• I have fully read the issue guide at https://yihui.name/issue/.
• I have provided the necessary information about my issue.
  • If I'm asking a question, I have already asked it on Stack Overflow or RStudio Community, waited for at least 24 hours, and included a link to my question there.
  • If I'm filing a bug report, I have included a minimal, self-contained, and reproducible example, and have also included xfun::session_info('rticles'). I have upgraded all my packages to their latest versions (e.g., R, RStudio, and R packages), and also tried the development version: remotes::install_github('rstudio/rticles').
  • If I have posted the same issue elsewhere, I have also mentioned it in this issue.
• I have learned the Github Markdown syntax, and formatted my issue correctly.

I understand that my issue may be closed if I don't fulfill my promises.

---

After authoring my first own rticles-based JSS submission, I wanted to thank you for providing Rmd support for JSS and suggest some small improvements.

Continuation prompts

At the moment rticles employs either R+ (for evaluated code) or R> (for non-evaluated code) as the continution prompt but + would be requested by JSS. As an example,

```{r}
f(a = 1,
  b = 2)
```

is currently displayed as follows when combined with eval=TRUE

R> f(a = 1,
R+   b = 2)

and with eval=FALSE as

R> f(a = 1,
R>   b = 2)

but

R> f(a = 1,
+    b = 2)

would be desired.

Address formatting

In skeleton.Rmd a simple > continuation is used for the address. However, to force the right line breaks | continuation would be better. I would suggest instead of

address: >
  First line
  Second line

to use:

address: |
  | Department/Faculty/etc.
  | Street Number
  | ZIP City, Country

Inline code formatting

For code in Markdown it is ok to use backtick syntax, so that \code{...} is typically not necessary. Hence I it is ok to remove \code{print("abc")} from skeleton.Rmd, I think.

Escaping code/math in section titles

How can code/math formatting in section titles be escaped? For example, when I want in LaTeX

\section[R code]{\proglang{R} code}

Can this be done in Markdown/Pandoc? If so, an example in skeleton.Rmd might help.

Thanks for all your efforts regarding JSS support, these are much appreciated!
Achim

[yihui]

Hi Achim, thanks for the kind words, and sorry for the late response! I think the first three improvements should be easy to implement, and I'll definitely do them. For the last one, it would be great if Pandoc could support short titles (not yet: jgm/pandoc#4409). I might be able to come up with a hack like this:

# \proglang{R} code [R code]{.short-title}

I'll think more about it.

[Freguglia]

Inline code formatting

For code in Markdown it is ok to use backtick syntax, so that \code{...} is typically not necessary. Hence I it is ok to remove \code{print("abc")} from skeleton.Rmd, I think.

Complementing this suggestion, the backticks styntax `a = 1` seem to render as \texttt{a = 1} instead of \code{a = 1}. In a recent submission I have used the backtick syntax, but then realized this and wasn't sure if it was ok, so I ended up rewriting all inline code with \code{}.

Is this worth changing? I'm not sure if we can control how Pandoc converts backtick blocks, but assuming we do not use \texttt{} in the Rmd file, the could would probably be done with a gsub() call?

[yihui]

@Freguglia Since @statibk said it was okay to use backticks, I guess he implied that \texttt{} was also fine (correct me if my understanding is wrong).

[yihui]

@cderv For the fourth issue, let's see if a Lua filter could work, e.g., see if we can generate

\section[R code]{\proglang{R} code}

from

# \proglang{R} code {short-title="R code"}

One thing that I'm not sure about is whether it works if the section title uses Markdown syntax, e.g., can

# **R** code {short-title="R code"}

generate

\section[R code]{\textbf{R} code}

instead of

\section[R code]{**R** code}

? I guess the answer is yes, but just want to make sure.

[yihui]

@statibk I'm wondering if it's okay to use \sectionmark{}: https://www.texfaq.org/FAQ-runheadtoobig

# \proglang{R} code

\sectionmark{R code}

If that's acceptable, there is nothing we need to do in rticles except documenting it.

[cderv]

Just to give a synthesis of the changes to adress before closing this issue:

• use + as continuation prompt for evaluated code chunk (done in Implemented some of the suggestions from #254 to jss_article #294)
• use + as continuation prompt for non-evaluated code chunk - not covered by Implemented some of the suggestions from #254 to jss_article #294, to be dealt in JSS continuation prompt when eval=FALSE #311
• adress formating - added as part of add a lua script to include short titles on headers #310
• inline code formating (done in Implemented some of the suggestions from #254 to jss_article #294)
• Escaping code/math in section titles - in discussion for a solution - currently done in add a lua script to include short titles on headers #310
• add knitr::purl call to generate the R replication code (per JSS requirement : https://www.jstatsoft.org/pages/view/style)

[cderv]

@yihui I tested and

# \proglang{R} code {short-title="R code"} renders as

\hypertarget{code}{%
\section{\texorpdfstring{\proglang{R} code}{ code}}\label{code}}

and # **R** code {short-title="R code"} renders as

\hypertarget{r-code-1}{%
\section{\texorpdfstring{\textbf{R} code}{R code}}\label{r-code-1}}

but either one generate currently a ! Use of \\pdfbookmark doesn't match its definition. issue when rendering.
Seems to be a conflict with this PDF bookmark feature.
It seems to come from hypertarget that don't like this \proglang in the section header

I'll see what I can come up with Lua to overcome that, but using \proglang in section headers seems not ok in this cases... 🤔

[yihui]

@cderv It seems that you haven't written the Lua filter yet? I wonder if the problem persists if we actually add the short title in the square brackets after \section.

[cderv]

It seems that you haven't written the Lua filter yet?

No I haven't yet write effectively, but I am onto it. Indeed, this works if we add the short title.

\hypertarget{code}{%
\section[R Code]{\texorpdfstring{\proglang{R} code}{ code}}\label{code}}

This is the hint I am following currently to write the lua filter.

[cderv]

Notes from my search :
It seems it happens that pandoc can use an optionals that could be bracketed
https://github.com/jgm/pandoc/blob/9d0506e4047f797a0672d7767830b59f1710d191/src/Text/Pandoc/Writers/LaTeX.hs#L981-L984

  optional <- if unnumbered || lstNoNotes == lst || null lstNoNotes
                 then return empty
                 else
                   return $ brackets txtNoNotes

and optionals is prepended before the content.

But I don't really know how to activate it. It seems a bit specific to a case, but can be useful to support short title.

[cderv]

Regarding lua, getting the short-title attributes is easy but then we have not so much to modify... the content will be included inside curly braces {} by pandoc so we can't preprend, and I am still looking if something can be modified to activate the optional linked above.

One solution could be to detect headers with short-title attributes and then replace them with a latex RawBlock, similar from the pandoc one. Having support for short titles in Pandoc who really be the best solution ! 😄

[yihui]

One solution could be to detect headers with short-title attributes and then replace them with a latex RawBlock

I'm okay with that. It seems you have implemented it in #310.

Having support for short titles in Pandoc who really be the best solution!

Sure. If jgm/pandoc#4409 is implemented, we should switch to the official solution.

[cderv]

While reading the jss style guide https://www.jstatsoft.org/pages/view/style, I am reading that an R file with replication code should be provided. I added to the todo #254 (comment)

@statibk does the Rmd file is enough or if we automatically produce an R script from the Rmd file using knitr::purl this would be useful ?

[yihui]

Most issues have been solved by the PR #310. Only one is left (#311) and hopefully we can also address it soon.

[github-actions]

This old thread has been automatically locked. If you think you have found something related to this, please open a new issue by following the issue guide (https://yihui.org/issue/), and link to this old issue if necessary.