09-tidy-text.Rmd

# Tidy Text {#tidy-text}

We create interconnected, interoperable (web) resources: we want to ensure that our research results are findable, accessible, and reusable. The world wide web has been a source of high interoperability and findability in the last 30 years with the introduction of the http protocol and the standardization of the HTML text markup language.

```{r screenshot-post-source-code, echo=FALSE, message=FALSE, fig.cap="Our entire website is created from simple markdown text. See Chapter  [13](https://manual.dataobservatory.eu/publishing)." }
knitr::include_graphics(here::here('png', 'screenshot_post_source_code.png'))
```


All our output needs to be converted to HTML, but that does not mean that we need to work in an HTML editor.  However, the need of interoperability among operating systems (Windows, MacOs, Linux) and software packages (at least from Word, Libre, Google Docs to HTML, preferably to PDF, too) requires a simple, common notation.

Markdown is a much simplified HTML text notation intended to work well with word processors. 

```{r 09-markdownflowchart}
knitr::include_graphics(here::here("png", "markdown-flowchart.png"))
# https://mdg.imgix.net/assets/images/markdown-flowchart.png
```

Or, if you want Word output, then instead of HTML, Word is rendered. Or PDF. Or EPUB.

## Try it out {#try-markdown-1}

There are countless Markdown editors. Because Markdown is so simple, you can, if you want to, edit markdown files in Notepad, WordPad (Windows) or VIM (Linux).

Most word processors support markdown. For example, Google Docs has a [free extension](https://workspace.google.com/marketplace/app/docs_to_markdown/700168918607) that converts and document from Docs to markdown.

```{r trydiliger}
knitr::include_graphics(here::here("png", "dilliger_example.png"))
```
There are several online Markdown editors that you can use to try writing in Markdown. [Dillinger](https://dillinger.io/) is one of the best online Markdown editors. Just open the site and start typing in the left pane. A preview of the rendered document appears in the right pane.

### Communicate using Markdown

This is a course for new GitHub users.  You need to log into your (free) GitHub account to use it.

- **Who is this for**: New developers, new GitHub users, and students.
- **What you'll learn**: Use Markdown to add lists, images, and links in a comment or text file.
- **What you'll build**: We'll update a plain text file and add Markdown formatting, and you can use this file to start your own GitHub Pages site.
- **Prerequisites**: In this course you will work with pull requests as well as edit files. If these things aren't familiar to you, we recommend you take the [Introduction to GitHub](https://github.com/skills/introduction-to-github) course, first!
- **How long**: This course is five steps long and takes less than one hour to complete.

1. Right-click **Start course** and open the [link](https://github.com/skills/communicate-using-markdown/generate) in a new tab.

```{r start-course-button, results='asis'}
if (! knitr::is_latex_output()) {
  cat('<br />[![start-course](https://user-images.githubusercontent.com/1221423/218596841-0645fe1a-4aaf-4f51-9ab3-8aa2d3fdd487.svg)](https://github.com/skills/communicate-using-markdown/generate)')
}
```

   
2. In the new tab, follow the prompts to create a new repository.
   - For owner, choose your personal account or an organization to host the repository.
   - We recommend creating a public repository—private repositories will [use Actions minutes](https://docs.github.com/en/billing/managing-billing-for-github-actions/about-billing-for-github-actions).
   
```{r new-repo-course-name, echo=FALSE, message=FALSE}
knitr::include_graphics(here::here("png", "218594143-e60462b6-9f2a-4fa3-80de-063ac5429aab.png"))
```   

3. After your new repository is created, wait about 20 seconds, then refresh the page. Follow the step-by-step instructions in the new repository's README.


### Make it look good

You can simplify a Word document, for example, via uploading to Google Docs and sending it through the [free extension](https://workspace.google.com/marketplace/app/docs_to_markdown/700168918607) to get a markdown document. But usually you would like to work the other way around!  It is a better practice to write a text in markdown, and when ready, add it to a nice PDF, Word, or website (blog) HTML template. This way you keep your text (and citations) simple and interoperable, and you can reuse the same text many times over. 


## Markdown syntax

- [Basic Syntax](https://www.markdownguide.org/basic-syntax/)
- [Extended Syntax](https://www.markdownguide.org/extended-syntax/)


## Use your favorite application

Working with tidy texts will not separate you from your favourite word processor. You can still use Grammarly in Google Docs.  You only have to make sure that your text remains simple: you refrain from adding formatting to the document if they do not adhere to a common standard that connects Windows, Mac, Unix, Word, VIM, and Posit.

- [x] Simple text has clearly defined headings: title, subtitle, heading level 1, heading level 2, heading level 3.
- [x] Simple text has standardised bibliographic references and footnotes.
- [x] Simple text has standard section breaks and page breaks.
- [x] Simple text allows the automatic insertion of tidy data (as defined earlier) or interoperable graphics (preferably PNG or for web use webp).
- [x] Simple text uses only bold, italics, underline, and perhaps strikethrough highlighting.
- [ ] Simple text has no table of contents because the table of contents is automatically generated from headings.
- [ ] Simple text has no bibliography because it is automatically generated from standardized bibliographic entries.
- [ ] Simple text does not use footers, headers, watermarks, color boxes, because these things need to be added differently on Word, PDF, or HTML.