10  Создание книг

Quarto предоставляет возможность создавать книги в различных форматах, имеющих открытый код, доступ к данным и интерактивные элементы в онлайн-публикациях. Примеры таких книг можно найти в Галерее примеров книг Quarto. На момент написания данного текста возможны следующие варианты для книг: HTML, PDF, MS Word, EPUB, AsciiDoc. Увы, в настоящий момент не предусмотрены готовые шаблоны для создания книг с помощью Typst, но возможность использования Quarto и Typst с последующим выводом в PDF существует.

В первую очередь мы сосредоточимся на создании онлайн-книг, такие книги имеют ряд важных преимуществ: обеспечивают широкий доступ, позволяют оперативно исправлять ошибки и опечатки (в отличие от печатных изданий), а также легко дополняются новым материалом. Большинство того, что составляет книги, мы уже рассмотрели в предыдущих главах: например, навигация страницы книги, как оформить библиографию и т. д., поэтому здесь будут кратко изложены основы и рассмотрены некоторые особенности, относящиеся к книгам.

10.1 Создание книги на основе шаблона

Для создания книг можно использовать, аналогично проектам веб-страниц и блогам, те же инструменты: Visual Studio Code (или Positron), RStudio и командную строку.

VS Code

Книгу на основе шаблона в Visual Studio Code (соответственно, Positron) можно создать, выбрав в меню File : New File… : Quarto Project и далее указать Book Project.

Рисунок 10.1: Пример создания книги в Quarto в Visual Studio Code / Positron

RStudio

Для того, чтобы создать книгу в Quarto в RStudio, необходимо выбрать в меню File : New Project… : New Directory : Quarto Book как на рисунке.

Рисунок 10.2: Пример создания книги в Quarto в RStudio

Терминал

Основу для будущей книги можно легко создать с помощью команд в терминале. Для этого необходимо открыть терминал в директории, где необходимо создать книгу, и далее следовать указаниям, набрав команду quarto create project либо quarto create-project --type book, если проект книги создается в текущей директории.

Terminal

quarto create project

Рисунок 10.3: Пример создания книги в Quarto в терминале

В процессе создания необходимо указать название директории и проекта, что потом возможно изменить.

Рисунок 10.4: Процесс создания книги в Quarto в терминале

Для предварительного просмотра необходимо набрать команду quarto preview, а для полного рендеринга проекта — команду quarto render.

Рисунок 10.5: Пример книги в Quarto на основе базового шаблона

Шаблон созданной на основе шаблона книги как проекта будет содержать следующие файлы в новой директории:

book_directory/my_book
1├── _quarto.yml
2├── index.qmd
3├── intro.qmd
4├── summary.qmd
5├── references.qmd
6├── references.bib
7└── cover.png

1

Файл с метаданными проекта Quarto-книги (_quarto.yml).

2

Основной файл книги (index.qmd).

3

Глава: Введение (intro.qmd).

4

Глава: Заключение (summary.qmd).

5

Глава: Библиография (references.qmd).

6

BibTeX-файл с метаданными для формирования библиографии (references.bib).

7

Обложка книги (cover.png).

10.2 Структура книги

10.2.1 Навигация

Структура книги определяется файлом _quarto.yml. Ниже представлен пример простого YAML-файла, задающего структуру книги.

_quarto.yml

project:
  type: book

book:
  # заголовок
  title: "Философия науки"
  # подзаголовок
  subtitle: "исторический обзор и современные проблемы"
  # автор
  author: "А.А. Автор"
  # аннотация
  abstract: "В книге рассмотрены современные подходы к практическим задачам."
  # текущая дата
  date: today
  # главы
  chapters:
    - index.qmd
    - introduction.qmd
    - text: "Содержание"
      href: Guide/index.qmd
    - text: "Основной текст"
      href: Main/index.qmd
    - exercises.qmd 
    # библиография
    - references.qmd
  # приложения
  appendices:
    - Appendicies/first.qmd
    - Appendicies/second.qmd 

# метаданные библиографии
bibliography: references.bib

Файл index.qmd выполняет роль домашней страницей проекта книги и может содержать обложку, вступительное слово, обзор содержания, благодарности, ссылки на аналогичные проекты и сведения о лицензии.

Названия глав указываются как заголовки первого уровня:

introduction.qmd

# Введение {#introduction}

Текст главы...

Совет

Указывайте в заголовках ключи для перекрестных ссылок (как выше {#introduction}), это поможет ориентироваться с тексте или в дальнейшем ссылаться на части книги.

Напомним, что название главы, которое будет отображаться в навигации, можно переопределить, что удобно в случае длинных названий глав:

_quarto.yml

book:
  chapters:
    - text: "Основной текст"
      href: Main/index.qmd

Главы будут нумероваться автоматически, однако для некоторых глав, например, введения и заключения можно отключить нумерацию:

index.qmd

# Введение {.unnumbered}

Текст главы...

Библиография будет сгененрирована автоматически при рендеринге проекта, в который включен файл references.bib, а также файл references.qmd вида:

Рисунок 10.6: Содержание файла references.qmd

10.2.2 Части книги

В том случае, если структура книги достаточно сложная, то можно разделить книгу на части, используя параметр part:

book:
  chapters:
    - index.qmd
    - preface.qmd
    - part: "Название части"
      chapters: 
        - basics.qmd
        - experiments.qmd
    - part: new_part.qmd
      chapters:
        - objects.qmd
        - notation.qmd
        - environments.qmd

Рисунок 10.7: Пример частей книги в Quarto

10.2.3 Приложения

Для добавления приложений необходимо добавить соответствующие части в _quarto.yml.

book:
  chapters:
    - index.qmd
    - preface.qmd
    - references.qmd
  # приложения:
  appendices:
    - appendix_1.qmd
    - appendix_2.qmd

# заголовок для приложений:
crossref:
  appendix-title: "Приложение"
  appendix-delim: ":"
crossref-apx-prefix: "Приложение"

Рисунок 10.8: Пример приложений в Quarto-книге

10.2.4 Изображение обложки

Для книг в форматах HTML и EPUB можно установить изображение в качестве обложки книги, указав это в YAML.

book:
  cover-image: cover-image.png

Рисунок 10.9: Пример HTML-книги с обложкой

Также возможно установить обложки для каждого из указанных форматов:

format:
   html: 
     cover-image: cover-HTML.png
   epub:
     cover-image: cover-EPUB.png

Рисунок 10.10: Пример EPUB-книги с обложкой

Отметим, что использование CSS/SCSS позволяет привнести дополнительные эффекты, например, сделать тень для обложки или преобразование-переход при наведении курсора на обложку.

book-theme.scss

img.quarto-cover-image {
  box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);
  border-radius: 4px;
  transition: transform 0.3s, box-shadow 0.3s;
}

img.quarto-cover-image:hover {
  transform: translateY(-5px);
  box-shadow: 0 20px 40px rgba(0, 0, 0, 0.3);
}

10.3 Дополнительные замечания по созданию книг

10.3.1 Использование скриптов для настроек

Замечательные советы по созданию книг в Quarto рассказала Mine Çetinkaya-Rundel в своем докладе Reproducible, dynamic, and elegant books with Quart. Вот один них.

Рутинные настройки книги удобно оформлять как скрипт и затем отдельно подгружать, например, в начале каждой главы, указывая ссылку на R-файл, обязательно указывая префикс нижнего подчеркивания в начале файла, чтобы исключить рендер:

R

#| echo: false
source("_common.R")
status("drafting")

В свою очередь, _common.R может содержать установки для отображения рисунков, базовую тему для {ggplot2}-изображений, сообщения по статусу текущего издания, функциональные скрипты, позволяющие отображать текущий статус и многое другое. Полный пример такого файла можно найти в коде книги R for Data Science (2e), приведем его адаптированный вариант ниже.

Пример скрипта

_common.R

set.seed(1014)

knitr::opts_chunk$set(
  comment = "#>",
  collapse = TRUE,
  fig.retina = 2,
  fig.width = 6,
  fig.asp = 2 / 3,
  fig.show = "hold"
)

options(
  dplyr.print_min = 6,
  dplyr.print_max = 6,
  pillar.max_footer_lines = 2,
  pillar.min_chars = 15,
  stringr.view_n = 6,
  cli.num_colors = 0,
  cli.hyperlink = FALSE,
  pillar.bold = TRUE,
  width = 77 # 80 - 3 для #> комментария
)

ggplot2::theme_set(ggplot2::theme_gray(12))

status <- function(type) {
  status <- switch(
    type,
    polishing = "должно быть читабельным, но в настоящее время проходит окончательную доработку",
    restructuring = "находится в стадии интенсивной реструктуризации и может быть запутанным или неполным",
    drafting = "в настоящее время это свалка идей, и мы не рекомендуем ее читать",
    complete = "в значительной степени завершено и просто нуждается в окончательной корректуре",
    stop("Invalid `type`", call. = FALSE)
  )

  class <- switch(
    type,
    polishing = "note",
    restructuring = "important",
    drafting = "important",
    complete = "note"
  )

  cat(paste0(
    "\n",
    ":::: status\n",
    "::: callout-",
    class,
    " \n",
    "Вы читаете находящееся в стадии разработки второе издание книги R for Data Science. ",
    "Эта глава ",
    status,
    ". ",
    "Вы можете ознакомиться с полным первым изданием по адресу <https://r4ds.had.co.nz>.\n",
    ":::\n",
    "::::\n"
  ))
}

Заключение