---
title: pinp is not PNAS

# Use letters 'a', 'b', ... or digits '1', '2', ... for different
# affiliations and addresses. Use '~' or '""' to suppress the
# display of the affiliation and address.
author:
  - name: Dirk Eddelbuettel
    affiliation: a
  - name: James Joseph Balamuta
    affiliation: a
address:
  - code: a
    address: University of Illinois at Urbana-Champaign; Champaign, IL, USA

# Optional: line of arbitrary text with additional information.
# Could be used, for example, to mention the bibliographic info in a post-print.
# If not specified, defaults to "This version was compiled on \today"
#date_subtitle: Published in *Journal of Statistical Software*, 2018

# For footer text  TODO(fold into template, allow free form two-authors)
lead_author_surname: Eddelbuettel and Balamuta

# Place DOI URL or CRAN Package URL here
doi_footer: "https://cran.r-project.org/package=pinp"

# Abstract
abstract: |
  This short vignette details several of the available options for the `pinp` pdf vignette template. 

# Optional: Acknowledgements
acknowledgements: |
   We gratefully acknowledge all the help from the
   [rticles](https://cran.r-project.org/package=rticles) package
   \citep{CRAN:rticles} which not only introduced us to the powerful
   [PNAS LaTeX](http://www.pnas.org/site/authors/latex.xhtml) style
   class, but also provided useful code templates to study in the
   other mode as the fine macros. The [pandoc](http://pandoc.org)
   document converter \citep{pandoc} is the much-admired driving force
   behind the document manipulation.

# Optional: One or more keywords
#keywords:
#  - pdf
#  - vignette

# Paper size for the document, values of letter and a4
papersize: letter

# Font size of the document, values of 9pt (default), 10pt, 11pt and 12pt
fontsize: 9pt

# Optional: Force one-column layout, default is two-column
#one_column: true

# Optional: Enables lineo mode, but only if one_column mode is also true
#lineno: true

# Optional: Enable one-sided layout, default is two-sided
#one_sided: true

# Optional: Enable section numbering, default is unnumbered
numbersections: true

# Optional: Specify the depth of section number, default is 5
secnumdepth: 3

# Optional: Bibliography 
#bibliography: pinp

# Optional: include-after
#include-after: somefile.tex

# Optional: Skip inserting final break between acknowledgements, default is false
skip_final_break: true

# Customize footer, eg by referencing the vignette
footer_contents: "pinp Vignette"

# Optional: Enable a 'Draft' watermark on the document
#watermark: true

# Produce a pinp document
# 
# Other options that can be set here, shown with their defaults
#   keep_tex: TRUE
#   collapse: FALSE
#   citation_package: natbib
#
# Any other arguments to rmarkdown::pdf_document could be set 
# here as well
#
output:
  pinp::pinp:
    includes:
      after_body: bib.tex


# Required: Vignette metadata for inclusion in a package.
vignette: >
  %\VignetteIndexEntry{Introduction to pinp}
  %\VignetteKeywords{pinp,vignette}
  %\VignettePackage{pinp}
  %\VignetteEngine{knitr::rmarkdown}

---

# Introduction 

The *pinp is not PNAS* template extends and reworks the
[pnas_article](https://github.com/rstudio/rticles/tree/master/inst/rmarkdown/templates/pnas)
template from the wonderful
[rticles](https://cran.r-project.org/package=rticles) package. 
This vignette aims to list all the available option in order to
provide both a reference documentation, and a simple introduction.
The source of this vignette is of course included in the package
itself.


# YAML Content 

## `author`

Fields `name` and `affiliation` must be given. The latter can be a
single-letter index referring to the address field described in the
next paragraph.

## `address`

Fields `code` (referring to the index from `affiliation`) and
`address` must be given. The latter is free-form, and may include
`\url{}` and other LaTeX macros.

## `lead_author_surnames`

A free-form field usable for either a simple "Author _et al_", or a
simple text field listing two or more authors. This field is not
post-processed.

## `doi_footer`

A free-form URL for a doi reference for a publication, or a canonical
URL for a software package or repository. These are typeset as actual
URLs and resolve their links from the pdf document following standard
LaTeX practice.

## `abstract`

A short free-form abstract can be used to inform the reader of the
essence of the subsequent document.

## `acknowledgements`

An _optional_ free-form text which will be typset at the very end
of the document right before the (optional also) references.

## `keywords`

An optional list (entered as a YAML list following `-` marks) which will be typeset as a list of alternatives separated by vertical _pipe_ symbols.



# Options 

## `fontsize` 

Default it 9pt, also supported are 10pt, 11pt and 12pt which may make
sense in one-column mode. 

## `one_column` 

An _optional_ override (using value `true`) for the default two-column
layout. Useful for initial stages of a document, as well as for
documents with wide-format tables and figures.

## `lineno` 

An _optional_ selection (via value `true`) of line numbers,
selectable only if `one_column: true` is set.  Currently typesets
number on both the left and right-hand side which seems in error.

## `one_sided`

An _optional_ selection (via value `true`) of one-sided rather than
two-sided output. This should probably alter the footnote but does not
currently do so.

## `numbersections`

An _optional_ selection (via value `true`) for overriding the default
unnumbered section headers. Useful if you need to refer to sections by number.

## `secnumdepth`

An _optional_ selection (via values 1, 2, 3, ...) of section numbering depth,
selectable only if `numbersections: true` is set.  Useful if you only want
to number sections and subsections but not subsubsections and so on.

## `skip_final_break`

An _optional_ selection (via value `true`) that avoids inserting a `\pnasbreak`
at the end of the document. This is useful when dealing with float issues that
may appear at the end of documents with acknowledgements and bibliographies.

## `bibliography`

A field for an _optional_ selection of a Bibtex input file, extension
can be omitted.  Alternative, bibliographic information may also be
included directly as a `thebibliography` environment by including the
content of the generated `bbl` file. The `after_body` include of the
YAML header can also be used.

## `watermark`

An _optional_ selection of a 'Draft' watermark drawn across the center
of the page (using value `true`). Note that figures may be plotted
above the watermark.

## `footer_contents`

An character value delimited by quotes for something like _"mypackage
Vignette"_ which will be shown in the footer.

## `date_subtitle`

An _optional_ free-form text string. Could be used, for example, to
mention the bibliographic info in a post-print. If not specified,
defaults to "This version was compiled on {current date}"

## `document_date`
An _optional_ free-form text string designed to specify the date of the document. It can be useful for example to specify the exact date of the publication in a post-print. If not specified, defaults to the current date.


# Code 

## Knitr

The [knitr](https://cran.r-project.org/package=pinp) package
\citep{CRAN:knitr} is also available to both typeset code, typically
in R or one of the other supported engines.  Knitr segments used three
backticks (just like Pandoc described below) followed by curly brace
sgement listing first the desired engine, and then the selected
display options. Output from the code can also be shown, and a myriad
of options permit many variants.

```{r}
a <- 2 + 2
a
```

Output from such code blocks is also shown in a framed and shaded box.
Code segments containing plots producing figures results in these
figures being automatically inlined:
 

```{r}
set.seed(42)
par(mar=c(3,3,3,0))
plot(cumsum(rnorm(100)), type='l',
     main="Up and and away")
```

## Pandoc

The easiest way to typeset code is to simply open three backticks
followed by the name of one of the _numerous_ built-in pandoc parsers, 
_i.e._, \verb|```c| to typeset in the C languags.

```c
/* this is a C function example */
int doubleMe(int x) {
    return x + x;          
}
```

Pandoc segments are highlighted as usual, and per a convention in this
template also shown in a framed and slightly shaded box as seen here and
above.

Another example from Python:

```py
# A Python example
def printSomething(str):
   "This prints the string passed in"
   print str
   
```


# Environments 

## Standard LaTeX

All standard LaTeX environment are directly usable if needed,
including of course all mathematical environments and symbols such as,
say, the greek lettering: $\alpha$, $\beta$, $\gamma$, and so on.

The following is set as usual via the `displaymath` environment:

\begin{displaymath}
    a^2 = b^2 + c^2
\end{displaymath}

## figure*

Figure can span two columns (when the default two-column mode is used)
by using a (LaTeX) `\begin{figure*} ... \end{figure*\it}` environment, .
Figures will then be _floats_ in the LaTeX sense and place at the top
or bottom of the page.  An example is given by the skeleton document
of the package. Similarly, `\begin{figure*} ... \end{figure*}` could
be used around a wide table structure.

## widetext

The `\begin{widetext} ... \end{widetext}` environment can be used to
break text from two-column mode to one-column mode and back. As of the
2018 release of the underlying PNAS macros, this feature is deprecated
upstream. But both the `figure*` and `table*` environments work, as 
does relying on \LaTeX commands `\onecolumn` and `\twocolumn`.



# Other Help 

## RMarkdown 

The [rmarkdown site](https://rmarkdown.rstudio.com/) by RStudio is very
comprehensive and can answer many questions pertaining to Markdown
processing in R using the
[rmarkdown package](https://cran.r-project.org/package=rmarkdown).


## LaTeX 

Ultimately, this style uses LaTeX to produce the pdf output. The
[tex StackExchange](https://tex.stackexchange.com) can be very helpful for
specific LaTeX questions.

<!-- Acknowledgements, and References, are automatically typeset after this -->
