---
title: "Transcript Profiles"
author: "Oliver Ehmer"
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette:
    toc: true
    toc_float: false
    toc_depth: 2
vignette: >
  %\VignetteIndexEntry{Transcript Profiles}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

The print transcripts of `act` (`export_docx()`, `export_txt()`,
`search_cuts_printtranscript()`, `corpus_export()` and `helper_layout_render()`)
take their whole format from a **transcript profile**: line structure, speaker
acronyms, tier styles, character styles, the Word template and the settings of
the alignment engine. A profile is a JSON file.

```r
# profiles that can be found
act::helper_style_list()

# read one, with all values filled in
p <- act::helper_style_read("act")

# export with a profile: by name, by path, or as a list
act::export_docx(t, pathOutput = "out.docx", style = "act")
act::export_txt(t, style = "/path/to/my_profile.json")
act::export_txt(t, style = list(extends = "act", width = 80))
```

Without `style` the built-in profile `act` is used. Profiles are searched in
the folders of the option `act.style.folders` and in the folder
`extdata/styles` of the package; the first folder wins when two folders hold a
profile of the same name.

# Building on another profile

A profile can build on another one with `extends` and then only states what
differs. Single values replace those of the parent, the groups `acronym`,
`word`, `functions` and `advanced` are merged key by key, styles are merged by
their name.

```json
{
  "label": "Wide",
  "extends": "act",
  "width": 80,
  "acronym": { "width": 5 }
}
```

New styles of the child stand after the styles of the parent, so the more
special pattern of the child wins. `styles.order` gives the order explicitly,
`styles.remove` drops styles of the parent by name.

# Top-level values

| Key | Default | Meaning |
|---|---|---|
| `label` | | Name shown in lists. |
| `mode` | `"gat"` | `"gat"`: one block per annotation; `"mondada"`: score layout, turns are merged. |
| `header` | `true` | Write the header (preface, title, subtitle, info). |
| `width` | `65` | Line width in characters. |
| `width.limit` | `true` | `false`: no line breaks. |
| `space.lines` | `true` | Empty line between the blocks. |
| `line.numbers` | `true` | Number the lines of the main tiers. |
| `time.format` | | Time format of the source line; empty: option `act.time.format.transcript`. |

# Groups

**`acronym`** - the speaker sigle in front of each line: `show`,
`suppress.repeated` (no sigle when the same speaker goes on), `case`
(`""`, `"lower"`, `"upper"`, `"capitalize"`), `search` / `replace`, `extract`
(regular expression; the match is the sigle), `width` (characters) and
`ending` (text after the sigle, e.g. `":  "`).

**`word`** - `file`: the Word template (`.docx`); empty takes the file of the
option `act.style.template`, and if that is empty too the template of the
package. `look`: `"file"` takes the look of the styles from the Word file
and creates only styles that are missing there; `"profile"` writes the look of
the profile into every style.

**`functions`** - `tiers.exclude` and `tiers.keep` (regular expressions; kept
tiers stay although they match the exclude pattern), `arrow` and `arrow.shape`
(the mark of a search hit).

**`advanced`** - settings of the alignment engine:

| Key | Default | Meaning |
|---|---|---|
| `spaces.before` | `3` | Spaces before the line number. |
| `brackets.align` | `true` | Align overlap brackets of the verbal tiers. |
| `symbol.merge` | `true` | Fold adjacent identical multimodal marks. |
| `tolerance.point` | `0.2` | Seconds up to which two point marks count as the same moment. |
| `tolerance.gesture` | `0.5` | Seconds up to which two span marks count as the same moment. |
| `fill` | `"-"` | Filler inside a multimodal span. |
| `block.height` | `2` | Lines a rectangle mark may take. |
| `min.description` | `10` | Minimum room (characters) for a description before the verbal line breaks early. |
| `max.span.blocks` | `3` | Blocks a description may span before it is cut with a resume arrow. |
| `fig.replace` | `true` | Replace the content of picture tiers by a number mark. |

Which tiers are picture tiers and which are the catch-all multimodal tiers
(they align on the symbols of all other multimodal tiers) is not part of the
profile: the options `act.tier.stills.name.regex` and
`act.tier.multimodal.name.regex` hold these tier name patterns.

# Styles

`styles` is a list. Each style has a `name`, the name of the Word style
(`word`) and its look: `font`, `size`, `color`, `background` (`"#rrggbb"`),
`bold`, `italic`. There are three kinds.

**Styles with a role** carry the fixed parts of the transcript. `role` is one
of `normal`, `default` (every transcript line), `header.preface`,
`header.title`, `header.subtitle`, `header.info` and `space` (the empty lines
between blocks). Only these styles take `font` and `size`.

**Tier styles** (`"type": "tier"`) format the lines of the tiers whose name
matches `pattern`; when several match, the lowest one in the list wins
(general styles above, special ones below). They take font and size
from the style `default`, because a layer line is aligned to its main line
character by character.

| Key | Meaning |
|---|---|
| `pattern` | Regular expression on the tier name. |
| `tiers` | Instead of `pattern`: the name of a tier type of the option `act.tier.types` (a named vector type = pattern, e.g. set by `iclo::config()`); the pattern then comes from there. An unknown type stops with a message. A profile that builds on another one and gives its own `pattern` for such a style drops the inherited type. |
| `active` | `false` switches the style off. |
| `main` | The tier is a main (verbal) tier. |
| `line.numbers.suppress` | No line number. |
| `acronym` | Own acronym values (`suppress`, `case`, `search`, `replace`, `extract`, `width`, `ending`); what it leaves open comes from the profile. |
| `indent` | `"none"`, `"content"` (under the first character of the text), `"text"` (as `content`, skipping latching, brackets, pauses and the multimodal symbols), `"align"` (on the symbols of the main line). |
| `align.chars` | Symbols the layer aligns on (with `indent = "align"`). |
| `align.mode` | `"bracket"` (spans with open and close) or `"point"` (single spots). |
| `join` | Score mode (`mode = "mondada"`) only, for a layer without `align.chars` (translation, gloss): `true` prints the annotations of one turn that end on the same printed line as one text under that line, instead of one line each. |
| `join.separator` | With `join`: put between the parts (e.g. `","` gives `"one, two"`); empty means only a space. No separator after a part that already ends in punctuation. |

**Character styles** (`"type": "character"`) format parts of a line.
`applies` is `"symbols"` (the multimodal symbols of the layer tiers) or
`"pattern"` (the matches of `pattern`). With `from.layer` the symbols take
color, bold and italic of the layer line they belong to.
When two character styles match the same characters, the lower one wins.

```json
{
  "label": "With symbols",
  "extends": "act",
  "styles": [
    { "name": "Translation", "type": "tier", "pattern": "#trans", "word": "transcript_translation",
      "indent": "content", "line.numbers.suppress": true, "acronym": { "suppress": true }, "italic": true },
    { "name": "Symbols", "type": "character", "applies": "symbols", "word": "transcript_symbols",
      "color": "#595959" }
  ]
}
```

`helper_style_appearance()` lists the styles of a profile with the look that
finally holds for each, `helper_style_docx()` writes an empty Word file with
the styles of a profile, e.g. to use it as a template of your own.