# Работа с документами

## Один файл настроек

В проекте используется только один входной файл — `main.typ`. В нём находятся данные документа, выбранный режим и порядок глав. Отдельные `draft.typ` и `clean-copy.typ` не нужны.

```typst
#let company-id = "scientia" // "scientia" | "technology" | "too"
#let document-mode = "final" // "final" | "draft" | "clean-copy"
#let use-private-assets = false // true, когда есть настроенная .private
```

- `final` — выпускной документ; приватные подписи и печати показываются при `use-private-assets = true`;
- `draft` — черновик с водяным знаком без реальных подписей;
- `clean-copy` — чистая копия с зарезервированными местами для ручного подписания.

## Служебные страницы отчёта

Титульный лист, список исполнителей и содержание настраиваются независимо от режима `final`, `draft` или `clean-copy`. Переключатели находятся в начале `main.typ`:

```typst
#let show-title-page = true // Титульный лист
#let show-executors = true // Список исполнителей
#let show-outline = true // Содержание
```

Частые варианты:

| Вариант | `show-title-page` | `show-executors` | `show-outline` |
|---------|-------------------|------------------|----------------|
| Полный отчёт | `true` | `true` | `true` |
| Отчёт без титула и исполнителей, но с содержанием | `false` | `false` | `true` |
| Только основной текст | `false` | `false` | `false` |

Если список исполнителей включён, но массив `executors` пуст, отдельная пустая страница не создаётся. При отключении служебных страниц основной текст начинается сразу с первой страницы.

## Виды документов

| Вид | Когда использовать | Готовый исходник |
|-----|--------------------|------------------|
| Отчёт | Технический или научный отчёт с титулом, содержанием, источниками и приложениями | [report/main.typ](examples/documents/report/main.typ) |
| Письмо | Исходящее письмо с адресатом, номером, подписью и перечнем приложений | [letter/main.typ](examples/documents/letter/main.typ) |
| ТКП | Предложение с составом работ, стоимостью, сроками и условиями оплаты | [commercial-offer/main.typ](examples/documents/commercial-offer/main.typ) |
| Договор | Стороны, представители, разделы, реквизиты и приложения | [contract/main.typ](examples/documents/contract/main.typ) |

Самый простой способ выбора — задача VS Code **Scientia: выбрать тип документа**. Она заменяет `main.typ` и `chapters/`, предварительно сохраняя резервную копию в `.private/starter-backups/`.

## Главы

Один крупный смысловой раздел удобно хранить в одном файле:

```text
chapters/
├── 00-introduction.typ
├── 10-methods.typ
├── 20-results.typ
├── 30-discussion.typ
├── 90-conclusion.typ
└── appendices/
    ├── 01-source-data.typ
    └── 02-calculations.typ
```

Числовой префикс помогает видеть порядок в проводнике, но сам по себе ничего не подключает. Состав PDF задаётся внизу `main.typ`:

```typst
#include "chapters/00-introduction.typ"
#pagebreak()
#include "chapters/10-methods.typ"
```

## Приложения отчёта

Каждое приложение отчёта хранится в отдельном файле внутри `chapters/appendices/`. В `main.typ` указываются только пути и их порядок:

```typst
#let appendices = (
  path("chapters/appendices/01-source-data.typ"),
  path("chapters/appendices/02-calculations.typ"),
)
```

Первый заголовок файла является названием приложения. На той же строке задаётся уникальная метка:

```typst
= Исходные данные <appendix-source-data>

Здесь находятся таблицы, рисунки и текст приложения.
```

Номер писать не нужно: файлы из списка автоматически становятся приложениями А, Б, В и начинаются с новой страницы. Заголовки попадают в содержание, а рисунки и таблицы получают номера `А.1`, `А.2`, `Б.1`. Чтобы временно исключить приложение или поменять порядок, измените только список `appendices` в `main.typ`; сами файлы переносить не требуется.

Ссылка оформляется той же функцией, что и ссылки на рисунки и таблицы:

```typst
Исходные данные приведены в #vref(<appendix-source-data>).
```

Получится «в Приложении А». Другие формы: `#vref(<appendix-source-data>, "и")` — «Приложение А», `"р"` — «Приложения А», `"д"` — «Приложению А», `"в"` — «Приложение А», `"т"` — «Приложением А». Групповая ссылка `#vrefs((<appendix-a>, <appendix-b>))` даёт «Приложениях А и Б».

Параметры `attachment()` и `attachment-set()` по-прежнему используются в письмах и договорах, где название нужно для перечня вложений. Для отчёта они не нужны.

## Ресурсы

- изображения — `assets/images/`;
- библиография — `assets/references.bib`;
- таблицы данных — `assets/data/` или непосредственно `assets/`;
- материалы конкретной главы можно хранить в подпапке с понятным именем.

Используйте прямые слеши: `assets/images/section-2.png`. Путь внутри главы считается относительно файла главы, поэтому из `chapters/10-main.typ` изображение обычно открывается как `../assets/images/example.png`.

## Как начать собственный проект

1. Выберите вид документа до начала больших правок.
2. Откройте `main.typ` и проверьте параметры сверху вниз.
3. Переименуйте или создайте главы.
4. Обновите список `#include`.
5. Замените учебные рисунки, таблицы и формулы своими данными.
6. Соберите PDF и сохраните законченную часть отдельным коммитом.