В настоящее время мы используем систему под названием AsciiDoc, которая позволяет нам создавать документацию в простой текстовой разметке. Из этого мы можем генерировать несколько выходных форматов. Мы используем только форматы вывода PDF и CHM.
Мне было интересно, если есть альтернатива ЧМ? То, что я ищу, - это то, что можно использовать в автономном режиме (это важно, потому что довольно многие из наших пользователей находятся в очень удаленных местах) с нашим программным обеспечением. Он должен иметь индекс (он может быть таким же простым, как HTML-страница с терминами с гиперссылками), он должен быть доступен для поиска и иметь механизм, позволяющий вызывать определенные записи из кода (аналогично контекстно-зависимой справке).
В этом случае две вещи против PDF:
- Контекстная помощь не вариант
- Обычно документ довольно большой
- PDF больше подходит для печатной документации, чем контекстно-зависимая помощь
Я хотел бы использовать HTML. Единственная проблема с html состоит в том, что я не могу понять, как автоматически обеспечить поиск по ключевым словам (кроме функциональности ctrl + f в браузерах - я хотел бы что-то более очевидное). Я также не могу найти способ автоматически генерировать гиперссылку индекса ключевых слов. Контекстно-зависимая справка будет простой из-за тегов раздела - я мог бы просто передать URL страницы и раздела, которые меня интересуют, в браузер по умолчанию, и эта страница должна загрузиться в правильный раздел.
Мои требования звучат очень похоже на чм - они делают. Я смоделировал свои требования от chm. Единственная причина, по которой я не люблю chm, заключается в том, как код взаимодействует с ним с помощью mapids и тому подобного. Я бы предпочел использовать для хранения простой текстовый список (который автоматически создается для меня), который мой код может использовать для доступа к контекстно-зависимой части документации.
Я предполагаю сценарий, который будет проходить через выходные файлы html и генерировать индексную страницу, которая просто содержит список найденных им ключевых слов. очевидно, должен существовать механизм исключения слов, чтобы игнорировать такие слова, как:, оно, есть и т. д. Эту часть было бы относительно легко написать. Во второй части понадобился бы какой-нибудь скрипт, чтобы собрать базу данных ключевых слов и их расположение в тексте html. Я думаю, что это было бы непростой задачей наряду с предоставлением механизма поиска в браузере.
Любые идеи об альтернативах будут оценены. Я хотел бы использовать вики или набор статических html-страниц, размещенных где-нибудь на веб-сервере, но у нас есть критическое требование автономного использования. Простое размещение html на локальном диске не обеспечивает нас необходимыми поисковыми требованиями.
РЕДАКТИРОВАТЬ:
Я разрабатываю программное обеспечение, которое используется в горнодобывающей промышленности. Многие шахты очень отдаленные и не имеют никакого доступа к Интернету. В pdf, html или chm нет ничего плохого (за исключением того, что он стареет). Если бы я мог отобразить файл PDF в правильном месте (т.е. контекстно-зависимую справку), я бы использовал его. Я почти испытываю желание написать свой собственный - в основном это будет портативная вики. Говоря об этом, если вы предлагаете портативную вики - вы должны думать о конечном пользователе, который может не иметь опыта использования таких инструментов. Это должно быть очень просто. В этом была прелесть chm, работать с болью, но конечным пользователям это нравится.
источник
Ответы:
Если вы готовы написать свою справку в XML-разметке DocBook, а не в HTML, DocBook имеет поддержку для создания WebHelp: http://wiki.docbook.org/WebHelp
Документация по WebHelp также является демонстрационной версией: http://docbook.sourceforge.net/release/xsl/current/webhelp/docs/content/ch01.html
Он предоставляет вам HTML-формат справки, который включает в себя:
источник
Создатели RoboHelp занялись другими делами и вернулись, чтобы сделать лучшую альтернативу. Проверьте MadCap's Flare - он поддерживает множество выходных форматов, генерирует индекс и предоставляет функцию поиска, которая работает локально (через JavaScript).
источник
Мы используем Adobe RoboHelp для создания различных стилей автономной справочной документации. Он предоставляет множество вариантов вывода и интеграции контента. Самое замечательное в этом инструменте - вы можете передать его не разработчикам и получить отличный контент без особых усилий, интегрируясь в ваше решение.
источник
Сам CHM стареет, и Microsoft также перешла к более новым вещам: http://msdn.microsoft.com/en-us/library/bb164608(v=vs.80).aspx
Но если вы действительно хотите избежать преобразования вашей справки в существующую систему и ищите, как обеспечить поиск и поиск по ключевым словам в статических файлах справки, вот две идеи:
добавьте в проект небольшой HTTP-сервер только для локального хоста, чтобы обслуживать веб-сайт с документацией. Проблемы заключаются в том, когда или как запустить / остановить этот HTTP-сервер и / или сохранить его работоспособным. Альтернативой может быть реализация пользовательской схемы URL, но это привязывает вас к одному браузеру и требует гораздо больше работы ( и я могу сказать )
написать поисковик JavaScript. JavaScript в любом браузере становится довольно быстрым и производительным в наши дни. Индекс ключевых слов может быть легко сохранен в JSON, и я запускаю регулярные выражения для локальных файлов с довольно хорошими результатами.
источник
Мы используем RoboHelp в моей компании, и мы желаем, чтобы файлы справки были доступны в автономном режиме, поскольку у нас часто бывают пользователи, выезжающие из областей с сетевым доступом в области без них.
Мы используем некоторые страницы в RoboHelp, чтобы объяснить использование определенных полей на экране. Мы можем иметь всплывающие окна для тех полей, которые появляются после клика. RoboHelp также имеет очень хорошую возможность поиска и автоматически сгенерированный индекс. Мне всегда везло на поиски. Это может не беспокоить вас, но у нас есть возможность обновить документацию, потому что RoboHelp - довольно простая в использовании программа.
источник