Кроссплатформенные инструменты разработки помощи конечным пользователям - PullRequest
Новая
       21

Кроссплатформенные инструменты разработки помощи конечным пользователям

8 голосов
/ 05 июня 2010

Какие хорошие авторские инструменты для создания кроссплатформенных файлов справки для конечных пользователей? (Наше приложение использует каркас Qt, если это что-то меняет.)

Примечание: меня не интересует внутренняя документация по API - для этого мы используем doxygen .

В идеале, решение будет:

  • Позволяет нам управлять всем справочным контентом (текстом, оглавлением, изображениями и т. Д.) В одном месте.
  • Вывод в родные форматы справки. (CHM для Windows - или, по крайней мере, что-то, что мы могли бы подать непосредственно в API справки HTML; не уверен, что «стандартные» форматы справки других платформ.)
  • Достойная поддержка WYSIWYG: легко обрабатывать общий текстовый ввод, изображения, перекрестные ссылки и т. Д., Но мы можем редактировать HTML, когда это необходимо.
  • Текстовый формат файла для проекта справки (XML и т. Д.), Позволяющий создавать версии в Subversion.
  • Любые хуки, которые помогают поддерживать его синхронизацию с реальной базой кода, были бы хорошими. (Возможно, тема справки связана с файлом кода и может проверить Subversion, чтобы увидеть, были ли внесены какие-либо изменения, и пометить тему как «возможно, устаревшую» ... я мечтаю?)
  • Содержимое справки можно локализовать.
  • Не в отличие от коммерческого продукта, но бесплатный вариант был бы неплохим.

Я сделаю это вики и начну с нескольких примеров. Проголосуйте за них, если у вас есть опыт, и оставьте несколько комментариев. Также добавьте дополнительные инструменты.

Ответы [ 6 ]

4 голосов
/ 09 июня 2010

Я только что открыл Сфинкс ; Я думаю, что я влюблен.

  • Лучше, чем WYSIWYG в HTML: reStructuredText
  • Выводит в QtHelp (среди прочего), поэтому будет легко распространять (и интегрировать) в нашем приложении.
  • Пока не уверен насчет локализации, но мы перейдем этот мост, когда нам будет нужно.
  • Был прост в настройке и "просто работает"; выглядит профессионально.
2 голосов
/ 30 августа 2010

Я думаю, 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, которые содержат справку только для функций, относящихся к конкретному продукту (т. Е. Выпуск Enterprise Edition имеет функции, которых нет в стандартной или демонстрационной версиях). Соответствующие шаги:

  1. Запустите шаблоны Profiling XSL для источника XML (используя, например, XSLTproc).
  2. Запустить XSL-шаблоны HTML-справки с выводом 1.
  3. Скомпилируйте выходные HTML-файлы, используя HTML-компилятор справки Microsoft (HHC).
2 голосов
/ 30 августа 2010

Я пользовался robohelp годами.

Хорошо, но базовая технология сейчас очень старая. Кроме того, способ, которым они привязываются к версиям Word, является полной PITA (и заставил меня несколько раз избегать обновлений MS Office).

Мы переходим к вспышке Madcap http://www.madcapsoftware.com/products/flare/robohelp.aspx

1 голос
/ 05 июня 2010
0 голосов
/ 11 июня 2010

Единственный, кого я знаю, это Latex, один из конвертеров latex2html, а затем несколько приспособлений для подготовки готового html к архиватору CHM.

  • текст, html, chm, pdf, ps без проблем.
  • Преобразование в Word через RTF раньше было катастрофой, не знаю текущего статуса.
  • Латексные 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:

pdf: http://www.stack.nl/~marcov/buildfaq.pdf

html: http://www.stack.nl/~marcov/buildfaq/

0 голосов
/ 05 июня 2010
...