diff --git a/AGENTS.md b/AGENTS.md index dba63bd..4db8732 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,6 +24,9 @@ - **Создание — только через `--init`.** Новый проект создавайте командами с флагом `--init` (см. ниже): они формируют правильную структуру и общий каталог ресурсов. +- **Сначала план — потом работа.** Прежде чем наполнять проект, составьте план и + сохраните его в `content/<проект>/PLAN.md` (см. раздел «Планирование проекта»). + Работу над содержимым начинайте только после согласования плана с пользователем. - **Имя результата = имя проекта.** Документ и презентация собираются в папку проекта, а имя файла совпадает с именем проекта: `content/<проект>/<проект>.docx` и `content/<проект>/<проект>.pptx`. @@ -43,7 +46,8 @@ ssau-generator/ │ └── example/ │ ├── assets/ # общие ресурсы проекта (для docx и pptx) │ ├── docx/ # config.yaml + *.md -│ └── pptx/ # config.yaml + slides/ +│ ├── pptx/ # config.yaml + slides/ +│ └── PLAN.md # согласованный план проекта ├── AGENTS.md # этот файл └── README.md ``` @@ -59,6 +63,24 @@ ssau-generator/ - Папки `content/*` добавлены в `.gitignore`; в репозитории хранится только `content/example/`. Рабочие проекты пользователя коммитить не нужно. +## Планирование проекта + +Перед наполнением проекта составьте план и сохраните его в +`content/<проект>/PLAN.md`. План создаётся **до** работы над `config.yaml` и +Markdown и согласуется с пользователем. В плане укажите: + +- **реквизиты** — студент (ФИО), группа, дисциплина; +- **тему** работы и её цель; +- **структуру** — разделы и подразделы с названиями и пунктами (для документа — + по `sections`, для презентации — список слайдов); +- **краткое содержание** каждого раздела/слайда; +- **список источников** — если согласован с пользователем; +- **нюансы** — особые требования пользователя (объём, оформление, сроки, + ограничения и т.п.), если они указаны; +- прочие согласованные детали. + +Пример готового плана — `content/example/PLAN.md`. + ## Создание нового проекта Проект создаётся командами с флагом `--init` — они формируют структуру и общие diff --git a/README.md b/README.md index 740b380..e051840 100644 --- a/README.md +++ b/README.md @@ -100,6 +100,8 @@ node docx/src/cli.js --content content/<проект>/docx --init node pptx/src/cli.js -c content/<проект>/pptx/config.yaml --init ``` +`--init` создаёт в общем каталоге ресурсов `content/<проект>/assets/` титульный лист `title-page.docx` (образец), который затем используется при сборке. + ### Сборка ```powershell @@ -114,6 +116,11 @@ node pptx/src/cli.js -c content/<проект>/pptx/config.yaml Результат собирается в папку проекта и называется по имени проекта: `content/<проект>/<проект>.docx` и `content/<проект>/<проект>.pptx`. +### 📄 Титульный лист и оглавление + +- **Титульный лист** берётся из файла `document.titlePage` (по умолчанию `content/<проект>/assets/title-page.docx`) и **приклеивается в начало** сгенерированного документа. Образец, созданный при `--init`, содержит условные данные: **отредактируйте его вручную** под свой проект (ФИО, группа, тема, преподаватель и т. п.) — при повторной сборке используется именно этот файл. +- **Оглавление** вставляется как поле Word и при генерации остаётся пустым. После сборки откройте документ в Word и **нажмите «Обновить поле» / «Обновить оглавление»** — оно заполнится автоматически на основе фактических заголовков. Либо включите `document.features.updateFields: true`, и Word обновит поле при открытии. + --- ## 📚 Документация diff --git a/content/example/PLAN.md b/content/example/PLAN.md new file mode 100644 index 0000000..68a075e --- /dev/null +++ b/content/example/PLAN.md @@ -0,0 +1,91 @@ +# План проекта `example` + +Демонстрационный проект: показывает возможности генераторов DOCX и PPTX на одном +наборе общих ресурсов. План согласован с пользователем до начала наполнения +проекта. + +## Реквизиты + +| Поле | Значение | +|------|----------| +| Студент | Иванов Иван Иванович | +| Группа | 6201-090301D | +| Дисциплина | Технологии подготовки отчётных документов | + +## Тема и цель + +**Тема:** демонстрация возможностей генератора отчётных документов SSAU Generator. + +**Цель:** показать полный набор поддерживаемых элементов оформления в одном +документе и одной презентации, собранных из Markdown-исходников. + +## Структура документа (DOCX) + +Файл: `content/example/example.docx`, исходники — `content/example/docx/`. + +| № | Раздел | Тип (`sections`) | Файл | +|---|--------|------------------|------| +| — | Оглавление | `toc` | — | +| — | Введение | `structural` | `01-introduction.md` | +| 1 | Возможности генератора | `numbered` | `02-features.md` | +| 2 | Примеры таблиц | `numbered` | `03-tables.md` | +| — | Заключение | `structural` | `04-conclusion.md` | +| — | Список использованных источников | `bibliography` | `05-bibliography.md` | +| — | Приложение А. Демонстрационные материалы | `appendix` | `06-appendix-a.md` | + +### Краткое содержание + +- **Введение** — назначение документа, перечень частей и групп возможностей. +- **1 Возможности генератора** — заголовки и абзацы; списки, в том числе + многоуровневые; таблицы обычные и с подписью; рисунки (готовые PNG и схемы + PlantUML); формулы с пояснениями; примечания и определения; перекрёстные ссылки. +- **2 Примеры таблиц** — варианты оформления таблиц и подписей. +- **Заключение** — итоги демонстрации, перечень проверенных возможностей. +- **Список источников** — стандарты оформления и учебное пособие. +- **Приложение А** — сводные демонстрационные материалы, буквенная нумерация + объектов. + +## Структура презентации (PPTX) + +Файл: `content/example/example.pptx`, исходники — `content/example/pptx/slides/`. + +| № | Слайд | Тип | Файл | +|---|-------|-----|------| +| 1 | Титульный | `title` | `00-title.md` | +| 2 | Текст и форматирование | `content` | `01-text.md` | +| 3 | Списки | `content` | `02-lists.md` | +| 4 | Таблица | `content` | `03-table.md` | +| 5 | Изображение | `content` | `04-image.md` | +| 6 | Схема PlantUML | `content` | `05-puml.md` | +| 7 | Метрики | `content` | `06-metrics.md` | +| 8 | Схема-цепочка | `content` | `07-flow.md` | +| 9 | Диаграмма | `content` | `08-chart.md` | +| 10 | Две колонки | `content` | `09-columns.md` | +| 11 | Заметки докладчика | `content` | `10-notes.md` | +| 12 | Разделитель | `section` | `11-section.md` | +| 13 | Завершающий | `final` | `12-final.md` | + +### Краткое содержание + +Презентация повторяет состав документа: титул, основные блоки разметки (текст, +списки, таблица, рисунок, PlantUML, метрики, схема-цепочка, диаграмма, +двухколоночная вёрстка, заметки докладчика), разделитель и финальный слайд. + +## Источники (согласованы) + +1. ГОСТ 7.32-2017. Отчёт о научно-исследовательской работе. Структура и правила + оформления. +2. ГОСТ Р 7.0.5-2008. Библиографическая ссылка. Общие требования и правила + составления. +3. Иванов, И. И. Оформление отчётных документов : учебное пособие. — Самара : + Изд-во Самарского университета, 2019. +4. ГОСТ 8.417-2002. Государственная система обеспечения единства измерений. + Единицы величин. + +## Нюансы + +- Общие ресурсы (титульный лист, задники, изображения, `.puml`) лежат в + `content/example/assets/` и используются обоими генераторами. +- Оформление — по СТО 02068410-004-2018; полужирный и курсив в документе + отключены. +- После правок исходников пересобирать `docx` и `pptx`. diff --git a/content/example/assets/title-page.docx b/content/example/assets/title-page.docx index d37a675..f69c40a 100644 Binary files a/content/example/assets/title-page.docx and b/content/example/assets/title-page.docx differ