---
title: "Introduction to the Reproducible Open Coding Kit (ROCK)"
author: "Gjalt-Jorn Peters & Szilvia Zörgő"
date: "`r Sys.Date()`"
output:
  pdf_document:
    toc: false
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Introduction to the Reproducible Open Coding Kit (ROCK)}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
  %\usepackage[utf8]{inputenc}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The Reproducible Open Coding Kit (ROCK) was developed to facilitate reproducible and open coding, specifically geared towards qualitative research methods. It was designed to be a standard that realized coded qualitative data that is simultaneously human- and machine-readable, similar to the spirit of Markdown and YAML.

To code something with the ROCK, add the code to the line your want to code, in between two pairs of square brackets:

```
Some example text,
and some more.       [[look_a_code]]
And the end.
```

-----

The `{rock}` package can parse sources like this, and then allows you to do what you can do with conventional (often proprietary) software for qualitative analysis. For example, it can prettify the source to be displayed like this: ^[Note that this uses HTML and so isn't visible in the PDF version of this vignette.]

-----

```{r, echo=FALSE, results='asis'}
exampleROCK <-
  rock::as.rock_source(c(
    "Some example text,",
    "and some more.       [[look_a_code]]",
    "And the end."));
rock::prettify_source(
  exampleROCK
);
```

-----

Here, you can quickly recognize the code, which has been placed in a blue block.

The ROCK standard supports a number of types of codes, attributes, comments, and other things. Below, you can see a prettified example source that shows many of these.

Codes in a flat or hierarchical organizational mode are in blue blocks again; value codes (for magnitude coding) are in yellow blocks; and class instance identifiers are in pink blocks. Utterance identifiers are in grey blocks (see [rock::prepend_ids_to_source()]), section breaks (used for segmentation) have a light blue/purplish background. Finally, embedded YAML chunks have a green background.

-----

```{r, echo=FALSE, results='asis'}
rock::prettify_source(
  system.file(
    "extdata", "example-1.rock",
    package="rock"
  )
);
```

-----

A more extensive introduction is available in the blog post at [https://sciencer.eu/posts/2024-12-rock-basics.html](https://sciencer.eu/posts/2024-12-rock-basics.html). In addition, the ROCK website, [https://rock.science](https://rock.science), links to a number of tutorials and workshops.
