Кроссплатформенные инструменты разработки помощи конечным пользователям
Какие хорошие авторские инструменты для создания кроссплатформенных файлов справки для конечных пользователей? (Наше приложение использует каркас Qt, если это что-то меняет.)
Примечание: меня не интересует внутренняя документация по API - для этого мы используем doxygen.
В идеале решение будет:
- Позвольте нам управлять всем справочным контентом (текстом, оглавлением, изображениями и т. Д.) В одном месте.
- Вывод в родные форматы справки. (CHM для Windows- или, по крайней мере, что-то, что мы могли бы передать непосредственно в API справки HTML; не уверен, что "стандартные" форматы помощи других платформ.)
- Достойная поддержка WYSIWYG: легко обрабатывать обычный текстовый ввод, изображения, перекрестные ссылки и т. Д., Но мы можем редактировать HTML, когда это необходимо.
- Текстовый формат файла для проекта справки (XML и т. Д.), Позволяющий создавать версии в Subversion.
- Любые хуки, которые помогают синхронизировать его с реальной базой кода, были бы хороши. (Возможно, тема справки связана с файлом кода и может проверить Subversion, чтобы увидеть, были ли внесены какие-либо изменения, и пометить тему как "возможно, устаревшую" ... я мечтаю?)
- Содержание справки может быть локализовано.
- Не в отличие от коммерческого продукта, но бесплатный вариант будет неплохо.
Я сделаю это вики и начну с нескольких примеров. Проголосуйте за них, если у вас есть опыт, и оставьте несколько комментариев. Добавьте также дополнительные инструменты.
6 ответов
Я только что обнаружил Сфинкса; Я думаю, я влюбился.
- Лучше, чем WYSIWYG над HTML: reStructuredText
- Выводит в QtHelp (между прочим), поэтому будет легко распространять (и интегрировать) в наше приложение.
- Пока не уверен насчет локализации, но мы перейдем этот мост, когда нам это понадобится.
- Был прост в настройке и "просто работает"; выглядит профессионально.
Я использовал robohelp в течение многих лет.
Это хорошо, но основная технология сейчас очень старая. Кроме того, способ, которым они привязываются к версиям Word, является полной PITA (и заставил меня несколько раз избегать обновлений MS Office).
Мы переходим к MadCap Flare 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 #include (кажется, что никто другой не поддерживает последний). Вы можете найти другие инструменты для разработки XML, которые лучше соответствуют вашим потребностям - Serna - это достаточно дорогое коммерческое предложение.
Docbook обеспечивает большую гибкость с помощью профилирования, что позволяет включать / исключать элементы XML на основе их атрибутов. В качестве примеров использования можно привести несколько иной вывод справки для OS=Windows и OS=Linux. Локализация также поддерживается через профилирование и другие механизмы.
Довольно хорошее введение в Docbook можно найти здесь.
Мы используем Docbook для формата справки и компилируем его в файлы CHM, которые содержат справку только для функций, относящихся к конкретному продукту (т. Е. В версии для предприятий есть функции, которых нет в стандартной или демонстрационной версиях). Соответствующие шаги:
- Запустите шаблоны XSL-профилирования для источника XML (используя, например, XSLTproc).
- Запустите XSL-шаблоны HTML-справки с выводом 1.
- Скомпилируйте выходные HTML-файлы, используя HTML-компилятор справки Microsoft (HHC).
Единственный, кого я знаю, это Latex, один из конвертеров latex2html, а затем несколько приспособлений, чтобы подготовить полученный html для архиватора CHM.
- текст, HTML, CHM, PDF, PS не проблема.
- Преобразование в Word через RTF раньше было катастрофой, не знаю текущего статуса.
- Конвертеры latex 2 html, хотя и несколько, все имеют свои проблемы.
- PDF-файлы выглядят абсолютно великолепно.
- WYSIWYM (через lyx) возможно.
Таким образом, этот архив содержит несколько CHM (в частности, prog,ref и пользовательские части, остальные (rtl,fcl,lcl) генерируются нашим собственным эквивалентом doxygen, fpdoc)
http://www.stack.nl/~marcov/doc-chm.zip
Обратите внимание, что вышеупомянутые CHM сделаны с нашим собственным (переносимым) компилятором CHM. Да, больше нет мастерской.
Документ Lyx в формате PDF и HTML: