Применение языка разметки Markdown для написания отчётов о НИР и других сложноструктурированных документов с регламентированными требованиями к оформлению (Владимир Зенкин, OSEDUCONF-2023)

Ссылки сюда (1) →

Короткая ссылка: 20230128H

Докладчик

Владимир Зенкин

В докладе описан опыт автора по написанию и оформлению технических отчётов по ГОСТ 7.32-2017 с помощью языка разметки Markdown. Для работы предложено применение скриптов автоматизации типовых задач (нумерация рисунков и таблиц, формирование библиографического списка, работа с размерностями величин и т.п.).

Преобразование к форматированному виду осуществляется с помощью утилиты pandoc. Выполнено сравнение предлагаемой методики с традиционными подходами к написанию технических документов в офисных текстовых процессорах и в LaTeX.

Презентация

Thesis

В научной, учебной и инженерной работе существует типовая задача создания сложноструктурированных, форматированных по требованиям документов. К ним относятся технические отчёты, отчёты о НИР, расчётно-пояснительные записки по курсовым проектам, выпускные квалификационные работы и т.п. Помимо увеличения трудозатрат сложная структура документа с многочисленными внутренними ссылками на рисунки, формулы, список литературы чревата возникновением ошибок при составлении документа, когда система ссылок поддерживается вручную.

Для решения данной задачи можно выделить три типовые группы инструментов. К первой относятся офисные текстовые процессоры (MS Word, Writer). Являясь наиболее привычным для пользователя инструментом, они остаются плохо применимыми для больших сложных документов из-за проблем с автоматической нумерацией и внутренними ссылками, неудобством разделения проекта на несколько файлов, проблемами с переносимостью материалов между различными версиями ПО.

Ко второй группе относятся аналогичные инструменты, реализованные с помощью облачных технологий (Google Docs). Основным их достоинством является возможность организации коллективной работы над документом, в том числе синхронной. Однако при этом степень контроля над личными файлами критически снижается, что может быть чрезвычайно важным в условиях работы с коммерческой тайной, личными данными или материалами с грифом секретности.

Другим популярным инструментом является система LaTeX. Имея огромные достоинства с точки зрения возможностей автоматизации, организации внутренних ссылок, работы с библиографией, LaTeX обладает крайне высоким порогом вхождения, высокой сложностью, неудобен при внесении точечных правок.

Кроме того, получение выходного формата, отличного от pdf, затруднительно, что может стать серьёзным препятствием при сдаче работы заказчику.

В качестве альтернативного инструмента, который мог бы вобрать в себя преимущества первого и третьего подхода, и не слишком пострадал бы от их недостатков, автор предлагает применение формата разметки markdown с его последующей обработкой и компиляцией в формат docx с помощью утилиты pandoc.

Преимуществами markdown по сравнению с разметкой LaTeX является:

• отсутствие необходимости в освоении;
• простота при наличии минимально-необходимого функционала;
• большое число редакторов;
• непосредственная визуализация «не текстовых» объектов: формул, рисунков, таблиц;

При этом текст в формате markdown сохраняет большую часть преимуществ \LaTeX:

• абстрагирование от вёрстки при работе с документом;
• надёжность;
• возможность простой обработки скриптами и утилитами;
• возможность полноценного версионирования;
• независимость от конкретного ПО для редактирования.

Для обеспечения необходимого функционала работы с внутренними ссылками и со списком используемых источников автором был написан ряд скриптов. С их помощью можно проводить автоматизированную нумерацию позиций, указывая в тексте метки вида: !!группа.ключ!!. Для списка литературы поддерживается работа с библиографией в формате bibtex. Общая схема работы используемых скриптов и утилит показана на рисунке:

Утилита pandoc осуществляет преобразование файлов проекта в формат docx по шаблону.

Ограничения и недостатки подхода:

• отсутствие идеального md-редактора;
• ограничения по сложности документа;
• сильные ограничения в вёрстке таблиц;
• необходимость чистовой правки документа.

Основные преимущества подхода:

• отсутствие необходимости в освоении инструмента работы с текстом;
• WYSIWYM. Привычная работа с документами с ««in-line»» визуализацией формул, рисунков, таблиц, заголовков и т.п.
• текстовый формат хранения данных повышает надёжность системы, упрощает версионирование, позволяет неограниченно писать и использовать скрипты;
• прозрачная организация внутренних ссылок внутри документа;
• возможность разделения файла на части для лучшей организации проекта или для совместной асинхронной работы.

В таблице перечислены основные требования, актуальные для организации рабочего процесса при оформлении отчётов с указанием уровня их реализации в средах текстовых процессоров, с помощью \LaTeX\ и с предлагаемой автором методикой.

Отметим, что формально в текстовых процессорах присутствует функционал работы с внутренними ссылками, библиографией и т.п., однако в силу его непрозрачности и низкой надёжности он крайне редко используется пользователями в реальной работе.

Таким образом, автор предлагает подход к организации работы по оформлению сложноструктурированных документов научного и технического профиля, направленный на ускорение, повышение удобства и уменьшение числа ошибок. Система реализуется на основе свободного программного обеспечения.