Initial commit

docs/documents.md

@@ -0,0 +1,119 @@
+# Работа с документами
+
+## Один файл настроек
+
+В проекте используется только один входной файл — `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 и сохраните законченную часть отдельным коммитом.