CarboKitten-research-paper

A paper describing CarboKitten

The source files for the paper should be placed in md/, that is md/paper.md figures in md/fig, and references in md/ref.bib. The paper is written in Markdown, that is then compiled down to LaTeX and PDF using Pandoc. Any source files for the LaTeX (cls files for the Journal template mostly) should be placed in latex/, while Pandoc filters are placed in pandoc/.

Figures should be located in md/fig so that the Markdown renders reasonably well on Github.

Figures and example code should be evaluated by Julia, so there should be a Project.toml, Manifest.toml and src/jl/*.jl for scripts.

Code fragments in the paper should be evaluating to the given output. Something that should be enforced by using Entangled.

All figures should have source files available. If they were created in``` Inkscape, the SVG file is considered 'source' and placed in src/svg.

When the paper is published, a release of the package should be made and artifacts uploaded to Zenodo.

All actions should be available from a Makefile, even if we use brei to build figures from Entangled sources, and latexmk to build the eventual LaTeX. All generated output should appear in build/.

Prerequisites

Julia

Julia dependencies:

• CarboKitten what else to talk about
• CairoMakie for high quality plotting
• GraphvizDotLang for drawing graphs

Pandoc

Use Pandoc ≥ 3.1, compiled with Lua support. On Fedora:

dnf install pandoc

LaTeX

Use TeXLive ≥ 2023, building with LuaTeX and latexmk. On Fedora:

dnf install texlive-scheme-medium latexmk texlive-selnolig texlive-svg

Entangled

pip install entangled-cli

Or use the attached pyproject.toml with uv:

uv sync

which allows you to run entangled and brei through uv, for example:

uv run entangled tangle

GNU Make

Used to combine everything.

Markdown

Since we're using Pandoc, we can keep our Markdown clean. Any particular items can be given a CSS class or ID and then translated to LaTeX using a Pandoc filter.

A div (being a custom content block) can be marked as follows:

:::abstract
...
:::

In this example, we speak of an abstract-div, that is then translated to

\begin{abstract}
...
\end{abstract}

A similar thing can be done with spans.

[[email protected]]{.author-email}

See the Pandoc documentation.

Citations follow a syntax like @Bosscher1992, where Bosscher1992 is an entry in the md/ref.bib. There are other forms for citation translating to \citet or \citep in LaTeX, see Pandoc documentation.

Filters

• hide.lua hides blocks that are marked with :::hide. This is used to hide code blocks.

• fignos.lua and figref.lua number the figures and enable referencing those figures in the text. The label should be given at the end of the caption, which should be given as a paragraph following the image, starting with Figure: . Example:

• eqnos.lua makes equations numbered and allows cross referencing them.

• plain_tables.lua converts tables to \begin{table}...\end{table} environment in LaTeX. This is needed because the default behaviour is to create a longtable which doesn't work in 2-column mode.

• wide_figures.lua you can tag a figure with the {.wide} class, so that it will translate to a LaTeX figure* and a set width of \textwidth.

An example of this profile is shown in Figure @fig:wave-transport-magnitude.

![Depth profile](fig/wave-transport-magnitude.svg){.wide}

Figure: Depth profile of velocity and shear. The velocity profile was taylored to have a maximum of $10 \textrm{m}/\textrm{yr}$ at a depth of $20 \textrm{m}$. Where the shear is non-zero, there is a net accumulation of sediment. {#fig:wave-transport-magnitude}

Template

We use a modified version of the standard Pandoc template for LaTeX output. The copernicus document class and citation styles are shipped in the latex/copernicus directory. The template in latex/template.tex is configured to use the Geoscientific Model Development (gmd) format. To create a (single column) manuscript version, run make manuscript.

Debugging output

To debug the conversion from Markdown to LaTeX it is sometimes useful to look at Pandoc's abstract syntax tree directly. Pandoc can show this when using -t native. This can also run with make debug.