![[MC-04 logo]](/mc-04/chrome/site/logo.png){kind=logo}
Opened 4 days ago
Last modified 43 hours ago
#1553 new улучшение
Альтернативный способ ведения документации.
| Reported by: | mixyil1.1 | Owned by: | Vladimir |
|---|---|---|---|
| Priority: | minor | Component: | Руководство по эксплуатации |
| Keywords: | Cc: |
Description (last modified by )
Как говорили в телефонном разговоре, приведу описание альтенативного способа (отличный от 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 раз).
- сложности с редактированием таблиц.
Ниже прикрепляю:
Attachments (1)
Change History (7)
by , 4 days ago
| Attachment: | main_target_11-11-2026.pdf added |
|---|
comment:1 by , 4 days ago
| Description: | modified (diff) |
|---|
follow-up: 3 comment:2 by , 2 days ago
follow-up: 5 comment:3 by , 2 days ago
Replying to Vladimir:
На первый взгляд, это сложный вариант, по сравнению с редактированием в MS Word и сохранением, как PDF.
Сложный первый, подготовительный этап. Дальше легче - правим текстовые файлы и не переживаем за то что сломается где-то верстка документа. Единственное сложное место это таблицы.
оформление РЭ в файле весьма необычное: каждый заголовок первого уровня занимает целую страницу без текста описания, некоторые рисунки выходят далеко за рамки страницы, масштаб даже мелких рисунков слишком большой - рисунок занимает почти 0,5 страницы, в таблицах тоже много погрешностей, гиперссылки в готовом PDF не работают.
Это та часть подготовительной работы, которую нужно проделать. После конвертации docx -> markdown требуется еще вручную проверить все документы и исправить неточности конвертации (это в большей степени касается таблиц). С картинками есть 2 варианта - все картинки привести к единому размеру или указывать нужный маштаб в документе при вставке. Сылки нужно проставить заново вручную - автоматически не переносятся при конвертации из docx.
В примеденном pdf картинки никак не обрабатывались, только конвертировались emf -> png, таблицы не исправлялись,
ссылки заново не проставлялись. Это черновой вариант чтобы показать принцип.
В целом идея интересная, но требуется более тщательная проработка в части оформления готового документа PDF: колонтитулы, гиперссылки, перекрёстные ссылки, рамки, титульный лист, штамп по ЕСКД, таблицы, рисунки и прочее, что есть в файле Ворда, в точности соответствует и в PDF.
Стиль оформления можно привести к нужному виду, это тоже часть подготовительной работы.
Эти ПО платные? И где они лежат?
comment:5 by , 43 hours ago
Replying to mixyil1.1:
Replying to Vladimir:
На первый взгляд, это сложный вариант, по сравнению с редактированием в MS Word и сохранением, как PDF.
Сложный первый, подготовительный этап. Дальше легче - правим текстовые файлы и не переживаем за то что сломается где-то верстка документа. Единственное сложное место это таблицы.
А вот таблиц в РЭ-84 (на нашем сайте) Очень много (в поиске "Табл." - 453 раза) -
хорошо бы скрипт сам их отредактировал
оформление РЭ в файле весьма необычное: каждый заголовок первого уровня занимает целую страницу без текста описания, некоторые рисунки выходят далеко за рамки страницы, масштаб даже мелких рисунков слишком большой - рисунок занимает почти 0,5 страницы, в таблицах тоже много погрешностей,
гиперссылки в готовом PDF не работают.
Т.е. невозможно сделать работающие гиперссылки в PDF-РЭ ? По-моему это очень плохо.
Гиперссылки в огромном РЭ - это очень важная часть РЭ.
Количество ссылок в последнем РЭ-84 и не сосчитать - наверное, тысячи, причём многие не простые,
а перекрёстные (в Ворде 3 вида ссылок: Закладка, Гиперссылка и Перекрёстная ссылка
и при каждом обновлении заново редактировать слишком трудоёмко...
Вот при конвертации файла Word в файл PDF все ссылки сохраняются и работают.
(конвертация прямо в Ворде функцией "Сохранить как" - можно выбрать любое расширение, в т.ч. pdf).
Это та часть подготовительной работы, которую нужно проделать. После конвертации docx -> markdown требуется еще вручную проверить все документы и исправить неточности конвертации (это в большей степени касается таблиц).
А как исправлять таблицы, если в Ворде они выглядят отлично?
Это должен бы делать какой-то скрипт или софт.
С картинками есть 2 варианта - все картинки привести к единому размеру или указывать нужный маштаб в документе при вставке.
Где это надо указывать, да и это невозможно: много рисунков разного размера, иногда на всю страницу мелким шрифтом.
Сылки нужно проставить заново вручную - автоматически не переносятся при конвертации из docx.
Когда речь идёт о сотнях и даже тысячах ссылок, то это должен бы делать какой-то софт...
В приведенном pdf картинки никак не обрабатывались, только конвертировались emf -> png, таблицы не исправлялись,
ссылки заново не проставлялись. Это черновой вариант чтобы показать принцип.
Принцип ясный, но если это делать в огромном РЭ, но это займёт много времени...
В целом идея интересная, но требуется более тщательная проработка в части оформления готового документа PDF: колонтитулы, гиперссылки, перекрёстные ссылки, рамки, титульный лист, штамп по ЕСКД, таблицы, рисунки и прочее, что есть в файле Ворда, в точности соответствует и в PDF.
Стиль оформления можно привести к нужному виду, это тоже часть подготовительной работы.
В Ворде я знаю, как задавать разные стили (выбор огромный), но хорошо бы конвертер сам,
"глядя" на файл Ворда, установил правильный стиль, иначе при каждой конвертации будет морока...
Спасибо, посмотрю, но доработать этот софт под Ворд и ЕСКД я не смогу...
Скорее всего, если будет 8 книг РЭ, то ссылки между книгами надо будет искать
средствами поиска по ключевым словам, даже если все книги в одной папке...
comment:6 by , 43 hours ago
Replying to mixyil1.1:
Пример pdf большего размера.
Для Word Алиса подсказала возможное решение:
"Как сделать гиперссылку из одного файла Word в конкретное место другого файла Word
Алиса:
Чтобы сделать гиперссылку из одного файла Word в конкретное место другого файла Word, нужно использовать связку «закладка + гиперссылка». Это работает в актуальных версиях Microsoft Word (2016, 2019, 2021, 365).
Шаг 1. Создайте закладку в целевом документе (куда должна вести ссылка)
Откройте второй файл (тот, куда будет вести ссылка):
Поставьте курсор в то место текста, куда должна приводить ссылка (или выделите небольшой фрагмент рядом — например, первое слово абзаца).
На вкладке «Вставка» нажмите кнопку «Закладка».
В поле «Имя закладки» введите короткое имя без пробелов, например target_section1. Можно использовать буквы, цифры и нижнее подчёркивание.
Нажмите «Добавить». Закладка создана.
Важно: имя закладки не должно содержать пробелов и специальных символов. Лучше делать его понятным, чтобы потом не запутаться.
Шаг 2. Сделайте гиперссылку в исходном документе
Откройте первый файл (откуда будет ссылка):
Выделите текст, который станет ссылкой (слово, фразу и т. п.).
Нажмите правой кнопкой мыши по выделению и выберите «Гиперссылка…», либо на вкладке «Вставка» кликните «Ссылка» → «Ссылка…» (или нажмите Ctrl+K).
В открывшемся окне слева в блоке «Связать с» выберите «Файл или веб‑страница».
С помощью кнопки «Выбрать файл…» найдите и укажите путь к второму файлу (целевому).
Обратите внимание на поле «Текст» / «Адрес» внизу окна: там будет путь к файлу. К этому пути нужно вручную добавить приписку с именем закладки через символ #.
Итоговый адрес должен выглядеть примерно так:
C:\Users\Name\Documents\Второй_документ.docx#target_section1
(вместо пути у вас будет свой путь к файлу, а вместо target_section1 — имя вашей закладки).
Нажмите «ОК». Ссылка готова.
Как проверить, что всё работает
В первом файле кликните по ссылке, удерживая клавишу Ctrl (так Word открывает гиперссылки).
Должен открыться второй файл, и курсор встанет сразу в место закладки.
Важные нюансы и ограничения
Файлы должны быть на диске (или в сетевой папке) с фиксированным путём. Если вы переместите или переименуете любой из файлов, ссылка перестанет работать.
Абсолютный путь критичен. Относительные пути (вроде ../Второй_документ.docx) в гиперссылках Word работают нестабильно.
Формат файла. Способ одинаково работает для .docx и .doc.
Облачные хранилища. Если файлы лежат в OneDrive, SharePoint и т. п., лучше использовать локальные копии с понятным путём, либо тестировать ссылки после синхронизации — в некоторых случаях Word может подставлять свои внутренние ссылки, и закладка не сработает.
Несколько закладок. В одном файле можно создать сколько угодно закладок и делать на них ссылки из разных мест и разных документов.
Если скажете, какая у вас версия Word и где хранятся файлы (локально, в облаке, на сетевом диске), подскажу, как адаптировать инструкцию под ваш случай."
Но я пока это не пробовал и не проверял, что получится после конвертации средствами Word to PDF.
Replying to mixyil1.1:
Большое Спасибо за подробное описание альтернативного способа создания РЭ.
На первый взгляд, это сложный вариант, по сравнению с редактированием в MS Word и сохранением, как PDF.
Сейчас я разделяю большой Ворд-файл на 8 книг в разных файлах, поэтому подробно пока не продумал Ваше предложение, но уже вижу, что оформление РЭ в файле весьма необычное: каждый заголовок первого уровня занимает целую страницу без текста описания, некоторые рисунки выходят далеко за рамки страницы, масштаб даже мелких рисунков слишком большой - рисунок занимает почти 0,5 страницы, в таблицах тоже много погрешностей, гиперссылки в готовом PDF не работают.
Я предполагал, что если все 8 книг (файлов Word и pdf) будут в одном каталоге, даже на нашем сайте,
то можно сделать ссылку, по которой откроется нужная книга, а в ней сразу откроется, например, нужный рисунок, таблица, пункт.
В целом идея интересная, но требуется более тщательная проработка в части оформления готового документа PDF: колонтитулы, гиперссылки, перекрёстные ссылки, рамки, титульный лист, штамп по ЕСКД, таблицы, рисунки и прочее, что есть в файле Ворда, в точности соответствует и в PDF.
Эти ПО платные? И где они лежат?