The goal of aeolus is to fix Markdown files that have no semantic linebreaks. aEOLus, get it? 😉
You can install the development version of aeolus like so:
pak::pak("ropenscilabs/aeolus")For any Markdown parser the two following code chunks are the same:
This is a sentence. This is another
sentence.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/.
- You can start doing it manually and make it a habit.
- You can use RStudio IDE’s Visual Markdown editor with the correct
wrapping option:
- Either run
aeolus::use_sentence_linebreaks()for the current user (oruse_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”.
- Either run
- Open it with RStudio IDE’s Visual Markdown editor with the correct R Markdown options (see previous section), then save.
- Use aeolus.
This is a basic example which shows you how to solve a common problem:
library(aeolus)
markdown_file <- system.file("example.md", package = "aeolus")
readLines(markdown_file)#> [1] "This is a **sentence**."
#> [2] "This is another [sentence](https://github.com)."
#> [3] ""
#> [4] "In this paragraph I made random line breaks."
#> [5] "How annoying is it?!"
#> [6] ""
#> [7] "``` md"
#> [8] "This is a sentence. This is another"
#> [9] "sentence."
#> [10] "```"
#> [11] ""
#> [12] "This is a very long paragraph very very long without any breaks whatsoever which is sad, because who wants to get such a git diff."
#> [13] ""
#> [14] "1. thing"
#> [15] "2. other thing"
#> [16] ""
#> [17] "- item 1"
#> [18] "- item 2"
#> [19] "- item 3"
#> [20] ""
#> [21] "**What is wrong with bold text?** What?"
#> [22] ""
#> [23] "The [difference between working openly and transparently](https://wiki.mozilla.org/Working_open#Open_vs._Transparent)."
#> [24] ""
#> [25] "This is a footnote [^example-1]."
#> [26] ""
#> [27] "[^example-1]: Some more information."
unleash(markdown_file)
readLines(markdown_file)#> [1] "This is a **sentence**."
#> [2] "This is another [sentence](https://github.com)."
#> [3] ""
#> [4] "In this paragraph I made random line breaks."
#> [5] "How annoying is it?!"
#> [6] ""
#> [7] "```md"
#> [8] "This is a sentence. This is another"
#> [9] "sentence."
#> [10] "```"
#> [11] ""
#> [12] "This is a very long paragraph very very long without any breaks whatsoever which is sad, because who wants to get such a git diff."
#> [13] ""
#> [14] "1. thing"
#> [15] "2. other thing"
#> [16] ""
#> [17] "- item 1"
#> [18] "- item 2"
#> [19] "- item 3"
#> [20] ""
#> [21] "**What is wrong with bold text?**"
#> [22] "What?"
#> [23] ""
#> [24] "The [difference between working openly and transparently](https://wiki.mozilla.org/Working_open#Open_vs._Transparent)."
#> [25] ""
#> [26] "This is a footnote [^example-1]."
#> [27] ""
#> [28] "[^example-1]: Some more information."
#> [29] ""
#> [30] ""
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.
We recommend using aeolus together with version control and reviewing
changes carefully before committing them.