243 lines
16 KiB
Markdown
243 lines
16 KiB
Markdown
# Запуск, профили и настройки md2gost
|
||
|
||
Справочник по CLI, типам документов, конфигурационным файлам и оформлению. Движок один: интерфейс собирает те же параметры, что и аргументы командной строки.
|
||
|
||
---
|
||
|
||
## 1. Основные команды
|
||
|
||
```bash
|
||
python -m md2gost # окно интерфейса
|
||
python -m md2gost report.md -o report.docx --type coursework --check
|
||
python -m md2gost report.md --check-only --type vkr --strict
|
||
python -m md2gost report.docx -o report.md # импорт Word → Markdown
|
||
python -m md2gost report.docx --check-pages # проверка вёрстки готового DOCX
|
||
python -m word2md report.docx -o report.md # то же импортом напрямую
|
||
python -m md2fodt report.md -o report.fodt # экспорт в формат LibreOffice
|
||
md2gost-gui # окно интерфейса, точка входа
|
||
```
|
||
|
||
Без имени файла или с ключом `--gui` открывается окно. Windows-сборка: `build-exe.bat` даёт `dist\md2gost.exe`, двойной клик открывает окно, аргументы работают так же.
|
||
|
||
---
|
||
|
||
## 2. Типы документов `--type`
|
||
|
||
| Тип | Назначение | Нумерация объектов | Источники | Стиль |
|
||
|-----|-----------|--------------------|-----------|-------|
|
||
| `practice` (по умолчанию) | отчёт по практике | по разделам: 1.1, 2.3 | 5–7, не старше 5 лет | МИРЭА |
|
||
| `coursework` | курсовая работа | по разделам | 5–7, не старше 5 лет | МИРЭА |
|
||
| `vkr` | выпускная квалификационная работа | по разделам | не менее 10 в каждом подразделе списка | МИРЭА |
|
||
| `APID_coursework` | курсовая «Архитектура приложений и данных» | по разделам | 7–20, не старше 5 лет | МИРЭА |
|
||
| `PIS_custom` | итоговый отчёт по практическим работам | сквозная: 1, 2, 3 | не требуются | ПИС |
|
||
|
||
Что меняет профиль:
|
||
|
||
| Свойство | МИРЭА-профили | `PIS_custom` |
|
||
|----------|---------------|--------------|
|
||
| H1 | 18 пт, ПРОПИСНЫЕ, слева (СОДЕРЖАНИЕ и СПИСОК — по центру) | 14 пт, ПРОПИСНЫЕ, по центру |
|
||
| H2 / H3 | 16 пт / 14 пт | 14 пт, по ширине, отступ 1,25 см |
|
||
| Введение и заключение | обязательны | не требуются |
|
||
| Список источников | обязателен | не требуется |
|
||
| Особая структура | у `vkr` — приложение «Графический материал»; у `APID_coursework` — фиксированные заголовки разделов | H1 вида «Практическая работа №N. …» |
|
||
|
||
Общее оформление обоих пресетов: Times New Roman 14, интервал 1,5, поля 30/10/20/20 мм, абзацный отступ 1,25 см, выравнивание по ширине, подпись рисунка под ним, надписи таблицы и листинга сверху.
|
||
|
||
---
|
||
|
||
## 3. Все ключи командной строки
|
||
|
||
### Ввод и вывод
|
||
|
||
| Ключ | По умолчанию | Смысл |
|
||
|------|--------------|-------|
|
||
| `filename` | — | путь к `.md` (сборка DOCX) или `.docx` (импорт в Markdown) |
|
||
| `-o`, `--output` | рядом с исходником | путь результата |
|
||
| `-t`, `--template` | встроенный `Template.docx` | свой шаблон DOCX |
|
||
| `--gui` | — | открыть окно, можно сразу с файлом |
|
||
| `--type` | `practice` | тип документа |
|
||
|
||
### Структура и разметка
|
||
|
||
| Ключ | По умолчанию | Смысл |
|
||
|------|--------------|-------|
|
||
| `--heading-numbering {auto,manual}` | `manual` | `manual` — цифры из markdown, автонумерация Word отключена; `auto` — нумерует Word, цифры из заголовков снимаются |
|
||
| `--toc {manual,native}` | `native` | `native` — поле Word TOC (обновить при открытии); `manual` — md2gost собирает содержание с номерами страниц |
|
||
| `--emdash-to-hyphen` | выкл. | заменить все «—» на «-» |
|
||
| `--hr-pagebreak` | выкл. | строки `---`, `***`, `___` дают разрыв страницы (иначе игнорируются) |
|
||
| `--page-start N` | сквозная нумерация | начальный номер страницы в колонтитуле тела |
|
||
|
||
### Титул, задание, метаданные
|
||
|
||
| Ключ | По умолчанию | Смысл |
|
||
|------|--------------|-------|
|
||
| `--title` | — | готовый DOCX титульного листа; **отключает автогенерацию** |
|
||
| `--auto-title` | выкл. | собрать титул из `info_conv.yaml` и блока ` ```title ` |
|
||
| `--assignment` | — | DOCX бланка задания |
|
||
| `--student`, `--group` | из `md2gost.user.json` | ФИО и группа для автотитула |
|
||
| `--doc-author-from {os,student,custom}` | `os` | источник автора в свойствах DOCX |
|
||
| `--doc-author`, `--doc-last-modified-by`, `--doc-title`, `--doc-subject`, `--doc-keywords`, `--doc-comments`, `--doc-category` | — | поля свойств DOCX; пустое `--doc-comments` убирает штамп md2gost |
|
||
|
||
### Проверка
|
||
|
||
| Ключ | Смысл |
|
||
|------|-------|
|
||
| `--check` | проверить ТЗ и напечатать отчёт |
|
||
| `--check-only` | только проверка, без сборки |
|
||
| `--strict` | код выхода 1 при ошибках, документ не собирается |
|
||
| `--check-pages` | эвристическая проверка полупустых страниц через Microsoft Word (нужны Windows, Word, `pywin32`) |
|
||
|
||
Полный каталог замечаний — в `checker.md`.
|
||
|
||
### Таблицы и листинги через границу страницы
|
||
|
||
| Ключ | По умолчанию | Значения |
|
||
|------|--------------|----------|
|
||
| `--table-continuation` | `word` | `word` — после сохранения Word COM режет по реальной пагинации и подписывает «Продолжение Таблицы N»; `off` и `soft` — одна таблица без автоподписи; `legacy` и `caption` — резать по оценке высоты (возможны артефакты) |
|
||
| `--listing-continuation` | `word` | те же значения для листингов |
|
||
| `--table-repeat-header` | выкл. | повторять шапку таблицы на каждом фрагменте после разрыва |
|
||
|
||
Режим `word` требует Windows, установленный Microsoft Word и пакет `pywin32`. Без Word — `--table-continuation off`.
|
||
|
||
### Диаграммы
|
||
|
||
| Ключ | По умолчанию | Смысл |
|
||
|------|--------------|-------|
|
||
| `--plantuml-jar` | вшитый, иначе `PLANTUML_JAR` | путь к `plantuml.jar` |
|
||
| `--kroki-url` | `KROKI_URL`, иначе `http://localhost:8000` | локальный Kroki |
|
||
| `--diagram-fallback {local,remote,off}` | `remote` | что делать при недоступности локального рендера: `remote` — обратиться к `kroki.io`; `local` — ошибка; `off` — не рисовать |
|
||
| `--diagram-format {png,svg}` | `png` | формат вставки; `svg` даёт вектор с PNG-запасным (Word 2016+) |
|
||
| `--diagram-scale` | `2` | масштаб растра PlantUML и локального Mermaid; размер на странице как при 1 |
|
||
| `--schemes` | рядом с приложением или с `.md` | путь к `md2gost.schemes.json` |
|
||
| `--install-chromium` | — | скачать headless Chromium для Mermaid и выйти |
|
||
|
||
### Прочее
|
||
|
||
| Ключ | По умолчанию | Смысл |
|
||
|------|--------------|-------|
|
||
| `--styles` | пресет типа | путь к `md2gost.styles.json` |
|
||
| `--syntax-highlighting` | выкл. | подсветка синтаксиса в листингах |
|
||
| `--debug` | выкл. | отладочные данные в документе |
|
||
|
||
---
|
||
|
||
## 4. Импорт Word → Markdown
|
||
|
||
```bash
|
||
python -m word2md report.docx -o report.md
|
||
```
|
||
|
||
| Ключ | Смысл |
|
||
|------|-------|
|
||
| `-o`, `--output` | путь к `.md`, по умолчанию рядом с DOCX |
|
||
| `--media-dir` | каталог картинок, по умолчанию `<имя>_media` |
|
||
| `--keep-toc-pages` | сохранить строки содержания Word (иначе остаётся только `[TOC]`) |
|
||
| `--pagebreaks` | писать `---` на разрывах страниц |
|
||
|
||
Что распознаётся: заголовки и спецразделы, содержание, подписи «Рисунок N — …» / «Таблица N» / «Листинг N» (включая склейку «Продолжение…»), таблицы с объединением в `^` и `>`, листинги, формулы OMML в `$$…$$`, библиография `[n]: …`, ссылки `[n]`, часть перекрёстных ссылок восстанавливается как `@Рисунок:fig1_1`.
|
||
|
||
Что теряется: исходники PlantUML и Mermaid (остаются только картинки), язык оградки листингов, осмысленные `id` меток, надписи и SmartArt, сноски, плавающие рисунки. Титул и бланк задания до первого заголовка пропускаются, колонтитулы не импортируются.
|
||
|
||
После импорта результат имеет смысл довести промптом `ai/prompts/from-word.md` и проверить `--check`.
|
||
|
||
---
|
||
|
||
## 5. Экспорт в FODT
|
||
|
||
```bash
|
||
python -m md2fodt report.md -o report.fodt
|
||
```
|
||
|
||
Ключ `--emdash-to-hyphen` работает так же. PDF через LaTeX — каталог `md2latex/`.
|
||
|
||
---
|
||
|
||
## 6. Конфигурационные файлы
|
||
|
||
| Файл | Где лежит | Назначение |
|
||
|------|-----------|------------|
|
||
| `md2gost.user.json` | рядом с приложением | ФИО, группа, блок `metadata` со свойствами DOCX |
|
||
| `md2gost.schemes.json` | рядом с приложением, рядом с `.md`, либо путь в `--schemes` | схемы диаграмм: `title`, `docs`, `ai-prompt`, `includes`, `prefix`, `postfix`, `theme` |
|
||
| `md2gost.styles.json` | рядом с `.md` или путь в `--styles` | оверлей оформления поверх пресета |
|
||
| `info_conv.yaml` | рядом с `.md` | институт, кафедра, дисциплина, преподаватель, должность |
|
||
| `.md2gost-cache/` | рядом с `.md` | кэш отрисованных диаграмм |
|
||
| `md2gost.include-cache.json`, `include-cache/` | рядом с приложением | кэш скачанных `.puml` |
|
||
|
||
Приоритет загрузки, где каждый следующий слой сильнее: встроенный шаблон → файл рядом с приложением → файл рядом с `.md` → явный путь в ключе.
|
||
|
||
### `info_conv.yaml`
|
||
|
||
```yaml
|
||
Институт: Институт информационных технологий (ИИТ)
|
||
Кафедра: Кафедра цифровой трансформации (ЦТ)
|
||
Дисциплина: Проектирование архитектуры цифровой организации
|
||
Преподаватель: Иванов Иван Иванович
|
||
Должность: старший преподаватель, кафедра ЦТ
|
||
```
|
||
|
||
Плоский список `ключ: значение` в UTF-8. Строки с `#` — комментарии. ФИО и группа студента из файла **не читаются**: они берутся из профиля или ключей `--student` / `--group`.
|
||
|
||
### Автотитул: условия срабатывания
|
||
|
||
1. Включён `--auto-title` (или галочка «Автотитул»).
|
||
2. Не задан готовый `--title`.
|
||
3. Есть `info_conv.yaml` рядом с `.md` **или** блок ` ```title ` в начале файла.
|
||
4. Известны ФИО и группа — иначе конвертация останавливается с подсказкой «Для генерации титула нужны ФИО и группа студента».
|
||
|
||
Номер работы и год берутся из блока ` ```title ` (`number`, `year`); значения из блока сильнее `info_conv.yaml`. По умолчанию номер `1`, год — текущий.
|
||
|
||
### `md2gost.styles.json`
|
||
|
||
```json
|
||
{
|
||
"page": { "left_mm": 30, "right_mm": 10, "top_mm": 20, "bottom_mm": 20 },
|
||
"styles": {
|
||
"Heading 1": { "alignment": "center", "size_pt": 14, "all_caps": true }
|
||
}
|
||
}
|
||
```
|
||
|
||
Допустимые имена стилей: `Normal`, `Heading 1`, `Heading 2`, `Heading 3`, `Caption Figure`, `Caption Table`, `Название таблицы`, `Caption Listing`, `Caption`, `Code`, `Table Text`, `Bibliography`, `Bibliography Heading`, `toc 1`, `toc 2`, `toc 3`, `Footer`, `Hyperlink`, `FollowedHyperlink`, `Space After Table`.
|
||
|
||
Допустимые поля стиля: `font_name`, `size_pt`, `bold`, `italic`, `all_caps`, `underline`, `alignment` (`left` / `center` / `justify`), `first_line_indent_cm`, `left_indent_cm`, `right_indent_cm`, `space_before_mm`, `space_after_mm`, `line_spacing` (`1.0` / `1.5`), `page_break_before`, `keep_with_next`, `widow_control`.
|
||
|
||
Неизвестный ключ или неизвестное имя стиля — ошибка запуска. Не настраивается через JSON: табуляция оглавления, отступы списков, оформление формул, цвет текста (всегда чёрный).
|
||
|
||
---
|
||
|
||
## 7. Переменные окружения
|
||
|
||
| Переменная | Назначение |
|
||
|------------|------------|
|
||
| `PLANTUML_JAR` | путь к `plantuml.jar` |
|
||
| `KROKI_URL` | адрес локального Kroki, по умолчанию `http://localhost:8000` |
|
||
| `PLAYWRIGHT_BROWSERS_PATH` | каталог Chromium для Mermaid |
|
||
| `WORKING_DIR` | родительский каталог кэша диаграмм |
|
||
|
||
---
|
||
|
||
## 8. Где что в окне
|
||
|
||
| Меню | Содержимое |
|
||
|------|------------|
|
||
| Основные | тип документа, выходной путь, нумерация заголовков, содержание, режимы продолжения таблиц и листингов, смещение страниц |
|
||
| Настройки → Файлы | шаблон, титульный лист, бланк задания, стили JSON |
|
||
| Настройки → Студент | ФИО и группа (спрашиваются при первом запуске) |
|
||
| Настройки → Метаданные | свойства DOCX |
|
||
| Настройки → Диаграммы | PlantUML, Graphviz для DFD, Chromium для Mermaid, Kroki, формат, сброс кэша |
|
||
| Шаблоны UML | редактор `md2gost.schemes.json` |
|
||
| Справка | инструкция, документация, схемы, промпт для ИИ |
|
||
|
||
Кнопка «Импорт DOCX→MD» и перетаскивание `.docx` запускают импорт; перетаскивание `.md` подставляет файл для сборки.
|
||
|
||
---
|
||
|
||
## 9. Установка
|
||
|
||
```bash
|
||
pip install -e .
|
||
pip install pywin32 # Windows: продолжение таблиц через Word COM
|
||
```
|
||
|
||
Нужен Python 3.10 или новее (для DFD — 3.11 и новее). Для PlantUML нужна Java; для Mermaid — Chrome, Edge или скачиваемый Chromium; для DFD — Graphviz. IDEF0 рисуется локально без внешних зависимостей.
|