%\VignetteIndexEntry{Overview of Utilities in the pkgmaker Package}
%\VignetteDepends{knitr,bibtex}
%\VignetteCompiler{knitr}
%\VignetteEngine{knitr::knitr}
 
\documentclass[a4paper]{article}
\usepackage[colorlinks]{hyperref} % for hyperlinks
\usepackage{a4wide}
\usepackage{xspace}
\usepackage[all]{hypcap} % for linking to the top of the figures or tables

% add preamble from pkgmaker
<<pkgmaker_preamble, message = FALSE, echo=FALSE, results='asis'>>=
library(pkgmaker)
pkgmaker::latex_preamble()
@

\title{Overview of Utilities in the pkgmaker Package\\
\small Version \Sexpr{utils::packageVersion('pkgmaker')}}
\author{Renaud Gaujoux}

\begin{document}

\maketitle

\section{Knitr hooks}

\subsection{hook\_try: showing error message in try statements}

This hooks aims at showing the error message generated by \code{try}
blocks, which are otherwise not shown in the generated document.

\subsubsection*{Hook registration}
<<hook_try>>=
library(knitr)
knit_hooks$set(try = pkgmaker::hook_try)
@

\subsubsection*{Usage}
<<without_try>>=
try( stop('this error will not appear in the document'))
@

Using chunk option \code{try = TRUE}, the error message is shown in the
document:
<<with_try, try = NA>>=
txt <- 'this error will be shown'
try( stop(txt) )
@

Note that by default, the error message is not highlighted by \code{knitr} as an
error but only as a normal message.
This is because highlighting apparently relies on an actual error signal
condition being raised, which in turn makes the package building process \code{R CMD build} fail.
However, it is still possible to hightlight the error when generating a document
outside a package, by using the chunk option \code{try = FALSE}:

<<with_try_highlight, try = TRUE>>=
txt <- 'this error will be shown'
try( stop(txt) )
@

\pagebreak 
\section{Session Info}
<<sessionInfo, echo=FALSE, results='asis'>>=
toLatex(sessionInfo())
@

\end{document}