id	summary	reporter	owner	description	type	status	priority	component	resolution	keywords	cc
1553	Альтернативный способ ведения документации.	mixyil1.1	Vladimir	"Как говорили в телефонном разговоре, приведу описание альтенативного способа (отличный от MS Word) ведения документации РЭА.

**Мотивация:** ведение документации в MS Word вызывает ряд неудобств. Мы попробовали связку Markdown → Pandoc → LaTeX: содержимое хранится в виде простых текстовых файлов, разбитых по пунктам, а итоговый PDF собирается из них одной командой. Наш наш взглят так руководство проще редактировать: правка затрагивает один небольшой файл, нет «плывущей» вёрстки (текст правится независимо от оформления), оглавление собирается автоматически. Для внесения изменений достаточно отредактировать нужный файл (текстовый файл) и выполнить сборку. Нужно запустить одну командой, технические детали скрыты в скрипте сборки (Makefile). 

**Шаг 1. Подготовительная часть.**

- Мы преобразовали документ MC04-DSL-3U_РЭ-78_12-11-2025.docx из формата MS Word в формат Markdown rea_78.md + извлекли все картинки из документа и сложили в отдельной папке img.
- Разделили содержимое 1 большого файла rea_78.md на отдельные файлы. Для каждого пункта (2.3, 5.1 ...) и подпункта (4.2.1, 5.2.1 ...) создавали отдельный файл __имя.md. Мы выделили только часть пунктов.
- Поправили содержимое файлов после конвертации (проблема - форматирование таблиц).

**Итог:** содержимое руководства разбито на набор текстовых фалов в формате Markdown, 
все картинки лежат отдельными файлами в папке img.

**Шаг 2. Техническая часть.**

- Описали структуру итогового документа. Какие файлы и в каком порядке будем добавлять в документ.
- Задали команды преобразования набор файлов mardown -> итоговый документ pdf. Составили итоговый файл сборки для linux (Makefile) и windows (build.ps1).
- Описали правила форматирования для итогового документа (шрифт, отступы, оглавлениие, ...).

**Итог:** реализована ""сборка"" руководства 1 командой.


**Шаг 3. Внесение изменений и генерация документа ""руководство по эксплуатации"".**

После выполнения первых 2 шагов схема готова к использованию. 

Пример работы с документацией. 
Что меняем:
- Текст в описании платы (например, E1), включая ссылки на картинки.
- Набор картинок в папке img — добавить новую или заменить существующую.
- Структуру — добавить новый раздел (например, в описание платы VE-02).
- Удалить описание устаревшей платы.
- Менять пункты, разделы местами. 

Как собрать и проверить:
- Выполнить make — собрать итоговый PDF. Для window нажать правую кнопку мыши и выпрать пункт запустить в powershell.
- Открыть PDF и проверить: правки на месте, картинки отображаются, оглавление обновилось.

----

Наш наш взглят такой способ хорошо подходит для ведения документации такого объема как руководство по эксплуатации и позволяет получить определенные плюсы. Однако он же сопряжен и с определенными трудностями.

Плюсы:
- текс правиться отдельно от форматирования
- автоматическая нумерация пунктов, картинок, таблиц
- можно добавить в систему контроля версий
- конвертировать в различные форматы. Например html и добавить документацию в web интерфейс управления.

Какие трудности:
- непревычно. Нужно разобраться с Markdown.
- много подготовительной работы (но нужно сделать 1 раз).
- сложности с редактированием таблиц.

Ниже прикрепляю:
- пример сгенерированого pdf файла руководства.
- архив с исходниками. Можно повторить сборку. Для window нужно установить дополнительное ПО MikTex, pandoc. Запустить сборку - нажать правой кнопкой на файл build.ps1 и выбрать ""выполнить скрипт"". В папке build аоявиться готовый pdf.  "	улучшение	new	minor	Руководство по эксплуатации