
[[make_documentation]]
### Написание документации ZCAD

Документация программы разрабатывается в формате AsciiDoc. Исходники
данного руководства лежат в папке [.filepath]#cad_source/docs/userguide/#.
AsciiDoc - простой текстовый формат, но для генерации pdf и html из него
потребуются дополнительные манипуляций

#### Установка AsciiDoctor для Windows
Т.к. AsciiDoc написан на языке Ruby, придется установить средства разработки
этого языка:

Идем на сайт https://rubyinstaller.org/downloads/ Скачиваем и устанавливаем
последний Ruby+Devkit (на момент написания это 3.2.2-1) В процессе установки
нужно будет указать какой вариант MSYS использовать, выбираем базовый 1,
затем для завершения установки просто жмем enter

После установки Ruby в командной строке можно будет использовать gem -
пакетный менеджер Ruby, с помощью его собственно устанавливает
AsciiDoctor и требуемые расширения. Открываем командную строку и вводим эти
три команды последовательно:

[.shell]#gem install asciidoctor#

[.shell]#gem install asciidoctor-pdf#

[.shell]#gem install asciidoctor-diagram#

Дополнительно для работы asciidoctor-diagram требуется наличие в системе
Java версии не ниже 11, если необходимо идем и устанавливаем по ссылке
https://www.oracle.com/java/technologies/downloads/#jdk21-windows

#### Установка GraphViz
Также понадобятся средства визуализации графов из состава Graphviz.
Идем на https://graphviz.org/download/ и качаем установщик для Windows
на момент написания это graphviz-9.0.0 (64-bit) EXE installer при установке
выбираем вариант [.hl]#Add Graphviz to the system PATH for all users#
чтоб графвиз был доступен из командной строки.

#### Генерация руководства пользователя

NOTE: Описанное выше нужно произвести один раз, это установит на
компьютер необходимые программы и их зависимости

После всех установок запускаем новую командную строку (рекомендую Far)
чтобы все изменения системной переменной PATH вступили в силу. Идем
в корневую директорию zcad (там где лежит makefile) и вводим

[.shell]#make documentation#

Ждем выполнения скриптов, по завершению в папке
[.path]#zcad\cad_source\docs\userguide\# находим сгенерированные файлы
[.path]#userguide.ru.pdf# и [.path]#userguide.ru.html#