Bookdown contest submission: a live example for Elsevier academic journals

Publishing Your Results
,
1

Highlights

  • Write academic papers of Elsevier journals with R markdown syntax.
  • A live example is provided. I published it TODAY!
  • Create multiple file formats, including .pdf, single .html, gitbook, .md, .epub, docx.

Introduction

It is today that one of my academic manuscripts is published on Agricultural and Forest Meteorology, one of the top journals in my scientific research area. This paper is the first paper of mine written in R bookdown environment from the preparation to the publication. Hooray! Now it is time to share its bookdown files.

Elsevier is one of the world's major providers of scientific, technical, and medical information. Elsevier owns 2500 journals, which is why I would like to share my bookdown manuscript for re-use.

An Example with Its Repo

The example is the paper I have just published TODAY. It is open-access. Users could either see it online or download the pdf version. Before the publication, a version with numbered lines is recommended for reviewers, which looks like this:

1701×2201 32.4 KB

1701×2201 28.9 KB

1701×2201 29 KB

1701×2201 28 KB

1701×2201 31.7 KB

It is produced by my bookdown project, which is available on the GitHub Repo. You could view the .docx, .epub, .html, .pdf, and .tex as well.

I should mention that you will fail in creating the book if you only download the repo and build it with R bookdown. You could see that in 'index.Rmd' there is a line which calls an R script:

source('scripts/paper.R')

paper.R processes my data and creates the data and figures for the manuscript. I would not like to share paper.R at the moment. Anyway, you could get an impression how the pdf is created from the .Rmd files even without seeing paper.R.

Technical details

Elsevier provides a LaTeX template which is free for using. I modified it as 'tex/template.tex', i.e. something was moved from the original LaTeX template to the yaml of 'index.Rmd'. Users could simply compare them and then get an idea how to convert a LaTeX template into a bookdown template.

Re-use

  • Download the GitHub Repo.
  • Revise 'index.Rmd' as your own manuscript.
  • Build the book with R bookdown.

Any suggestions are welcome. Just PR the repo!

7 Likes
2

This is an incredibly useful example, which helped me learn much about cross-referencing and auto-numbering eqns, figures, etc. Thank you for sharing it.

Is it possible to use fig.cap='(ref:fig1)' to create the handle for later reference using \@ref(fig:fig1), but not have the caption render below the figure in bookdown::pdf_document2 output type? I've not discovered the appropriate combination of options to create the reference without printing the caption.

Thanks!

3

Thank you for your feedback. I did not quite get your point. If a figure is cross-referred, it needs a figure number. Do you mean that you want a figure with a number but wuthout a caption? Maybe the bookdown book Chapter 2.4 could help.

1 Like
4

Yes, that’s what I meant, I wanted the figure to have a number but for the caption to not be printed in the output. I will check out the book down chapter you suggested, and post a solution if I find it. Perhaps the figure must be places outside a code chunk, as you’ve done with your equations.

5

why not just give a blank caption, with a single space…:slight_smile:

6

I should clarify, I want the figure to get a reference (so I can cross-reference it), but not have a caption under the figure at all (I'd like to add my own caption with more complext Markdown text than appears to be allowed in the fig.cap options). As I understand it (from trial and error), the chunk must have a label and a caption, or the reference won't be generated, e.g., {r fig1, fig.cap=' '} works with \@ref(fig:fig1). However, it generates a figure with the caption Figure 1: (no other text). If I omit the fig.cap='' argument, the figure does not get a reference and \@ref(fig:fig1) produces ??.

I may not be making sense, but perhaps you can follow.

7

I see. If you'd like to add a caption with complext Markdown text, you could follow L148 in my example, according to the bookdown book chapter 2.2.4: Text References.

1 Like
8

Yes! This is the answer. It's clear that reading the Bookdown book from start to finish should be on my 'to do' list. I really appreciate you sticking with me to guide me to a solution. At present, these labels are not working as desired for bookdown::word_document2 (perhaps they never will), but they work for pdf_document2 and presumably html_document2 (haven't tried). Next up, refining the placement and size of figure images in my document...

9

glad that you've got it. The bookdown book is worth reading carefully again and again, as well as the pandoc documentation, where the answers to your questions could be hidden.

10

This looks great! And congrats on the real paper that you just published!

A minor suggestion is that you don't ship the LaTeX packages that are available on CTAN ("you ship it, you maintain it"), such as comment.sty and lineno.sty. You know tinytex can automatically install them if missing.

11

Exactly. The CTAN LaTeX packages are unnecessary for sharing the template. Thanks for the suggestion!

They might be useful if saved locally for personal use, though. If a co-author does not have these packages or tinytex installed, the missing .sty files could be annoying. The co-work of writing a manuscript might last one year or even longer, and the shipped .sty files could keep the output consistent and independent on the package update. It is the two sides of a coin.

Anyway, I had better remove the LaTeX packages from the bookdown template. I don't want to maintain it. Never.