Help - Помощь

НАЧАЛО >> Оглавление >> Help - Помощь📄 Скачать в DOCX

Подсистема помощи САБ ИРБИС 64/128 опирается на набор связанных в виде дерева страниц, реализуемых одной из двух технологий - в виде класса PHP или в виде Markdown файла

1. Правила ведения документации

Основной источник пользовательской и технической документации системы - каталог modules/Help/Help.

Новые статические разделы рекомендуется писать в Markdown. PHP-файлы .help используются там, где нужна динамическая генерация: списки модулей, автодокументация действий, функций, страниц и параметров.

Каждая новая Help-страница должна:

иметь заголовок первого уровня #;
иметь ссылку на родительский раздел через {&linkup ...}, кроме корневой страницы;
быть достижимой из пользовательского дерева через Sub() или {&linksub ...};
открываться через ?id=Help/Show&m=... без ошибок;
выгружаться в DOCX как отдельная страница;
если страница является разделом, выгружаться в DOCX вместе с поддеревом;
использовать изображения из стабильных путей внутри модуля или modules/Help/Help;
иметь понятный источник миграции, если материал перенесен из Documentation.

2. Markdown-страницы Help

Markdown-страница связывается с Help-путем так же, как PHP-страница .help: путь Module/Section/Page соответствует файлу modules/Module/Help/Section/Page.md. Для собственных страниц модуля Help используется тот же принцип, например Help/HelpDoc загружает modules/Help/Help/HelpDoc.md.

При открытии раздела подсистема сначала ищет PHP-файл .help. Если он не найден, загружается одноименный файл .md. Это позволяет постепенно переносить статические материалы на Markdown и оставлять динамические разделы на PHP-классах.

В Markdown-файле первый заголовок # используется как заголовок Help-раздела. Ссылка на родителя задается макросом {&linkup ...}, а дочерние страницы подключаются через {&linksub ...}. Относительные пути ./... и ../... вычисляются от текущего Markdown-файла; их нужно использовать для изображений, подключаемых фрагментов и локальных ссылок внутри раздела.

Перед преобразованием Markdown в HTML или DOCX выполняется обработка Help-макросов: include, template, image, h, action, module, table, counter и других команд из списка ниже. Если параметр макроса содержит пробелы, его нужно размещать последним параметром команды.

3. DOCX-экспорт

DOCX-экспорт позволяет скачать любой раздел Help как документ Microsoft Word. На странице просмотра раздела ?id=Help/Show&m=<раздел> ссылка Скачать в DOCX выводится в верхней строке навигации, если в системе активен модуль FT.

Кнопка скачивания раздела Help в DOCX

При нажатии ссылки открывается страница ?id=Help/DownloadDocx&m=<раздел>. Она собирает Markdown текущего раздела, подготавливает его для конвертации и передает в модуль FT, где используется поставляемый конвертер Pandoc.

В DOCX попадает:

заголовок и текст выбранного раздела;
дочерние страницы раздела, подключенные через Sub() или {&linksub ...};
изображения из стабильных путей внутри Help или модулей;
таблицы, списки, информационные и предупреждающие блоки;
оглавление и титульный лист, если они включены в настройках.

Если одна и та же страница встречается в дереве повторно, экспорт добавляет диагностическую строку о пропуске повторной ссылки. Это защищает документ от зацикливания при ошибочной структуре дерева.

3.1. Настройки DOCX-экспорта

Настройки находятся в административной карточке модуля Help:

referenceDocx - файл-шаблон стилей DOCX. Если свой файл не задан, используется шаблон reference.docx из модуля Help;
addTitlePage - добавлять титульный лист с названием выбранного раздела;
addToc - добавлять оглавление;
tocDepth - максимальный уровень заголовков, включаемых в оглавление;
tocTitle - заголовок оглавления.

Для корректной выгрузки изображений пути в документации должны указывать на файлы, доступные из корня системы, например через макрос {&image ...}. Локальные файлы вне дерева системы в DOCX не попадут.

3.2. Проверка и диагностика

DOCX-экспорт должен работать начиная с любого раздела Help, а не только с корневой страницы.

При проверке раздела нужно убедиться, что:

ссылка Скачать в DOCX отображается на странице ?id=Help/Show&m=<раздел>;
HTTP-запрос ?id=Help/DownloadDocx&m=<раздел> завершается успешно;
результат является валидным OpenXML-документом;
в документ попадает содержимое текущей страницы;
в документ попадает поддерево раздела из linksub или Sub();
в документе нет диагностических строк вида Ошибка загрузки раздела, Ошибка экспорта, Неизвестная ссылка, Fatal, Warning, если они не являются частью описываемого пользовательского текста.

Если ссылка на скачивание не отображается, нужно проверить доступность модуля FT. Если скачивание завершается сообщением Pandoc error, нужно проверить поставку Pandoc, шаблон referenceDocx и доступность изображений, подключенных в экспортируемом разделе.

4. Автодокументация

Автодокументация модулей строится по файлам __call, Actions, Pages и параметрам модуля. Такой механизм полезен для обзора API, но он подключает исполняемые PHP-файлы и поэтому должен обрабатываться осторожно.

Требования к автодокументации:

ошибка в одном действии, функции или странице не должна ронять весь раздел;
проблемный элемент должен отображаться диагностической строкой, чтобы его можно было исправить отдельно;
подключаемые файлы не должны выполнять внешние переходы, сетевые вызовы, запись данных или exit при обычной загрузке описания;
для файлов с внешними SDK и побочными эффектами предпочтительно выделять метаданные описания отдельно от исполняемой логики;
повторно подключаемые зависимости должны использовать require_once или include_once.

5. Экспорт WhatsNew из Jira и Bitbucket

Страница ?id=Help/JiraExport запускает фоновую задачу Help/JiraExport, которая собирает данные Jira и Bitbucket и обновляет разделы Что нового в дереве Help.

Режим предназначен для подготовки и обновления страниц вида modules/Help/Help/GeneralDescription/WhatsNew/<проект>/...:

индекс проекта index.md;
страницы версий, например I128/2026.2.md;
карточки задач TaskInfo/<ключ>/README.md;
метаданные задач TaskInfo/<ключ>/meta.json;
используемые в описаниях изображения из вложений Jira.

Каталог modules/Help/Help/GeneralDescription/WhatsNew и все его подпапки являются результатом автоматической генерации при выпуске релиза. Не создавайте и не редактируйте эти файлы вручную: при следующей генерации они будут перезаписаны. Если нужно изменить текст в Что нового, обновите summary или description соответствующей связанной задачи Jira.

В форме запуска задаются:

Форма экспорта задач из Jira/Bitbucket

URL Jira - базовый адрес Jira, по умолчанию https://jira.irbis128.ru;
URL Bitbucket - базовый адрес Bitbucket, по умолчанию https://bitbucket.irbis128.ru;
ID Проекта - ключ проекта Jira и подпапка WhatsNew, например I128;
Логин и Пароль - учетные данные для чтения Jira и Bitbucket;
Номер задачи - необязательный ключ Jira для экспорта одной задачи;
Номер версии - необязательный фильтр fixVersion для пакетного экспорта завершенных задач.

Если указан номер задачи, экспортируется только эта задача и ее связанный контекст. Если номер задачи не указан, задача выбирает завершенные задачи проекта, при необходимости ограничивая выборку указанной версией.

Во время обработки задача:

получает полные данные Jira, включая описание, тип, статус, версию, компоненты, вложения и связи;
читает dev-status Jira по Bitbucket и отбирает pull request, ветки, коммиты и измененные файлы, относящиеся к тому же проекту;
конвертирует Jira Wiki Markup в Markdown для Help;
скачивает только те изображения из вложений, которые реально упомянуты в описании задачи или pull request;
транслитерирует имена файлов вложений в безопасный вид;
оформляет изображения через макрос {&image ...};
добавляет linkup и linksub, чтобы карточки задач были доступны из дерева Help;
обновляет индексные страницы версий и проекта.

Запуск выполняется через очередь WIrbis (Queue/AppendTaskAndMonitor), поэтому длительный экспорт отображается в штатном окне мониторинга. После завершения в дереве Help обновляются страницы проекта, версий и карточек задач в разделе Что нового.

6. Специальные расширения markdown ИРБИС 128

action: {&action Cataloguer/LinkSearch} - создает ссылку на описание действия модуля
blockinfo: {&blockinfo text} - вывести блок с информацией (inline-аналог @@@info)
blockwarn: {&blockwarn text} - вывести блок с предупреждением (inline-аналог @@@warn)
counter: {&counter counter_type counter_name} - создать якорь счетчика произвольного типа "1"
doclinkNo: {&doclinkNo ./../chapter1/index} - преобразуется в текст:
- п. 1.3 - если включен режим нумерации заголовков и заголовок с указанной ссылкой присутствует в документе
- п. "Заголовок главы" - если выключен режим нумерации и заголовок с указанной ссылкой присутствует в документе
- разд. "Заголовок главы" - если заголовок с указанной ссылкой отсутствует в документе
h: {&h link} - создать ссылку на раздел помощи, например АРМ Каталогизатор
image: {&image counter_name image_path caption} - вставляет markdown-изображение целиком
img: {&img counter_name} - создать якорь изображения "Рисунок 1 -"
include: {&include ./../tplIndex .} - подключает Markdown-файл "по месту" как самостоятельный вложенный раздел. Относительные ссылки внутри подключенного файла вычисляются от папки этого файла. Второй параметр управляет смещением заголовков: . оставляет уровни без изменения, строка из символов # добавляет уровни к стандартному смещению include
includesublinks: {&includesublinks 1} - команды linksub рассматриваются как include. Если параметр 0 - выключает такое поведение. Если 1 - включает. Команда без параметров эквивалентна 1 (включает поведение)
l: {&l counter_name} - вывести ссылку на якорь. Например, "(см. рисунок 1)"
linksub: {&linksub Help/Root/Sub} - ссылка на документ ниже уровнем
linkup: {&linkup Help/Root} - ссылка на документ выше уровнем
module: {&module Cataloguer} - создает ссылку на описание модуля
table: {&table counter_name Название таблицы} - создать якорь таблицы "Таблица 1. Название таблицы"
template: {&template ./../tplIndex . localPath} - подставляет Markdown-файл как шаблон. В отличие от include, по умолчанию сохраняет текущий относительный путь вызывающей страницы. Второй параметр задает смещение заголовков, третий параметр позволяет явно указать локальный путь для относительных ссылок внутри шаблона

6.1. Подключение Markdown-фрагментов через include и template

Макросы include и template помогают собирать один Help-раздел из нескольких Markdown-файлов. Оба макроса раскрываются до обработки обычных ссылок, заголовков, счетчиков, изображений и DOCX-экспорта, поэтому подключенный текст участвует в HTML и DOCX так же, как основной файл.

Используйте include, когда подключаемый файл является самостоятельной страницей или главой Help. Такой файл можно открыть отдельно по Help-пути, а его относительные ссылки ./..., ../..., изображения и вложенные подключения считаются от папки самого подключенного файла.

&#123;&include ./Chapter .}

Используйте template, когда один и тот же Markdown-фрагмент должен вставляться в разные страницы как общий шаблон. Файл читается из первого параметра, но относительный путь по умолчанию остается путем страницы, которая вызвала макрос. Это удобно для общих предупреждений, описаний настроек и повторяемых блоков, которым нужны изображения или ссылки текущего раздела.

&#123;&template ./CommonBlock . .}

Второй параметр управляет уровнем заголовков внутри подключенного файла:

. - не менять уровни заголовков;
# - добавить один уровень для template и дополнительный уровень для include;
## - добавить два уровня для template и два дополнительных уровня для include.

Третий параметр есть только у template. Если он не указан или равен ., относительные пути внутри шаблона вычисляются от текущей Help-страницы. Если шаблон должен использовать файлы из своей собственной папки, укажите эту папку или Help-путь явно.

&#123;&template ./Shared/Warning . ./Shared/Warning}

Если подключаемый файл не найден, Help выводит диагностический текст Ошибка загрузки подключаемого файла. При проверке документации нужно открыть HTML-страницу и DOCX-экспорт раздела, в который вставлен include или template, и убедиться, что такой диагностики нет.

7. Специальное выделение блока текста

7.1. Блок с предупреждением

@@@warn
Текст предупреждения
@@@

Выведет:

Текст предупреждения

7.2. Блок с информацией

@@@info
Текст с информацией
@@@