Документация по ЕСПД ГОСТ 19

0. Мотивация, соображения, основные фишки

Для предварительной разработки и написания каждого отдельного документа рекомендую использовать TexStudio, для которого в корне лежит шаблон настроек.

Облегчение жизни программистам и техническим писателям, подготавливющим документацию по ГОСТ 19: поскольку большинство разделов в документах по ГОСТ 19 дублируются, то нет смысла их копировать, поддержка этого превращается в кошмар. Достаточно 1 раз написать в нужные разделы, а затем распределить текст по документам - пример этого и представлен.

Отдельно уделено внимание обработке исходников (файлов исходного кода программа) - производится их архивация с изготовлением контрольной суммы по ГОСТ и изготовление информационно-удостоверяющего листа, в который вставляется контрольная сумма архива.

(ВНИМАНИЕ! Единственное исключение сделано для ИУЛ - он подготавливается вручную по шаблону (вставляются фамилии и названия программы), а затем в него автоматически вставляется контрольная сумма архива).

Что нужно исправить при подгонке под себя:

• Состав создаваемой документации в корневом CMakeLists
• Естественно, править само содержание документов в /documents и отдельно рекомендую в documents/common для повторного использования.
• Все аббревиатуры, используемые в тексте (для автоматического создания перечня сокращений), нужно писать в documents/abbreviations.tex.
• Все требуемые рисунки, иллюстрации ко всем документам - размещать в documents/images.
• Библиографию для автоматического создания перечня использованных источников и оформления ссылок на литературу размещать в documents/bibliography.bib согласно нормам написания *.bib файлов (легко гуглится).
• Исходники описываемой программы (если это надо) должны лежать в documents/text_program/АБВГ.XXXXX 12 01.
• Поскольку, о горе, ГОСТ строго не регламентирует как должен выглядет ИУЛ, каждая "норма" и каждая приемка выпендривается как может - поэтому в директории documents/iul лежат попытки сделать "как по ГОСТ", а потом в documents/iul_easy - по-простому через текстовый файл libreoffice.
• В файле documents/preamble.tex нужно подправить название разработки, фамилии, должности и т.д. для конкретного разрабатываемого изделия.
• Шифр программы вида АБВГ.ХХХХХ во всех файлах заменить на свой, для упрощения этого в корне лежит скрипт replace_word.sh

1. Поддерживаемые документы

• Отдельные листы утверждения для каждого документа
• Спецификация
• Описание программы
• Описание применения
• Руководство системного программиста
• Руководство оператора
• Программа и методика испытаний
• Пояснительная записка
• Информационно-удостоверяющий лист
• Формуляр
• Ведомость эксплуатационных документов
• Ведомость держателей подлинников

Опционально поддерживаются (не являются необходимыми по ГОСТ 19):

• Техническое задание
• Протокол информационного обмена отдельным документом (иногда полезно)

2. Обзор

• Лист утверждения с настраиваемым составом подписей согласования/утверждения (правится в espd)
• Титульный лист с различными вариантами штампа слева (правится в espd)
• Можно включать аннотацию, содержание, приложения (как одно, так и несколько)
• Шаблон будет автоматически нумеровать рисунки, таблицы, формулы и т.д. (больше никакого ручного отслеживания этого кошмара)
• Библиография оформляется отдельным файлом или файлами, как это принято в Tex (и автоматически формирует нужные строки, больше никакого кошмара с этим)
• Отдельное формирование перечня терминов и сокращений (можно отключить)
• В конце каждого документа - лист регистрации изменений (строго так, как написано в ГОСТ 19)

3. Зависимости

Предполагается, что работа происходит под ubuntu/xubuntu/astralinux. Должны быть установлены пакеты:

• texlive (лучше весь дистрибутив теха)
• msttcorefonts (для шрифта times new roman)
• ttf-mscorefonts-installer (для шрифта times new roman, ибо приёмка преваривает только его, увы)
• zip (для архивации исходников)
• libreoffice (вместе с soffice - для редактирования ИУЛ)
• sed (для редактирования ИУЛ)
• gost12sum (для получения контрольной суммы по ГОСТ 19 для архива с исходниками)

Также наобходимо скопировать шрифты из директории /fonts проекта в директорию

/usr/local/share/fonts

для поддержки шрифта ГОСТ.

3. Сборка

Конечная (после окончания разработки) сборка осуществляется командой в терминале из корневой директории проекта:

 mkdir build && cd build && cmake .. && make 

после чего в директории /output появится собранный целевой *.pdf файл/файлы.

При разработке документации удобнее пользоваться редактором, например TexStudio, для чего в его настройках следует указать:

Options -> Configure TexStudio... -> Commands -> XeLaTeX = xelatex -shell-escape -output-directory=./build/ -synctex=1 %.tex
Options -> Configure TexStudio... -> Commands -> BibTeX = bibtex ./build/%.aux
Options -> Configure TexStudio... -> Build -> Default Compiler = txs:///xelatex
Options -> Configure TexStudio... -> Build -> Default Bibliography Tool = txs:///bibtex
Options -> Configure TexStudio... -> Additional Search Paths:
	Log File ./build
	PDF File ./build

также, в корневой директории проекта есть файл настроек TexStudio

4. Структура проекта и разработка документации

Предполагается, что каждый программный документ находится в своей директории (например, /example или /technical_task), где лежат соответствующие корневые файлы данного документа *.tex и *_lu.tex - сам документ и лист утверждения отдельно. Сами исходные тексты разделов документа собраны в директорию /src, иллюстрации собраны в директорию /images, библиография (при необходимости) - в файл bibliography.bib. Файл CMakeLists.txt в директории отдельного документа управляет сборкой и переименовыванием конечного файла документа и его листа утверждения. Корневой CMakeLists.txt позволяет собрать весь проект сразу (все документы)