README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# aeolus

<!-- badges: start -->
[![R-CMD-check](https://github.com/maelle/aeolus/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/maelle/aeolus/actions/workflows/R-CMD-check.yaml)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- badges: end -->

The goal of aeolus is to fix Markdown files that have no semantic linebreaks.
aEOLus, get it? :wink:

## Installation

You can install the development version of aeolus like so:

``` r
pak::pak("ropenscilabs/aeolus")
```

## Why have semantic linebreaks?

For any Markdown parser the two following code chunks are the same:

```md
This is a sentence. This is another
sentence.
```

```md
This is a sentence. 
This is another sentence.
```

However, the second one will make your work easier when you use version control.
Git treats code by **line** so if lines are logical units as opposed to random units
or units of a certain length, 
the Git diff is better. 

If you change one sentence in a paragraph, and that paragraph is a single line, 
the Git diff is less readable.

With semantic linebreaks, code suggestions in GitHub Pull Requests are easier to make and use.

More information: <https://sembr.org/>.

## How to add linebreaks at the end of sentences?

1. You can start doing it manually and make it a habit.
1. You can use RStudio IDE's Visual Markdown editor with the correct wrapping option:
    - Either run `aeolus::use_sentence_linebreaks()` for the current user (or `use_sentence_linebreaks("project")` for the current project);
    - Or, manually in the project/global options, choose "sentence" as value for "Automatic text wrapping (line breaks)" under "R Markdown".

## How to fix a file that has no linebreaks at the end of sentences?

1. Open it with RStudio IDE's Visual Markdown editor with the correct R Markdown options (see previous section), then save.
1. Use aeolus.

## Example

This is a basic example which shows you how to solve a common problem:

```{r example}
library(aeolus)
markdown_file <- system.file("example.md", package = "aeolus")
readLines(markdown_file)
unleash(markdown_file)
readLines(markdown_file)
```

## Caveats

`aeolus::unleash()` uses the tinkr package under the hood, which means it suffers from the same limitations: for instance, files after editing only use "-", not "*", for lists.
Refer to [tinkr documentation](https://docs.ropensci.org/tinkr/#loss-of-markdown-style).
We recommend using aeolus together with version control and reviewing changes carefully before committing them.