first commit
This commit is contained in:
Valère Plantevin
304
ieee_template.qmd
Normal file
304
ieee_template.qmd
Normal file
@@ -0,0 +1,304 @@
|
||||
---
|
||||
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}
|
||||
{width="30%"}
|
||||
|
||||
An example of figure.
|
||||
:::
|
||||
|
||||
|
||||
:::{#fig-2 layout-ncol=2}
|
||||
{#fig-2a}
|
||||
|
||||
{#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/>
|
||||
Reference in New Issue
Block a user