Author: Mariana Montes
Date: 2024-05-19

# Styling glosses

#### Mariana Montes

#### 2024-05-19

Users of glossr can configure certain styling parameters in different ways. From version 0.8.0, next to the `styling` argument of `use_glossr()`, users can also load a YAML configuration file via `config_from_file()`; either of these options will override glossr’s defaults. A YAML file can be useful if you want to reuse a configuration across different documents. In any case, you can still use `use_glossr()` along your document to override the current settings.

In this vignette I will first show how you can check and override the current configuration, and then go over the effect of each of the settings.

# Configuration settings and override

The current configuration settings can be inspected with `print_config()`, which optionally takes as argument one of the four types of settings: “format”, “pdf”, “word” and “other”. You can also store the contents as a list by assigning the output to a variable.

    print_config()
    #>
    #> ── General line formatting ─────────────────────────────────────────────────────
    #> 1. a:
    #> 2. b:
    #> 3. c:
    #> 4. preamble: b
    #> 5. translation:
    #>
    #> ── PDF-specific formatting ─────────────────────────────────────────────────────
    #> 1. exskip: 0
    #> 2. belowglpreambleskip: 0
    #> 3. aboveglftskip: 0
    #> 4. extraglskip: 0
    #>
    #> ── Word-specific formatting ────────────────────────────────────────────────────
    #> 1. font_family: Cambria
    #> 2. font_size: 12
    #> 3. page_width: 1332
    #>
    #> ── Other formatting ────────────────────────────────────────────────────────────
    #> 1. output: leipzig
    #> 2. trans_quotes: "
    #> 3. numbering: TRUE

## Configuration file

One of the ways to override the default settings, available since version 0.8.0, is loading a YAML file with `config_from_file()`. An example file is provided in `system.file("extdata/glossr-config.yml", package="glossr")`.

### glossr-config.yml

    format:
      a: i
      preamble: b
    pdf:
      exskip: 2
      belowglpreambleskip: 0
      aboveglftskip: 0
      extraglskip: 0
    word:
      font_family:
        a: Cambria
        default: Times New Roman
      font_size: 12
      page_width: 1332
    other:
      trans_quotes: "'"
      numbering: true

### New configuration

    config_from_file(system.file("extdata/glossr-config.yml", package="glossr"))
    print_config()
    #>
    #> ── General line formatting ─────────────────────────────────────────────────────
    #> 1. a: i
    #> 2. b:
    #> 3. c:
    #> 4. preamble: b
    #> 5. translation:
    #>
    #> ── PDF-specific formatting ─────────────────────────────────────────────────────
    #> 1. exskip: 2
    #> 2. belowglpreambleskip: 0
    #> 3. aboveglftskip: 0
    #> 4. extraglskip: 0
    #>
    #> ── Word-specific formatting ────────────────────────────────────────────────────
    #> 1. font_family: Cambria, Times New Roman, and Times New Roman
    #> 2. font_size: 12
    #> 3. page_width: 1332
    #>
    #> ── Other formatting ────────────────────────────────────────────────────────────
    #> 1. output: leipzig
    #> 2. trans_quotes: '
    #> 3. numbering: TRUE

## `use_glossr()` on the fly

Alternatively, for more occasional overrides you may want to use the old `use_glossr()`, which since version 0.8.0 is only necessary if you want to customize your settings.

    use_glossr(styling = list(a = "i", numbering = TRUE, trans_quotes = "**"))
    print_config("other")
    #>
    #> ── Other formatting ────────────────────────────────────────────────────────────
    #> 1. output: leipzig
    #> 2. trans_quotes: **
    #> 3. numbering: TRUE

> Repeated calls to `use_glossr()` can be used to switch the styling in a PDF or Word document, but it won’t work in HTML output because styling is defined by CSS classes that affect all the lines of a certain type.

# Effect of the configuration settings

In the subsections below we’ll go into some more detail regarding these configuration settings. In each of them we’ll discuss one of the “sections”, but all the settings can be adjusted together either as the `styling` argument of `use_glossr()` or via the YAML file.

## Line styling

Glosses produced with glossr don’t have italics or boldface by default. Instructions to set this kind of formatting at the line level can be provided by setting the right items of the `format` set of configuration settings:

- `preamble` or `source` indicate the styling for the (optional) first line, where the “source” variable is rendered.

- `a` or `first` indicate the styling of the first gloss line.

- `b` or `second` indicate the styling of the second gloss line.

- `c` or `third` indicate the styling of the third gloss line.

- `translation`, `trans` or `ft` indicate the styling of the translation line.

Each of these options can either take a value setting italics (“i”, “it”, “italics” or “textit”) or one setting boldface (“b” “bf”, “bold”, “textbf”).

The names can be provided directly in the `styling` argument of `use_glossr()` or as items under `format` in the YAML file. For instance, we can set up the first line in italics and the source in bold as follows:

    use_glossr(styling = list(
      a = "i", preamble = "b"
    ))
    print_config("format")
    #>
    #> ── General line formatting ─────────────────────────────────────────────────────
    #> 1. a: i
    #> 2. b:
    #> 3. c:
    #> 4. preamble: b
    #> 5. translation:

    as_gloss("First line", "Primera línea", source="This should be in bold")

1. This should be in bold

   First line

   Primera línea

The following YAML section achieves the same:

    format:
      a: i
      preamble: b

Styling can be removed by setting the value to ““.

The current configuration of this level can be requested as follows:

    print_config("format")
    #>
    #> ── General line formatting ─────────────────────────────────────────────────────
    #> 1. a: i
    #> 2. b:
    #> 3. c:
    #> 4. preamble: b
    #> 5. translation:

## Latex-specific features

The expex documentation shows a number of parameters that can be manipulated to adjust the spacing between the different parts of a gloss. In all cases the default value is `0`, but you can increase them or reduce them by providing the desired value to the appropriate item under the `pdf` section.

The variables that you can manipulate are the following:

- `exskip` (also called `par_spacing` in this package) defines the space above and below the example.

- `belowglpreambleskip` defines the space under the preamble (where the source is printed).

- `aboveglftskip` defines the spacing above the free translation.

- `extraglskip` defines the spacing between the types of lines, e.g. between the source and the aligned lines, between the aligned lines and the translation, and between the groups of lines if your example is long enough to take more than one line.

For instance, the following sets a spacing of 6pt above and below the example and a spacing of 15pt between the different sections of the example:

    use_glossr(styling = list(
      exskip = 6,
      extraglskip = 15
    ))

The YAML equivalent is:

    pdf:
      exskip: 6
      extraglskip: 15

The current \(\LaTeX\) specific configuration can be requested like so:

    print_config("pdf")
    #>
    #> ── PDF-specific formatting ─────────────────────────────────────────────────────
    #> 1. exskip: 6
    #> 2. belowglpreambleskip: 0
    #> 3. aboveglftskip: 0
    #> 4. extraglskip: 15

## Word-specific features

Since version 0.8.0 glossr renders interlinear glosses in Word by computing the expected width of the words in pixels and padding them with spaces. This is achieved via `systemfonts::string_width()`, which takes arguments such as font family, font size, boldface, and italics. Boldface and italics are already specified via \(\LaTeX\) or markdown formatting but font family and size can be specified as the `styling` arguments `font_family` and `font_size` or under the `word` section in the YAML file. If they are a character/numeric vector of length 1 (e.g. `font_family = "Cambria"` and `font_size = 11`), they will be applied to all the lines. Alternatively, you can specify the values for certain lines if, for example, you combine different scripts with different font families or sizes. For instance, `font_family = list(a = "Arial", default = "Cambria")` will assume that the first aligned line is in Arial and the second and third, in Cambria.

A third Word-specific argument is `page_width`, which indicates the width covered by the lines in pixels. This number (by default 1332) is used to wrap the lines properly when they are too long. If the width of your text differs from the one used to set up this default, you can easily modify it via `use_glossr()` or the configuration file.

As an example, the code below sets “Arial” as the font for the first aligned line and “Cambria” for the rest; size 11 for all the lines and a page width of 430 pixels.

    use_glossr(styling = list(
      font_family = list(a = "Arial", default = "Cambria"),
      font_size = 11,
      page_width = 430))

The YAML section below fulfills the same goal:

    word:
      font_family:
        a: Arial
        default: Cambria
      font_size: 11
      page_width: 430

The current values for these settings can be requested like so:

    print_config("word")
    #>
    #> ── Word-specific formatting ────────────────────────────────────────────────────
    #> 1. font_family: Arial, Cambria, and Cambria
    #> 2. font_size: 11
    #> 3. page_width: 430

Note that this does not render the text in a specific font family or size, but only uses the information to estimate the width of the words and align them better.

## Other formatting

Next to the options discussed above, the `styling` argument can take two other elements.

First, “trans_quotes” defines the character you want to surround your translation with. By default, this is double quotes, but you might want to select single quotes instead, or remove them altogether. The following chunk of code sets italics in the first line and single quotes for the translation:

Second, “numbering = `FALSE`” when the output is not PDF allows you to remove the numbering of examples, e.g. in slides.

These two settings can be provided as part of the `other` section.

    use_glossr(styling = list(
      trans_quotes = "~",
      numbering = FALSE
    ))
    as_gloss("First line", "Primera línea", translation = "Free translation")

First line

Primera línea

~Free translation~

    other:
      trans_quotes: ~
      numbering: false

    print_config("other")
    #>
    #> ── Other formatting ────────────────────────────────────────────────────────────
    #> 1. output: leipzig
    #> 2. trans_quotes: ~
    #> 3. numbering: FALSE