Межплатформенные инструменты разработки справки конечного пользователя
Каковы некоторые хорошие инструменты разработки для создания межплатформенных справочных файлов для конечных пользователей? (Наше приложение использует спокойную платформу, если это имеет какое-либо значение.)
Примечание: Я не интересуюсь внутренней документацией API - мы используем doxygen для этого.
Идеально, решение было бы:
- Позвольте нам управлять всем содержанием справки (текст, оглавление, изображения, и т.д.) в единственном месте.
- Вывод к собственным форматам справки. (CHM для Windows - или по крайней мере что-то мы могли подать непосредственно в Справку HTML API; не уверенный, каковы "стандартные" форматы справки других платформ.)
- Достойная поддержка WYSIWYG: обработайте общий ввод текста, изображения, перекрестные ссылки, и т.д. легко, но мы можем отредактировать HTML, когда мы должны.
- Основанный на тексте формат файла для проекта справки (XML, и т.д.) так, чтобы это могло быть имеющим версию в Подверсии.
- Любые рычаги, что справка сохраняет его в синхронизации с фактической кодовой базой, были бы большими. (Возможно, так или иначе тема справки связана с файлом кода и может проверить Подверсию, чтобы видеть, были ли какие-либо изменения внесены и отмечают тему как "возможно устаревшую"... я мечтаю?)
- Содержание справки может быть локализовано.
- Не настроенный против коммерческого продукта, но бесплатной опции было бы хорошо.
Я буду идти вперед и делать это Wiki и запускаться с нескольких примеров. Проголосуйте за них или вниз если Вы имеете опыт с ними и оставляете некоторые комментарии. Добавьте дополнительные инструменты также.
6 ответов
Я только что открыл для себя Sphinx; кажется, я влюбился.
- Лучше, чем WYSIWYG над HTML: reStructuredText
- Выводит в QtHelp (среди прочего), поэтому будет легко распространять (и интегрировать) в наше приложение.
- Пока не уверен насчет локализации, но мы перейдем этот мост, когда понадобится.
- Было легко настроить и "просто работает"; выглядит профессионально.
Единственное, что я знаю, это Latex, один из конвертеров latex2html, а затем несколько адаптаций, чтобы сделать полученный html готовым для архиватора CHM.
- text,html,chm,pdf, ps без проблем.
- Конвертация в Word через RTF раньше была катастрофой, сейчас не знаю.
- Конвертеры latex 2 html, хотя их несколько, все имеют свои проблемы.
- pdf-файлы выглядят просто великолепно.
- WYSIWYM (через lyx) возможен.
В этом архиве есть куча CHM (особенно части prog, ref и user, остальные (rtl, fcl, lcl) генерируются нашим собственным эквивалентом doxygen, fpdoc)
http://www.stack.nl/~marcov/doc-chm.zip
Обратите внимание, что вышеупомянутые CHM сделаны с помощью нашего собственного (портативного) компилятора CHM. Да, больше никакого семинара.
Документ Lyx в формате PDF и html:
Я много лет пользуюсь robohelp.
Это хорошо, но основная технология уже очень старая. Кроме того, то, как они привязываются к версиям Word, является полным PITA (и заставляло меня несколько раз избегать обновлений MS Office).
Мы переходим на madcap flash http://www.madcapsoftware.com/products/flare/robohelp.aspx
Я думаю, что DocBook отвечает всем вашим требованиям, за исключением, возможно, ловушек синхронизации, о которых я подумаю чуть позже. По сути, это подмножество XML, предназначенное для создания документации, бесплатное и с открытым исходным кодом. Это просто формат плюс набор выходных преобразований XSL, которые преобразуют Docbook в более полезные форматы (HTML и, следовательно, CHM, JavaHelp, PDF через XML-FO или Tex).
Это означает, что вам по-прежнему необходимо выбрать инструмент для разработки XML, чтобы фактически редактировать его, поэтому такие вещи, как WYSIWYG, будут зависеть от функций вашего программного обеспечения для разработки XML. Мы используем Syntext Serna, так как он хорошо поддерживает WYSIWYG и встроенное редактирование XML #includes (похоже, никто другой не поддерживает последнее). Вы можете найти другие инструменты для разработки XML, которые лучше подходят для ваших нужд — Serna — разумно дорогое коммерческое предложение.
Docbook обеспечивает большую гибкость благодаря профилированию, которое позволяет включать/исключать элементы xml на основе их атрибутов. Примеры использования: вывод справки для OS=Windows немного отличается от OS=Linux. Локализация также поддерживается с помощью профилирования и других механизмов.
Неплохое введение в Docbook можно найти здесь.
Мы используем Docbook для нашего формата справки и компилируем его в файлы CHM, которые содержат справку только по функциям, относящимся к конкретному продукту (т. е. в версии Enterprise есть функции, которых нет в стандартной или демонстрационной версиях). Соответствующие шаги:
- Запустите XSL-шаблоны профилирования в источнике XML (используя, например, XSLTproc).
- Запустите XSL-шаблоны HTML-справки на выходных данных 1.
- Скомпилируйте выходные HTML-файлы с помощью компилятора HTML-справки Microsoft (HHC).