Альтернативы HTML-справке

12

В настоящее время мы используем систему под названием AsciiDoc, которая позволяет нам создавать документацию в простой текстовой разметке. Из этого мы можем генерировать несколько выходных форматов. Мы используем только форматы вывода PDF и CHM.

Мне было интересно, если есть альтернатива ЧМ? То, что я ищу, - это то, что можно использовать в автономном режиме (это важно, потому что довольно многие из наших пользователей находятся в очень удаленных местах) с нашим программным обеспечением. Он должен иметь индекс (он может быть таким же простым, как HTML-страница с терминами с гиперссылками), он должен быть доступен для поиска и иметь механизм, позволяющий вызывать определенные записи из кода (аналогично контекстно-зависимой справке).

В этом случае две вещи против PDF:

  1. Контекстная помощь не вариант
  2. Обычно документ довольно большой
  3. PDF больше подходит для печатной документации, чем контекстно-зависимая помощь

Я хотел бы использовать HTML. Единственная проблема с html состоит в том, что я не могу понять, как автоматически обеспечить поиск по ключевым словам (кроме функциональности ctrl + f в браузерах - я хотел бы что-то более очевидное). Я также не могу найти способ автоматически генерировать гиперссылку индекса ключевых слов. Контекстно-зависимая справка будет простой из-за тегов раздела - я мог бы просто передать URL страницы и раздела, которые меня интересуют, в браузер по умолчанию, и эта страница должна загрузиться в правильный раздел.

Мои требования звучат очень похоже на чм - они делают. Я смоделировал свои требования от chm. Единственная причина, по которой я не люблю chm, заключается в том, как код взаимодействует с ним с помощью mapids и тому подобного. Я бы предпочел использовать для хранения простой текстовый список (который автоматически создается для меня), который мой код может использовать для доступа к контекстно-зависимой части документации.

Я предполагаю сценарий, который будет проходить через выходные файлы html и генерировать индексную страницу, которая просто содержит список найденных им ключевых слов. очевидно, должен существовать механизм исключения слов, чтобы игнорировать такие слова, как:, оно, есть и т. д. Эту часть было бы относительно легко написать. Во второй части понадобился бы какой-нибудь скрипт, чтобы собрать базу данных ключевых слов и их расположение в тексте html. Я думаю, что это было бы непростой задачей наряду с предоставлением механизма поиска в браузере.

Любые идеи об альтернативах будут оценены. Я хотел бы использовать вики или набор статических html-страниц, размещенных где-нибудь на веб-сервере, но у нас есть критическое требование автономного использования. Простое размещение html на локальном диске не обеспечивает нас необходимыми поисковыми требованиями.

РЕДАКТИРОВАТЬ:

Я разрабатываю программное обеспечение, которое используется в горнодобывающей промышленности. Многие шахты очень отдаленные и не имеют никакого доступа к Интернету. В pdf, html или chm нет ничего плохого (за исключением того, что он стареет). Если бы я мог отобразить файл PDF в правильном месте (т.е. контекстно-зависимую справку), я бы использовал его. Я почти испытываю желание написать свой собственный - в основном это будет портативная вики. Говоря об этом, если вы предлагаете портативную вики - вы должны думать о конечном пользователе, который может не иметь опыта использования таких инструментов. Это должно быть очень просто. В этом была прелесть chm, работать с болью, но конечным пользователям это нравится.

bluebill
источник
1
Что не так с использованием стандартного инструмента, такого как браузеры в механизме поиска сборки. Пользователи понимают, что это намного более проверено в бою, чем ваш пользовательский механизм поиска, а пользовательский интерфейс более знаком пользователям, чем ваша поисковая система
Raynos
1
@Raynos Браузерная помощь, как правило, очень плохая. Справочная система по умолчанию в VS2010 является хорошим примером этого.
MetalMikester

Ответы:

4

Если вы готовы написать свою справку в XML-разметке DocBook, а не в HTML, DocBook имеет поддержку для создания WebHelp: http://wiki.docbook.org/WebHelp

Документация по WebHelp также является демонстрационной версией: http://docbook.sourceforge.net/release/xsl/current/webhelp/docs/content/ch01.html

Он предоставляет вам HTML-формат справки, который включает в себя:

  • Полнотекстовый поиск с:
    • Поддержка Stemming для английского, французского и немецкого языков. Поддержка стемминга может быть добавлена ​​для других языков путем реализации стеммера.
    • Поддержка китайского, японского и корейского языков с использованием кода из поисковой системы Lucene.
    • Подсветка поиска, показывающая, где искомый термин появляется в результатах.
    • Результаты поиска могут включать краткое описание цели.
  • Панель оглавления со складным деревом оглавления.
  • Автосинхронизация панели содержимого и оглавления.
  • Содержание и область поиска реализованы без использования набора фреймов.
  • Файл Ant build.xml для генерации вывода.
robstel
источник
1
Это в основном то, что делает AsciiDoc.
Bluebill
4

Создатели RoboHelp занялись другими делами и вернулись, чтобы сделать лучшую альтернативу. Проверьте MadCap's Flare - он поддерживает множество выходных форматов, генерирует индекс и предоставляет функцию поиска, которая работает локально (через JavaScript).

Росс Паттерсон
источник
2

Мы используем Adobe RoboHelp для создания различных стилей автономной справочной документации. Он предоставляет множество вариантов вывода и интеграции контента. Самое замечательное в этом инструменте - вы можете передать его не разработчикам и получить отличный контент без особых усилий, интегрируясь в ваше решение.

Карло Куйп
источник
1

Сам CHM стареет, и Microsoft также перешла к более новым вещам: http://msdn.microsoft.com/en-us/library/bb164608(v=vs.80).aspx

Но если вы действительно хотите избежать преобразования вашей справки в существующую систему и ищите, как обеспечить поиск и поиск по ключевым словам в статических файлах справки, вот две идеи:

  • добавьте в проект небольшой HTTP-сервер только для локального хоста, чтобы обслуживать веб-сайт с документацией. Проблемы заключаются в том, когда или как запустить / остановить этот HTTP-сервер и / или сохранить его работоспособным. Альтернативой может быть реализация пользовательской схемы URL, но это привязывает вас к одному браузеру и требует гораздо больше работы ( и я могу сказать )

  • написать поисковик JavaScript. JavaScript в любом браузере становится довольно быстрым и производительным в наши дни. Индекс ключевых слов может быть легко сохранен в JSON, и я запускаю регулярные выражения для локальных файлов с довольно хорошими результатами.

Стейн Сандерс
источник
Я думал в духе поисковой системы javascript. Мне придется сделать еще несколько исследований.
bluebill
0

То, что я ищу, - это то, что можно использовать в автономном режиме (это важно, потому что довольно многие из наших пользователей находятся в очень удаленных местах) с нашим программным обеспечением.

Мы используем RoboHelp в моей компании, и мы желаем, чтобы файлы справки были доступны в автономном режиме, поскольку у нас часто бывают пользователи, выезжающие из областей с сетевым доступом в области без них.

Он должен быть доступен для поиска и иметь механизм, позволяющий вызывать определенные записи

Мы используем некоторые страницы в RoboHelp, чтобы объяснить использование определенных полей на экране. Мы можем иметь всплывающие окна для тех полей, которые появляются после клика. RoboHelp также имеет очень хорошую возможность поиска и автоматически сгенерированный индекс. Мне всегда везло на поиски. Это может не беспокоить вас, но у нас есть возможность обновить документацию, потому что RoboHelp - довольно простая в использовании программа.

Эндрю Шипе
источник