test/README.md

# Шаблон документов Scientia

Готовая рабочая область Typst для отчётов, писем, технико-коммерческих предложений и договоров. Для повседневной работы нужен один файл настроек — `main.typ`, текст в `chapters/` и материалы в `assets/`.

## Что находится на виду

| Элемент | Что с ним делать |
|---------|------------------|
| `main.typ` | Выбрать компанию и режим, заполнить реквизиты, подключить главы |
| `chapters/` | Писать основной текст документа |
| `assets/` | Хранить рисунки, таблицы, CSV и библиографию |
| `docs/` | Читать инструкции и открывать готовые примеры |

`.template/`, `.private/` и `.vscode/` являются служебными и скрыты в проводнике VS Code. Документация для разработчика шаблона также скрыта и не смешивается с инструкциями автора.

## Первый запуск

1. Установите [Visual Studio Code](https://code.visualstudio.com/), [Git](https://git-scm.com/downloads) и [Typst](https://github.com/typst/typst/releases) 0.15.1 или новее.
2. В VS Code выберите **Файл → Открыть папку** и откройте корень проекта.
3. Установите предложенные расширения или откройте Extensions (`Ctrl+Shift+X`), введите `@recommended` и нажмите **Install Workspace Recommended Extensions**.
4. Откройте `main.typ` и запустите `Typst Preview` через `Ctrl+Shift+P`.

Автосохранение уже включено. Изменения текста появляются в предпросмотре примерно через 700 мс.

## Начало нового документа

По умолчанию открыт пример полноценного отчёта. Для другого типа:

1. Нажмите `Ctrl+Shift+P`.
2. Выполните **Tasks: Run Task / Задачи: выполнить задачу**.
3. Выберите **Scientia: выбрать тип документа**.
4. Выберите `report`, `letter`, `commercial-offer` или `contract`.

Предыдущие `main.typ` и `chapters/` автоматически сохраняются в локальной `.private/starter-backups/`.

## Настройка одного `main.typ`

В начале файла находятся три основных переключателя:

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

Отдельных файлов для черновика и чистой копии нет. После переключателей последовательно заполните исполнителей, источники, приложения и параметры выбранного документа.

Главы подключаются внизу `main.typ` обычными строками:

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

Чтобы добавить, убрать или переставить главу, измените только список `#include`.

Приложения отчёта хранятся отдельными файлами в `chapters/appendices/`. В `main.typ` достаточно перечислить их пути; название и метка находятся в самом файле, а номера А, Б, В назначаются автоматически. Подробный пример: [приложения отчёта](docs/documents.md#приложения-отчёта).

## Рисунки, таблицы, формулы и ссылки

Корневой пример отчёта уже содержит:

- обычный рисунок и рисунок из нескольких панелей;
- таблицу с настраиваемыми столбцами;
- отдельную и встроенную формулы;
- автоматическую нумерацию и ссылки в тексте;
- библиографию и приложение.

Расширенный каталог с пояснениями находится в [руководстве по оформлению](docs/formatting.md). Исходник можно открыть и собрать отдельно: [docs/examples/formatting/main.typ](docs/examples/formatting/main.typ).

## Сборка PDF

Нажмите `Ctrl+Shift+B` или запустите задачу **Scientia: собрать PDF**. Будет создан `document.pdf`.

В Typst Typewriter также доступны две кнопки: быстрый экспорт автоматически формирует имя PDF из названия отчёта, этапа и тома, а экспорт с настройками позволяет выбрать входной `.typ`, имя и папку результата.

Через терминал выполняется та же команда:

```powershell
typst compile --root . main.typ document.pdf
```

## Подписи и печати

Без папки `.private` оставьте `use-private-assets = false`: чистый форк собирается без ошибок. Для печати и подписи организации используются безопасные заглушки, а у отсутствующей подписи сотрудника остаётся пустая строка.

Для выпуска с реальными изображениями:

1. Скопируйте полученную папку `.private` в корень проекта с заменой.
2. В `main.typ` поменяйте одну строку: `#let use-private-assets = true`.
3. Пользуйтесь обычным предпросмотром и задачей **Scientia: собрать PDF**.

В `.private/settings.typ` хранятся доступность изображений и индивидуальные смещения подписей. Состав исполнителей и их роли меняются понятными строками в `main.typ`. Подробная структура: [приватные данные](docs/private-assets.md).

## Git в двух словах

- **Commit** — контрольная точка с объяснением изменений.
- **Branch** — отдельная версия для главы или набора правок.
- **Pull** — получить изменения коллег.
- **Push** — отправить свои контрольные точки на сервер.
- **Merge** — объединить работу веток.

Пошаговая инструкция для сотрудников без опыта программирования: [Git для авторов документов](docs/git.md).

## Публичная документация

| Тема | Ссылка |
|------|--------|
| Полная навигация | [Документация пользователя](docs/README.md) |
| Виды документов и главы | [Работа с документами](docs/documents.md) |
| Таблицы, рисунки, формулы и ссылки | [Руководство по оформлению](docs/formatting.md) |
| Все компилируемые примеры | [Каталог примеров](docs/examples/README.md) |
| VS Code, расширения и предпросмотр | [Настройка VS Code](docs/vscode.md) |
| Коммиты, ветки и merge | [Git для авторов](docs/git.md) |
| Подписи, печати и смещения | [Приватные данные](docs/private-assets.md) |
| Редактирование технического текста | [Подсказка по стилю](docs/writing-style.md) |
| Типовые проблемы | [Решение проблем](docs/troubleshooting.md) |

Документация разработки шаблона предназначена только для сопровождающих: [.template/development/docs/README.md](.template/development/docs/README.md).