# Introduction

The package yamlme targets to write yaml-heads and even full r-markdown documents from plain R codes. The tasks of this package are the automatic generation of reports from R sessions as well as producing templates that can be shared as R-functions.

# Installing yamlme

To install this package from its GitHub repository, you can use the package devtools.

library(devtools)
install_github("kamapu/yamlme", build_vignettes = TRUE)

To start a new session, load the package:

library(yamlme)

# Writting yaml heads

Several internal funcions and classes are implemented in this package, while the only visible result will be produced by the function write_rmd(). Each entry in the yaml head can be provided as custom argument in this function, where at the moment four different categories are defined.

A vector of lentght 1 is the basing entry for a head, for instance:

my_document <- write_rmd(title = "My first document")
my_document
## ---
## title: My first document
## ---

Some applications may also require a description (or abstract) as in the case of documents rendered by distill. To add a description in post you start with a vertical line as first element in the vector.

my_document <- write_rmd(description = c("|",
"This text starts with a vertical line",
"and will be thus used as a description",
my_document
## ---
## description: |
##   This text starts with a vertical line
##   and will be thus used as a description
##   in the head.
## ---

A similar way is applied in the case of the entries for the element vignette in a vignette document, hier for convenience recycling the tile of the vignette.

the_title <- "Introduction to this package"
my_document <- write_rmd(
title = the_title,
vignette = c(">",
paste0("%\\VignetteIndexEntry{", the_title, "}"),
"%\\VignetteEngine{knitr::rmarkdown}",
"%\\VignetteEncoding{UTF-8}"))
my_document
## ---
## title: Introduction to this package
## vignette: >
##   %\VignetteIndexEntry{Introduction to this package}
##   %\VignetteEngine{knitr::rmarkdown}
##   %\VignetteEncoding{UTF-8}
## ---

A further class is used for entries starting with a dash symbol.

my_document <- write_rmd(author=c("- name: Miguel Alvarez",
"url: https://kamapu.github.io/",
"- name: Bisrat H. Gebrekhidan"))
my_document
## ---
## author:
##   - name: Miguel Alvarez
##     url: https://kamapu.github.io/
##   - name: Bisrat H. Gebrekhidan
## ---

And finaly, nested entries can be provided as lists.

my_document <- write_rmd(output=list(pdf_document="default"))
my_document
## ---
## output:
##   pdf_document: default
## ---

# A full example

With the function write_rmd() you can create a full r-markdown document. You cam either assign the result to an object or write it in a file, or both. For it, the parameters filename (name and path for the output file), body (body of the document as caracter vector), and append (appended blocks in yaml-head, for instance comments) are suitable.

my_document <- write_rmd(title = "Mi First Document", author = "My Name",
output = "html_document", append = "# This is a comment in head",
body = txt_body(
"# Starting a working day",
"",
"At the beginning of every day I will do:",
"",
"- Say everyone \"Good morning!\"",
"- Start the coffe mashine",
"- Start the computer",
my_document
## ---
## title: Mi First Document
## author: My Name
## output: html_document
## # This is a comment in head
## ---
##
## # Starting a working day
##
## At the beginning of every day I will do:
##
## - Say everyone "Good morning!"
## - Start the coffe mashine
## - Start the computer
## - Read mails

In this case we can render the document directly from the resulting object.

render_rmd(input = my_document, output_file = "my_document")

# Using the objects as template

The function update() can be used to modify settings and content in documents written by write_rmd().

my_template <- write_rmd(
title = "Example HTML document",
author = "My Self",
output = "html_document",
body = txt_body(
"# Introduction",
"",
"This is just an example."))
my_template
## ---
## title: Example HTML document
## author: My Self
## output: html_document
## ---
##
## # Introduction
##
## This is just an example.

We can also modify the template to adapt the output or the template of the document.

my_template <- update(my_template,
title = "Example PDF document",
output = "pdf_document",
append = "# this is a modified version")
my_template
## ---
## title: Example PDF document
## author: My Self
## output: pdf_document
## # this is a modified version---
##
## # Introduction
##
## This is just an example.