Документування програм

На певному етапі розвитку програмної системи неминуче виникає завдання розробки користувальницької документації. І тут виникає технічне питання вибору форматів і інструментів розробки документації.

1.1. Вихідні формати
З вибором кінцевого формату зазвичай проблем не виникає, так як цільова операційна система висуває свої вимоги. Так, наприклад, для програм для Windows — це формат скомпілованої довідки CHM, для Linux і BSD систем — це man. Загальним для всіх систем форматом для онлайн довідки є html, а для друку — pdf.

Ситуація ускладнюється у випадку, якщо необхідно мати документацію в кількох форматах — для розповсюдження з програмою (chm або man), для розміщення на сайті (html) і для друку (pdf). При цьому можливо, що зміст документації в різних форматах може дещо відрізнятися. Наприклад, відеофрагменти має сенс включати в онлайн документацію, а у друкованій версії їх потрібно замінювати на статичне зображення, можливо доповненим qrcode посилання на фільм. Крім того, зміст документів може відрізнятися для різних категорій користувачів, версій, комплектів поставки та інших факторів.

1.2. Вихідні формати
Незважаючи на гадану очевидність необхідності використання спеціально створених програм, тут не все так однозначно.

Залежно від цільової операційної системи підходи відрізняються.

1.2.1. Пропрієтарні вихідні формати

Так, для створення скомпілованої довідки для Windows у форматі chm Microsoft пропонує використовувати спеціальний безкоштовний компілятор HTML Help Workshop. При цьому вихідні тексти мають бути підготовлені у форматі html редактор в постачання не входить), а файли змісту в специфічному форматі. Ніяких засобів формування друкованих посібників не надається.

Зрозуміло, спеціалізовані програми для створення довідки (Robohelp, Help&Manual, HelpScribble і їм подібні) надають високий рівень сервісу, володіють можливістю формування вихідних документів в різних форматах і навіть в деякій мірі профілювати вміст.

Однак їм притаманні наступні недоліки:

  1. По-перше, всі ці системи комерційні і ліцензуються за кількістю використовуваних робочих місць.
  2. По-друге, використовується ними внутрішній формат є пропрієтарним і не поддержимается ніяким, крім продається. Можливість імпортувати файли в проект вам, звичайно, буде надана, а ось експортувати проект в який-небудь відкритий формат, придатний для подальшої обробки, не вдасться. Навіть у випадку використання в якості внутрішнього формату XML (як, наприклад, Help&Manual) схема його залишається закритою і ніяк не задокументованої.
  3. -третє, можливості по зміні зовнішнього вигляду вихідного документа є недостатніми для формування, наприклад, документації у відповідності з вимогами ГОСТ.
  4. В-четвертих, з цими програмами організувати колективну роботу якщо і можливо, то вкрай важко
1.2.2. Прості формати розмітки
Раціональною альтернативою представляється застосування простих і, як наслідок, швидко освоюваних форматів розміток.

На сьогоднішній день таких форматів:

  • ASCIIdoc, використовуваний дефакто в Linux (BSD) системах;
  • Wiki, застосовуваний в різного роду енциклопедіях і навіть дав їм загальну назву;
  • MarkDown — формат документування систем у системі контролю версій Git.


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

Наприклад, Вікіпедія перетворює Wiki формат HTML «на льоту». Веб-портал системи Git http://github.org так само здатний показувати документи у розмітці Markdown у придатному для читання в браузері вигляді.

1.3. Редактори
Незважаючи на те, що для створення і редагування вихідних текстів достатньо можливостей блокнота, деякі сервісні функції, такі як перевірка орфографії і підсвічування розмітки були б письменникові досить до речі.

У статті http://www.ixbt.com/soft/markdown-online-2.shtml наведено огляд онлайн-редакторів підтримкою markdown-синтаксису, а в http://www.ixbt.com/soft/markdown-online-3.shtml наведено огляд п'яти настільних редакторів, які підтримують формат markdown за замовчуванням, так би мовити, «з коробки».

Одним з таких редакторів є MarkdownPad.

1.3.1. MarkdownPad

Редактор MarkdownPad 2
Малюнок 1. Редактор MarkdownPad 2

Як видно з копії екрану, редактор MarkdownPad 2 підтримує «живий» попередній перегляд редагованого файлу з підтримкою синхронної прокручування вихідного тексту і візуалізації результату.

При установці Windows 8 може виникнути ситуація, коли попередній перегляд недоступний.

Повідомлення про крах системи попереднього перегляду
Малюнок 2. Повідомлення про крах системи попереднього перегляду

За заявою розробників http://markdownpad.com/faq.html#livepreview-directx це пов'язано з необхідністю встановлення специфічного SDK веб-рендеринга Awesomium 1.6.6 SDK, який у свою чергу використовує DirectX.

Редактор підтримує підсвічування синтаксису, перевірку синтаксису одного мови (в тому числі російської), експорт у формати HTML, PDF (тільки в платній версії). Іншими словами, MarkdownPad 2, як і інші спеціальний редактори, є хорошим вибором для технічного письменника. У тих же випадках, коли користувачеві належить редагувати файли різного формату, можна адаптувати свій редактор для редагування текстів з markdown-розміткою.

1.3.2. Notepad++

Редактором, в достатній мірі відповідає цим вимогам, можна вважати Notepad++. Перевірка правопису багатьох мов підтримується з допомогою спеціального плагіна. Причому підтримується перевірка тексту на декількох мовах одночасно.

Редактор Notepad++
Малюнок 3. Редактор Notepad++
Незважаючи на простоту правил розмітки, автора текстів було б зручніше працювати з підсвічуванням синтаксичних елементів. Стосовно до Notepad++ в цьому допоможе проект Markdown Syntax Highlighting for Notepad++, який, по суті, являє собою конфігураційний файл інтерфейсу мови Markdown. Після його установки текст в редакторі виглядає наступним чином.

Редактор Notepad++ з підсвічуванням елементів розмітки markdown
Малюнок 4. Редактор Notepad++ з підсвічуванням елементів розмітки markdown

1.4. Quota
Примітно, що редактори з підтримкою markdown існують навіть для мобільних платформ. На малюнку наведена копія екрану смартфона з запущеним редактором Quoda Code Editor.

Quoda Code Editor - універсальний редактор для Android з підтримкою розмітки markdown
Малюнок 5. Quoda Code Editor — універсальний редактор для Android з підтримкою розмітки markdown

Слід сказати, що більша частина цієї статті набрана саме в цьому редакторі, а вже потім вивантажено на комп'ютер для доопрацювання.

За результатами аналізу можливостей мови розмітки Markdown і спеціальних редакторів можна рекомендувати їх застосування для документування систем середньої складності.

1.4.1. Відкриті теговые формати

Разом з тим, для розробки програмної документації великих систем слід застосовувати в якості вихідного формату відкритий, добре документований формат. В якості засобу формування — інструмент з широкими можливостями по налаштування зовнішнього вигляду, профілювання і здатністю формувати документи в різних форматах.

Цим вимогам повною мірою відповідають такі системи як DITA і Docbook.

Незважаючи на деякі відмінності, обидві системи мають багато спільного:

  • використовують в якості вихідного формату документований (схематизированный) XML, що забезпечує можливість використання для редагування будь-якого редактора XML з функцією валідації;
  • для конвертування в один з результуючих форматів може бути використаний практично будь-xsl-перетворювач xslproc, xalan, saxon та ін;
  • для отримання pdf-документа використовується проміжний формат xsl-fo, з якого засобами будь-якого fo-процесора (наприклад, Apache FOP або XEP) вже формується pdf;
  • для налаштування зовнішнього вигляду і профілювання використовуються численні параметри перетворень, а в разі необхідності — додаванням користувальницьких xsl-шаблонів.


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

Разом з тим практичний досвід використання, зокрема Docbook, підтверджений і в низці публікацій, показав, що і при використанні такої продуманої технології виникають деякі складності:

  • створення вихідних текстів у форматі XML певної схеми вимагає від технічного письменника навичок роботи зі спеціальними редакторами;
  • хороші XML-редактори з підтримкою Docbook — продукти комерційні і недешеві (наприклад, oXygen XML Editor, Altova XMLSpy XML Editor;
  • багаті можливості XML розмітки тягнуть за собою ускладнення формату. Наприклад, для вставки в текст ілюстрації з підписом в розмітці Docbook необхідно використовувати чотири вкладених тегів.


Природно, що перераховані вище недоліки стримують широке застосування XML-орієнтованих технологій єдиного джерела.

У разі використання нетеговых форматів для підготовки офлайн або друкованої документації необхідно використовувати утиліти перетворення. Серед багатьох конвертерів особливої уваги заслуговує програма pandoc.

1.5. Утиліта перетворення pandoc
Pandoc представляє собою кроссплатформенную програму з командним інтерфейсом, здатну перетворювати тексти в найрізноманітніших розмітках в численні вихідні формати.

Так, наприклад з використанням pandoc можна конвертувати вихідні документи в розмітках ASCIIdoc, Wiki, Markdown в HTML. Якщо встановити LaTex, то стає можливим отримання і PDF.

Так, наприклад, перетворення вихідного тексту цієї статті html формат можна виконати наступною командою:

pandoc-f markdown pandoc.md-t html-o pandoc.html -H h.html

Результатом буде готовий html-файлу:
HTML-документ, сформований з Markdown утилітою pandoc
Малюнок 6. HTML-документ, сформований з Markdown утилітою pandoc

За свою універсальність програма образно названа автором «швейцарським армійським ножем».

Дійсно, pandoc справляється з конвертуванням без будь-яких втрат інформації. При конвертуванні з формату MarkDown підтримується читання трьох параметрів метаданих — заголовка, автора і дати документа. Підтримується так само передача параметрів командного рядка для встановлення деяких специфічних властивостей, наприклад мови документа. Є можливість поставити свій шаблон вихідного документа, до деякої міри видозмінюючи його.

Так, наприклад, у наведеному вище прикладі мається на увазі, що в поточній папці є файл h.html, який грає роль заголовка. Якщо в цьому файлі додати посилання на стильовий файл і, визначивши
<base target="_blank">
, отримаємо наступний результат:

HTML-документ, сформований pandoc з використанням заголовкого файлу з посиланнями на стилі
Малюнок 7. HTML-документ, сформований pandoc з використанням заголовкого файлу з посиланнями на стилі

Як видно з прикладу, заголовки придбали свій стиль, а зовнішні посилання стали відкриватися в новій вкладці браузера.

Вищеописані можливості формату роблять виправданим використання розмітки Markdown для документування відносно невеликих програмних систем, до оформлення яких не пред'являється вимог ГОСТ, що і доводиться її широким використанням у системі Git.

Що ж стосується великих систем з великою і складною документацією, то для її створення бачиться застосування системи єдиного джерела Docbook. Можуть мати місце і перехідні випадки, коли масштаб проект проявляється не відразу.

1.6. Docbook
Складність створення вихідних XML-джерел можна подолати шляхом використання вихідних текстів у форматі Markdown з подальшою їх конвертацією в Docbook. Таке перетворення підтримується утилітою pandoc. Так, команда

pandoc-f markdown pandoc.md-t docbook-o pandoc4.xml -H h.xml

створить результуючий файл.

Використання заголовкого файлу
h.xml
(можна просто порожнього) необхідно для коректної обробки метатегів і формування статті.

Сформована стаття в редакторі XML
Малюнок 8. Сформована стаття в редакторі XML

Слід зазначити кілька додаткових вимог до розмітки markdown, яка буде використана для перетворення в docbook:

По-перше, слід уникати використання в тексті символів кутових дужок (< >), так як в XML вони використовуються для виділення тегів, а конвертер залишає їх як є. Якщо ж кутові дужки потрібні за змістом, то слід використовувати сутності
&lt;
та
&gt;
.

По-друге, при вставці зображення обов'язково вводити альтернативний текст, так як pandoc використовує його для створення обов'язкового тега
title
у тега
figure
.

Однак вихідний текст формується в застарілому форматі Docbook 4 версії, в той час як сучасна 5 версія надає істотно більш багаті можливості по семантичної розмітки.

Для перетворення тексту з 4 у 5 версію можна скористатися спеціальним перетворенням db4-upgrade.xsl, що входить в комплект поставки Docbook.

xsltproc-o pandoc5.xml db4-upgrade.xsl pandoc4.xml

Отриманий таким чином xml файл схеми docbook 5 можна використовувати при формуванні єдиного джерела.

Стаття схеми в редакторі XML в режимі автора
Малюнок 9. Стаття схеми в редакторі XML в режимі автора

Описаний ланцюжок перетворень може здатися на перший погляд довгої і невиправдано складною. Однак освоївши один раз необхідних інструментів і розробивши для часто виконуваних завдань командні файли (скрипти) можна заощадити значну кількість часу в подальшому.

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

Набір перетворень Docbook підтримує формування документів в HTML зі стилями, PDF для друку так би мовити «з коробки».

xsltproc-o pandoc5.fo c:\<Путь до DocbookXSL>\f\docbook.xsl pandoc5.xml

Зовнішній вид вихідних документів може бути до певної міри налаштований за допомогою параметрів. Отримані файл формату FO-XSL pandoc5.fo є проміжним і потрібен для побудови кінцевого PDF.

Важливою є й можливість автоматичного формування змісту, списку ілюстрацій, лістингів, таблиць, індексного покажчика, глосарію термінів і список літератури.

При великій кількості документів у складі пакету також можливе створення окремого списку з можливістю автоматичного формування правильно оформлених посилань на них. У випадку підготовки типографського макета керівництва з урахуванням особливих вимог, наприклад ГОСТ, необхідно розробити додаткові xsl для форматів звичайних сторінок, титульної і фінальної сторінки.

Це може стати темою наступної статті.

Джерело: Хабрахабр

0 коментарів

Тільки зареєстровані та авторизовані користувачі можуть залишати коментарі.