From ebd3504cb71ba99d52aa69f3eb6f9ea7c81b7463 Mon Sep 17 00:00:00 2001
From: James J Balamuta <coatless@users.noreply.github.com>
Date: Mon, 13 Nov 2023 18:37:56 -0700
Subject: [PATCH] Re-align vignettes (#61)

* Refocus vignette on solving linear regression and remove package use

* Improve the package usage note
---
 vignettes/package-usage.Rmd       | 42 +++++++++++++++++++++++++++++++
 vignettes/using-rcppensmallen.Rmd | 32 ++++-------------------
 2 files changed, 47 insertions(+), 27 deletions(-)
 create mode 100644 vignettes/package-usage.Rmd

diff --git a/vignettes/package-usage.Rmd b/vignettes/package-usage.Rmd
new file mode 100644
index 0000000..fab70e2
--- /dev/null
+++ b/vignettes/package-usage.Rmd
@@ -0,0 +1,42 @@
+---
+title: "Using RcppEnsmallen in Your Own R Package"
+author: James Joseph Balamuta
+abstract: |
+  This vignette describes the best practices for using RcppEnsmallen in your
+  own R package.
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Using RcppEnsmallen in Your Own R Package}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+# Overview
+
+RcppEnsmallen is best used within an _R_ package. 
+The setup for `RcppEnsmallen`'s use mirrors that of other `Rcpp`-based projects.
+In particular, the `DESCRIPTION` file requires the `LinkingTo` field and
+two files inside the `src/` to establish the necessary compilation options.
+In the next two sections, we show the modifications. 
+
+## DESCRIPTION file
+
+Open your R package's `DESCRIPTION` file. Ensure that the `LinkingTo` directive
+is present and contains:
+
+```bash
+LinkingTo: Rcpp, RcppArmadillo (>= 0.9.800.0.0), RcppEnsmallen (>= 0.2.20.0.1)
+```
+
+## Makevars inside the src/ Directory 
+
+Next, the `src/` directory must contain both a `Makevars` and `Makevars.win` 
+file. Each file must have the same contents of:
+
+```bash
+PKG_CXXFLAGS = $(SHLIB_OPENMP_CXXFLAGS)
+PKG_LIBS = $(SHLIB_OPENMP_CXXFLAGS) $(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS)
+```
+
+The `Makevars.win` file provides the appropriate configuration for Windows
+while `Makevars` acts on Unix-alike systems like macOS, Linux, and Solaris.
diff --git a/vignettes/using-rcppensmallen.Rmd b/vignettes/using-rcppensmallen.Rmd
index 6c7f448..ec0d608 100644
--- a/vignettes/using-rcppensmallen.Rmd
+++ b/vignettes/using-rcppensmallen.Rmd
@@ -1,12 +1,12 @@
 ---
-title: "Using RcppEnsmallen"
+title: "Solving Linear Regression using Numeric Optimization"
 author: James Joseph Balamuta and Dirk Eddelbuettel
 abstract: |
-  Contained within are examples related to using RcppEnsmallen in everyday 
-  work alongside of creating an _R_ package with it. 
+  In this vignette, we describe how to use RcppEnsmallen in a standalone 
+  C++ file. 
 output: rmarkdown::html_vignette
 vignette: >
-  %\VignetteIndexEntry{Using RcppEnsmallen}
+  %\VignetteIndexEntry{Solving Linear Regression using Numeric Optimization}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---
@@ -45,7 +45,7 @@ $$RSS\left( \beta \right) = \left( { \mathbf{y} - \mathbf{X} \beta } \right)^{\t
 
 The objective function we wish to minimize would be defined as:
 
-$$f(\beta) = \rVert y - X\beta\lVert_2$$
+$$f(\beta) = \rVert \mathbf{y} - \mathbf{X}\beta\lVert_2$$
 
 The gradient is defined as:
 
@@ -185,25 +185,3 @@ rownames(compare_coefs) = paste0("Beta", seq_len(nrow(compare_coefs)))
 knitr::kable(compare_coefs, longtable = FALSE, caption = "Comparison of Estimated Coefficients")
 ```
 
-# Package Usage
-
-RcppEnsmallen is best used within an _R_ package. The setup for `RcppEnsmallen`'s
-use mirrors that of other `Rcpp`-based projects. In particular, the
-`DESCRIPTION` file requires the `LinkingTo` field to contain:
-
-```bash
-LinkingTo: Rcpp, RcppArmadillo (>= 0.9.800.0.0), RcppEnsmallen (>= 0.2.18.0.1)
-```
-
-Next, the `src/` directory must contain both a `Makevars` and `Makevars.win` 
-file with:
-
-```bash
-CXX_STD = CXX11
-PKG_CXXFLAGS = $(SHLIB_OPENMP_CXXFLAGS)
-PKG_LIBS = $(SHLIB_OPENMP_CXXFLAGS) $(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS)
-```
-
-The `Makevars.win` file provides the appropriate configuration for Windows
-while `Makevars` acts on Unix-alike systems like macOS, Linux, and Solaris.
-