Моя команда использует MadCap Flare для создания большого объема документации (тысячи тем). Источником является "Flare HTML", HTML с некоторыми дополнениями Flare (для переменных, предупреждений, фрагментов и т. д.). Мы используем CSS для стилизации HTML по своему вкусу. Мы используем инструмент сборки, поставляемый с Flare, для создания вывода, управляемого скриптами, которые выполняют некоторую предварительную обработку (например, обеспечивают обновление записей оглавления при изменении заголовков тем).
Мы бы предпочли использовать язык семантической разметки, такой как DocBook XML или DITA XML, вместо чистого HTML. Семантическая разметка решила бы для нас ряд проблем с написанием. Но мы не нашли способа сделать это во Flare, и наши авторы очень привязаны к этому инструменту, работая почти исключительно напрямую с графическим интерфейсом Flare. Некоторые из наших пользователей обладают экспертным знанием Flare; по этой и другим причинам 1 менять инструменты было бы очень трудно.
Есть ли способ использовать Flare с языком семантической разметки, сохраняя преимущества использования графического интерфейса Flare, чтобы опыт наших авторов был примерно таким же, как сейчас? HTML «запекается» во Flare; мы можем вместо этого запекать в DocBook или DITA? (Запекание в небольшом подмножестве спецификации DocBook было бы неплохо; когда я использовал DocBook, я, вероятно, использовал только 20-25 из 400 элементов схемы. Я менее знаком с DITA.)
Я предполагаю, что для сборки нам нужно будет добавить шаг преобразования, чтобы преобразовать семантическую разметку в HTML, прежде чем передавать ее в сборку Flare. (В любом случае это кажется проще, чем заставить сборку Flare понимать другую схему).
Нашим основным выходным документом является HTML, но мы также создаем PDF, форматирование которого иногда приводит к беспорядку. Мы пока не можем полностью отказаться от PDF, поэтому решение этой проблемы должно учитывать и PDF. Наше требование к HTML — «хорошо выглядит», а наше требование к PDF — «не ломается».
1 Другие причины: (а) отсутствие бюджета; (б) это предпочтительный корпоративный инструмент (т.е. политика); (c) эта команда уже меняла инструменты один раз, года 3-4 назад, я думаю, и время от времени мы до сих пор сталкиваемся с неоптимальными артефактами этого изменения.
DITA — один из вариантов вывода для Flare. Вы можете создать новую цель DITA прямо рядом с любой целью HTML или PDF. Мы не используем его в моей компании, но я немного поиграл с ним, чтобы посмотреть, как он работает.
Я не уверен, насколько широко поддерживается структура DITA. В моих коротких экспериментах я увидел, что ключевые слова madcap транслируются в теги элементов indexterm в выводе DITA . Переменные заключены в теги элементов ph с атрибутами conref в выходных данных DITA, а файл mcvars.dita включен в выходную папку Resources. В этом файле перечислены только переменные, выбранные в файле Flare Target для вывода DITA.
Для иллюстрации это небольшой пример вывода DITA из Flare:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="Get_Help">
<title>Get Help</title>
<body>
<p>
<indexterm>Get Help</indexterm>
<indexterm>Customer Service</indexterm>Get Help</p>
<p>
<ph conref="Resources/mcvars.dita#mcvars/variableId2" /> is committed to providing a variety of helpful resources to support your needs.</p>
<p>Online Help</p>
<p>From anywhere within <ph conref="Resources/mcvars.dita#mcvars/variableId1" />, click Help to browse our Online Help Center, where you'll find a list of Frequently Asked Questions (FAQs) for quick answers to common questions.</p>
</body>
</topic>
И, для сравнения, та же тема, что и в текстовом редакторе Flare:
<?xml version="1.0" encoding="utf-8"?>
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd">
<head>
</head>
<body>
<h1 class="NewPage"><MadCap:keyword term="Get Help;Customer Service" />Get Help</h1>
<p><MadCap:variable name="Text.Brand" /> is committed to providing a variety of helpful resources to support your needs.</p>
<h2>Online Help</h2>
<p>From anywhere within <MadCap:variable name="Text.AccountPage" />, click <strong>Help</strong> to browse our Online Help Center, where you'll find a list of Frequently Asked Questions (FAQs) for quick answers to common questions.</p>
</body>
</html>
В выходных данных используются типы файлов .ditamap и .dita, а на справочном сайте Madcap для Flare отмечается, что вы не можете редактировать структуру DITA изначально:
По мере того, как DITA играет все более важную роль в технических коммуникациях, становится доступным все больше и больше инструментов для создания этого типа структурированного контента. В этой версии вы не можете использовать Flare для редактирования содержимого DITA. Однако вы можете использовать сторонний инструмент (например, XMetal) для создания структурированных файлов DITA.
Однако, проведя небольшое исследование, я нашел этот учебник на YouTube о том, как создавать собственные элементы DITA с помощью атрибута mc-dita-type в классах абзацев во Flare. Например:
p.Note
{
background-image: url('../Images/Icons/noteicon.png');
mc-auto-number-format: '{b}{color #9EB515}Note: {/color}{/b}';
mc-dita-type: quicktest;
}
После построения вывода DITA этот атрибут типа mc-dita становится тегом элемента quicktest в файле темы.
Условия, однако, не работают в выводе DITA. Включается любой текст в теме, независимо от используемых тегов условий.
Я почти уверен, что ответ на техническом уровне - нет. Но это действительно вопрос, который нужно решать на другом уровне.
Особенность структурированного письма заключается в том, что оно учитывает определенные аспекты окончательной публикации, которые затем должны быть учтены алгоритмами, когда придет время публикации. Причина, по которой эти вещи не учитываются, заключается в том, что вы можете применять разные алгоритмы для получения разных видов выходных данных.
Различные структурированные системы письма выделяют разные элементы публикации и, таким образом, поддерживают разные типы алгоритмов для создания разных типов контента.
Дело в том, что для надежной работы алгоритмов писатели должны правильно создавать структуры. Редактор с фиксированным форматом, такой как Word, FrameMaker или Flare, встраивает структуры этих языков и их представление в графический интерфейс. Графический интерфейс основан на структурах этих языков и не подходит для других языков с другой структурой.
Поэтому для DocBook и DITA требуются разные интерфейсы, которые раскрывают их структуры писателю. Принятие другого языка означает принятие другого интерфейса.
Тем не менее, DITA и DocBook — большие сложные языки. Вы можете создавать для них интерфейсы, которые поддерживают только небольшую часть структур, поддерживаемых полными языками. Они могут быть проще в использовании, но они не поддерживают все функции языка. Вы можете думать, что эти интерфейсы связаны с DITA и DocBook так же, как MarkDown связан с HTML. Markdown гораздо проще писать, чем HTML, но он поддерживает лишь часть языка HTML.
Практически любые существующие форматы письма могут быть преобразованы в DocBook. Результатом будет действительный документ DocBook, но он не будет использовать все возможности DocBook. Преобразование других форматов в DITA сложнее из-за архитектуры темы. Но даже если он работает и создает действительный файл DITA, он не будет использовать все возможности DITA. Содержимое Flare, вероятно, может быть преобразовано либо в DocBook, либо в DITA, но содержимое будет содержать только те структуры, которые поддерживаются интерфейсом Flare. Вы не получите всех возможностей Flare или DITA.
Дело в том, что и DITA, и DocBook поддерживают создание структур контента, которыми можно манипулировать с помощью ряда алгоритмов. Но если ваш инструмент не поддерживает создание структур, требуемых этими алгоритмами, вы не сможете успешно запустить их, даже если ваш исходный файл технически находится в DITA или DocBook.
Другими словами, вы должны отталкиваться от алгоритмов, которые хотите использовать в своем контенте. Алгоритмы, которые вы хотите запустить, требуют надежной работы определенных структур контента. Таким образом, вам нужно выбрать язык, поддерживающий эти структуры, а затем выбрать инструмент, позволяющий авторам создавать эти структуры легко и просто.
Если инструмент, который вы сейчас используете, не поддерживает алгоритмы, которые вы хотите запустить, скорее всего, он не будет поддерживать создание структур, необходимых для запуска этих алгоритмов. Вам нужен инструмент, соответствующий формату, который поддерживает алгоритмы, которые вы хотите запустить.
Моника Челлио