---
title: A Sample Article Using `quarto-ieee` for IEEE Journal and Transactions
format:
  ieee-pdf:
    keep-tex: true  
  ieee-html: default
author:
  - id: vplantev
    name: Valere Plantevin
    affiliations:
      - name: UQAC
        department: Laboratoire Prisme
        city: Saguenay
        country: Canada
    orcid: 0000-0000-0000-0000
    email: vplantev@uqac.ca
    attributes:
      corresponding: true
    bio: |
      Use `IEEEbiography`  with figure as  option and
      the author name as the argument followed by the biography text.
  - name: John Doe
    affiliations: 
      - name: Anonymous University
    bio: |
      Use `IEEEbiographynophoto` and the author name
      as the argument followed by the biography text.
    note: "Template created June 23, 2023; revised `r format(Sys.Date(),format='%B %d, %Y')`."
abstract: |
  This document describes the most common article elements and how to use the 
  `quarto-ieee` class with Pandoc/Quarto-Markdown to produce files that are
  suitable for submission to IEEE journals.  
  `quarto-ieee` can produce conference, journal, and technical note (correspondence) 
  papers with a suitable choice of class options. 
  It intends to generate PDF and HTML outputs that closely mimick what IEEE would generate.
keywords: [IEEE, IEEEtran, journal, Quarto, Pandoc, template]
#funding: 
funding: 
  statement: "The `quarto-ieee` template is freely available under the MIT license on github: <https://github.com/dfolio/quarto-ieee>."
pageheader:
  left: Journal XXX, Month Year
  right: 'D. Folio:  A Sample Article Using quarto-ieee'
bibliography: bibliography.bib
date: 2023-06-23
pdf: https://github.com/dfolio/quarto-ieee/blob/main/template.pdf
citation: 
  container-title: GitHUB
  page: 1-3
  type: software
  issued: 2023-06-23
  url: https://github.com/dfolio/quarto-ieee
  pdf-url: https://github.com/dfolio/quarto-ieee/template.pdf
---

# Introduction {#sec-intro}

[T]{.IEEEPARstart}[his]{}
file is intended to serve as a "sample article file"
for IEEE journal papers produced with (Pandoc/Quarto)-Markdown using `IEEEtran.cls` version 1.8b and later for the PDF output. 
It is based on `bare_jrnl_new_sample4.tex` provided by IEEE Publication Technology, Staff and available from  <https://template-selector.ieee.org/>.
The most common elements are covered in the simplified and updated instructions in `New_IEEEtran_how-to.pdf`.
For less common elements you can refer back to the original `IEEEtran_HOWTO.pdf`. 
It is assumed that the reader has a basic working knowledge of {{< latex >}} @mittelbach2023latex and of (Pandoc/Quarto)-Markdown [@MacFarlane_Pandoc; @Allaire_Quarto_2022] markup.


# The Design, Intent, and Limitations of this Templates

The `quarto-ieee` template is intended to **approximate the final look and page length of the articles/papers** either in PDF output or HTML output. 
**They are NOT intended to be the final produced work that is displayed in print or on IEEEXplore^®^**.
They will help to give the authors an approximation of the number of pages and layout that will be in the final version. 

## Unsuported feature and limitations
Although most of the {{< latex >}} and `IEEEtran.cls` commands and environment are supported, 
there are some limitations when trying to export to a format other than PDF  (e.g. HTML output).
For PDF output, the reader can use the {{< latex >}} command directly. However, this may break other output formats.
\
It can be can reported the following limitations of the  `quarto-ieee` template:
- Several authors with same affiliation produce weird output. 
  In such case, it is recommended to use `note` and `tex-author-no-affiliation: true`.
- For `PDF` output
  - `quarto-ieee` use a hack to handle the `longtable` issue with  2-column {{< latex >}} documents[^issues-1023].
    But, in some cases, a page overflow may occur (see also @sec-tables).
- For `HTML` output
  - The default Quarto toc is used, so the table of contents (toc) display is not the same as on [IEEEXplore<sup>®</sup>].
  - Footnote are put at the end of document, while on [IEEEXplore<sup>®</sup>] there are placed in the accordion.
  - Figures are not placed in the accordion.
  - [IEEEXplore<sup>®</sup>] specifics (e.g. citation metrics, etc.)
  - The `HTML` output is a  Quarto citeable article @quarto-citation, so a citation appendix is automatically added to the article end.
  

## Contributing

If you want to improve the `quarto-ieee` template or need some specific features do not hesitate to submit Pull Request[^PR] (it is considered good practice to open an issue for discussion before working on a pull request for a new feature).

[^PR]: Go to the PR page: <https://github.com/dfolio/quarto-ieee/pulls>


# Some random text
For some of the remainder of this sample we will use dummy text to fill out paragraphs rather than use live text that may violate a copyright.
\IEEEpubidadjcol\
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis cursus nisl eget tempor porta. Proin dapibus dictum quam a commodo. Mauris congue scelerisque eros a porta. Proin blandit nulla sapien, et pretium justo dictum non. Vivamus ultricies, elit eu posuere placerat, sapien est condimentum nisl, at tincidunt tortor dolor ac ligula. Suspendisse pulvinar libero quis eros finibus sodales. Vivamus mattis est eget imperdiet luctus. Morbi eget posuere metus. Nam egestas elit lectus, eu tincidunt odio viverra sed. Sed sit amet metus rutrum, ultricies elit in, finibus felis. Integer lobortis dui ante, eget placerat lorem laoreet eu.

Nullam mi ligula, luctus a orci ut, tincidunt varius augue. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia curae; Donec sed sem risus. Nam eleifend ultrices elit, vitae posuere tellus interdum et. Nam id nisl at elit malesuada malesuada. Suspendisse viverra ipsum libero, vel pharetra sem maximus sed. Nunc vel est fringilla, rutrum diam eu, egestas quam. Vivamus lobortis blandit velit, commodo finibus mauris. Quisque vel lacus ipsum. Pellentesque quis nulla ipsum.

Aenean in hendrerit quam. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Aliquam tincidunt vehicula dignissim. In quis aliquet lectus, ac vestibulum elit. Quisque a magna viverra quam viverra faucibus. Nulla ornare tortor at mollis viverra. Curabitur vel porta dui. Etiam ipsum elit, egestas eget lacus nec, laoreet iaculis lacus. In iaculis risus ac tincidunt viverra. Maecenas tempor iaculis odio quis aliquet.
\
Maecenas ac posuere turpis. Fusce est dui, dapibus sed odio eget, eleifend facilisis felis. Nam gravida varius enim, ornare tincidunt urna ullamcorper ut. Donec sit amet eros ac lacus placerat rutrum ut non dolor. Nulla tincidunt nunc massa, sed euismod dui feugiat vitae. Integer tempus risus rutrum tellus interdum, eu aliquet sapien rutrum. Nunc feugiat varius lacus sed laoreet. Integer euismod tellus nisi, id scelerisque sem sagittis eu. Suspendisse at orci vel neque varius tempor nec vitae odio. Integer elementum elementum fermentum. Morbi in turpis cursus, lacinia arcu et, semper orci.

# Front matter

Most Quarto's authors and affiliations schemes  @quarto-funding are supported in the YAML front matter to render authors as requested by IEEE journals in PDF and HTML outputs.
When provided to an author, the `note` entry is rendered as a `\thanks{}` in `PDF` output (ignored in `HTML` output).
Additionally, the reader may add to an author a `photo: path/to/photograph.png` with a `bio` metadata entries to generate a `IEEEbiography`, while a sole `bio` generates a `IEEEbiographynophoto` (these features is used both in `PDF` and `HTML` outputs).
\
The `funding` entry is also used in both PDF and HTML outputs @quarto-funding.
At version v1.1.1, only the `funding.statement` is used.
Similarly, `citation` entry is supported to make the HTML output a "_citeable article_" @quarto-citation.

 
# Some Common Elements
## Sections and Subsections
As stated in the `IEEEtran` template enumeration of section headings is desirable, but not required.
When numbered, it should be consistent throughout the article, that is, all headings and all levels of section headings in the article should be enumerated. 
Primary headings are designated with Roman numerals, secondary with capital letters, tertiary with Arabic numbers; and quaternary with lowercase letters. 
References and Acknowledgment headings are unlike all other section headings in text. 
They are never enumerated. 
They are simply primary headings without labels, regardless of whether the other headings in the article are enumerated. 

The following @sec-Markdown shows some basic usage and capabilities of `quarto-ieee`.

## Markdown basics {#sec-Markdown}
The reader can easily find many documentations on how to write using the (Pandoc/Quarto) Markdown syntax.
The `quarto-ieee` template relies mainly on the Markdown markup supported by Quarto @quarto-markdown, which is build based on Pandoc [@MacFarlane_Pandoc; @Allaire_Quarto_2022].
Below are some basic examples of usage of the Markdown markup (to save space, it is better to consult the original Quarto document `template.qmd`).


### Display equations
To write equations use `$` delimiters for inline formula or `$$` for block one.
To number the equations, it is recommended to use classic equation environments 
provided by {{< latex >}} and to use `\eqref{}` (or `\ref{}`) for cross-referencing.
For example:
\begin{equation}\label{eq:1}
{{\chi}_a}=\text{diag}\left(\frac{{\chi}}{1+n_a{\chi}},\frac{{\chi}}{1+n_b{\chi}},\frac{{\chi}}{1+n_b{\chi}}\right),
\end{equation}
\begin{align}
a & = b + c \label{eq:2} \\
c & = d + e \label{eq:3}
\end{align}

\begin{equation}\label{eq:4}
\begin{cases}
    1&=n_a+2n_b \\
    n_a&=\dfrac{1-{\varepsilon}^2}{2{\varepsilon}^3}\left(\log\left(\dfrac{1+{\varepsilon}}{1-{\varepsilon}}\right)-2{\varepsilon}\right)
\end{cases}
\end{equation}
The above equation is cross-referenced as \eqref{eq:1}, \eqref{eq:2}, \eqref{eq:3} and \eqref{eq:4}.

For now, avoid using the Quarto cross-references that use of `$$ $$` with `#eq-` label.
It works properly only for PDF output, but there are some issues with HTML[^issues-2275] output.


::: {.remark}
`quarto-ieee` template also supports the [`mhchem`](https://ctan.org/pkg/mhchem) (for chemical equation) 
and [`physics`](https://ctan.org/pkg/physics) (for flexible macros for typesetting equations) {{< latex >}} packages 
and [Mathjax extensions](https://docs.mathjax.org/en/latest/input/tex/extensions/index.html).
:::

### Theorems, Proofs and Remarks
To include a reference-able theorem, create a div with a `#thm-` label.
A theorem name is specified  via the first heading in the block. 
For example:

::: {#thm-line}

## Line

The equation of any straight line, called a linear equation, can be written as:

$$
y = mx + b
$$
:::

The theorem is cross-referenced as @thm-line.


There are a number of theorem variations supported by [Quarto](https://quarto.org/docs/authoring/cross-references.html#theorems-and-proofs), each with their own label prefix:

- `#thm-` for Theorem;
- `#lem-` for Lemma;
- `#cor-` for Corollary
- `#prp-` for Proposition;
- `#cnj-` for Conjecture;
- `#def-` for Definition;
- `#exm-` for Example;
- `#exr-` for Exercise.


The `proof`, `remark` and `solution` environments generally receive similar typesetting as theorems.
However they are not numbered (and therefore cannot be cross-referenced). To create these environments just use them as the class name of a div such as:

::: {.solution name="The solution"}
An example of solution environment.
:::



### Figures
An image with nonempty alt text will be rendered as a figure with a caption with Pandoc and Quarto.
Quarto includes a different features to simplify the use of figures and subfigures.
Here, it is recommended to use div block with `#fig-` label to embed your Figures.


:::{#fig-1}
![](fig1.png){width="30%"}

An example of figure.
:::


:::{#fig-2  layout-ncol=2}
![ ](fig1.png){#fig-2a}

![ ](fig1.png){#fig-2b}

An example with sub-figure.
:::


The figures is cross-referenced as @fig-2  and even the sub-figures as @fig-2b.

### Tables {#sec-tables}

Similarly, many kind of tables may be used with Pandoc and Quarto.
The latter also includes different features to simplify the table output.
To make tables cross-referenceable use a label with a `#tbl-` prefix. 
\
However, it is recommended to avoid using the commonly used single Markdown table known as a 'pipe table'. 
In fact, Pandoc Markdown uses the {{< latex >}} `longtable` package, which does not support the two-column mode, which is required for most `IEEEtran` journals.
`quarto-ieee` uses a hack to temporarily switch to one-column mode. 
However, this hack may break the page layout.
To overcome this issue, a basic way is to use code cells (as for @tbl-other).
Quarto is a multi-language and it uses  `Knitr` to execute `R` code and can execute  Python code blocks within Markdown.

::: {#tbl-panel layout-ncol=2}
| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

: First Table {#tbl-first}

| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | C    |
| E    | F    | G    |
| A    | G    | G    |

: Second Table {#tbl-second}

Main Caption 
:::

The Tables are cross-referenced as @tbl-panel for details, especially @tbl-second.
There is also @tbl-other.

## Bibliography

IEEE journal should normally use IEEEtran[^bibtex] {{< bibtex >}} style.
Nevertheless, Pandoc and Quarto do support {{< bibtex >}} with natbib or biblatex. However, neither is officially recommended for normal IEEE use.
For this reason, `quarto-ieee` uses `citeproc` with the `ieee` CSL style sheet.

[^bibtex]: IEEEtran BibTeX  style support  page is: <http://www.michaelshell.org/tex/ieeetran/bibtex/>


# Conclusions
The conclusion goes here.

# Acknowledgment {-}
This should be a simple paragraph before the References to
thank those individuals and institutions who have supported
your work on this article.


[]{.appendix options="An Appendix"}


Use `[]{.appendix options="An Appendix"}` markup if you have a single appendix.
`IEEEtran` state that to do not use `\section{}` anymore after `\appendix`.



::: {.content-visible when-format="pdf"}
# References {-}
:::



[^issues-1023]: ["_[longtable not compatible with 2-column LaTeX documents](https://github.com/jgm/pandoc/issues/1023>)_", 

[^issues-2275]: See the issue here <https://github.com/quarto-dev/quarto-cli/issues/2275>

[IEEEXplore<sup>®</sup>]: <https://ieeexplore.ieee.org/>
