Альтернативується у довідці HTML

В даний час ми використовуємо систему під назвою AsciiDoc, яка дозволяє нам створювати документацію в простому розмітці тексту. З цього ми можемо генерувати кілька форматів виводу Ми використовуємо лише вихідний формат pdf та chm.

Мені було цікаво, чи є альтернатива chm? Що я шукаю - це те, що можна використовувати в режимі офлайн (це важливо, оскільки досить багато наших користувачів знаходяться у дуже віддалених місцях) з нашим програмним забезпеченням. Він повинен мати індекс (він може бути таким же простим, як html-сторінка із гіперпосиланими термінами), його слід шукати, і він повинен мати механізм, який дозволяє викликати конкретні записи з коду (подібно до контекстно-чутливої ​​допомоги).

Дві речі, які в цьому випадку є проти PDF:

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

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

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

Я передбачаю сценарій, який проходитиме через вихідні файли html та генерує індексну сторінку, яка просто містить перелік ключових слів, які він знайшов. Очевидно, має бути механізм виключення слів, щоб ігнорувати слова типу: the, it, is тощо. Цю частину було б досить легко написати. Друга частина потребує певного сценарію, щоб зібрати базу даних ключових слів та їх розташування в тексті html. Я думаю, це було б складною частиною разом із забезпеченням механізму пошуку в браузері.

Будь-які ідеї щодо альтернатив були б вдячні. Я хотів би використовувати вікі або набір статичних html-сторінок, розміщених десь на веб-сервері, але у нас є критична вимога використання в автономному режимі. Просто розміщення html на локальному диску не забезпечує нам необхідних вимог пошуку.

Редагувати:

Я розробляю програмне забезпечення, яке використовується гірничодобувною промисловістю. Багато мін дуже віддалені і не мають доступу до Інтернету жодним змістовно. Немає нічого поганого у форматі pdf чи html чи chm (крім того, що воно старіє). Якби я міг відобразити PDF-файл у потрібному місці (тобто, залежно від контексту), я би використовував його. Я майже спокушаюся написати своє - в основному це буде портативний вікі. Якщо говорити про це, якщо ви пропонуєте портативну вікі - вам доведеться думати про кінцевого користувача, який може не мати досвіду використання таких інструментів. Він повинен бути мертвим простим. Це була краса chm, болісно працювати, але кінцевим споживачам це подобається.

Якщо ви готові надати вашу допомогу в розмітці DocBook XML, а не HTML, DocBook має підтримку для створення WebHelp: http://wiki.docbook.org/WebHelp

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

Він надає веб-формат довідки HTML, який включає:

• Повний текст пошуку за допомогою:
  • Підтримка створіння для англійської, французької та німецької мов. Підтримка створіння може бути додана для інших мов, застосувавши ствол.
  • Підтримка китайської, японської та корейської мов із використанням коду з люценської пошукової системи.
  • Виділення пошуку, яке показує, де в результатах відображається шуканий термін.
  • Результати пошуку можуть містити короткі описи цілі.
• Панель вмісту з розбірним деревом TOC.
• Автосинхронізація панелі вмісту та TOC.
• TOC та панель пошуку реалізовані без використання набору кадрів.
• Мурашний файл build.xml для отримання результатів.

Творці RoboHelp перейшли до інших речей і повернулися, щоб зробити кращу альтернативу. Перевірте Flare MadCap - він підтримує різноманітні формати виводу, генерує індекс і постачає функцію пошуку, яка працює локально (через 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 - це досить проста програма.