Старт из командной строки

OneClickHelp – не является консольным приложением, однако ее можно запустить из командной строки. Формат команды:

“ПолныйПуть\OneClickHelp.exe” /go /p:“ПолныйПутьФайлаПроекта”

Например:

D:\NETProjects\1ch\1ch\bin\OneClickHelp.exe /go /p:" D:\NETProjects\1ch\1ch\1ch-ru.1ch"

Это может быть очень полезным для автоматизации процесса выпуска приложения. Вы компилируете приложение, тестируете его и строите справку, которую также можно протестировать.

Горячие клавиши

Как проверить ссылки в справке

После создания справки или коллекции справок, вы можете проверить работу гиперссылок. Если вы попробуете это сделать вручную, кликая по каждой ссылке, то быстро устанете и, скорее всего, что-то пропустите. Среди бесплатных средств можно отметить программу CheckHelpLinks.

Программа имеет также возможность запуска с параметрами

-f / -fast : select fast mode

-s / -slow : select slow mode

-o / -open : open most recently used chm

-o:"C:\path\xxx.chm" : open specified chm

-w / -work : check file

-x / -export : export reports to default folder

-x:"C:\path\folder" : export to specified folder

-c / -close : close app

Пример запуска программы для проверки документации OneClickHelp:

D:\NETProjects\1ch\1ch\bin\CheckHelpLinks.exe -o:D:\NETProjects\1ch\1ch\Help\1chDoc\1ch-ru\1ch-ru.chm -f -w

Ограничения

1. Длинные имена разделов могут привести к проблемам. Например, заголовок

Общая сумма, выплачиваемая Заказчиком Системному интегратору по настоящему Договору, составляет 1.458.985.44 (Один миллион четыреста пятьдесят восемь тысяч девятьсот восемьдесят пять и 44/100) рубля, в том числе НДС (18%) в сумме 222.557,10 (Двести двадцать две тысячи пятьсот пятьдесят семь и 10/100) рубля и включает в себя:

Может вызвать ошибку  “The path is too long after being fully qualified.  Make sure path is less than 260 characters.Base = System.IO.PathTooLongException”

2. MS WORD при преобразовании документа в html файл формирует только 6 уровней заголовков. Поэтому не используйте больше 6 уровней.

3. Ваш документ всегда должен содержать первый уровень Заголовка.

4. Иерархия заголовков всегда должна быть такой Заголовок 1, Заголовок 2, …

5. Файлы с именем типа %7B5084099d-9270-436d-af65-034af7582479%7D.jpg – удаляются, так как вызывают проблемы при компиляции справки.

6. В именах разделов не используйте символ “/”, так как он при построении aspx сайта приведет к потере этого раздела.

Советы

· Практически никто не читает документацию, в каком либо виде от начала до конца. Пользователь хочет найти ответ на свой вопрос и как можно быстрее. (Я ни разу не видел, чтобы моя жена прочитала хоть какую-нибудь часть инструкции по использованию того или иного прибора. В результате, она стирала не правильно белье в течение трех лет, приговаривая, что-то оно серое!)

· Прежде чем компилировать справку, убедитесь, что ваш документ в режиме Схема документа выглядит, так как Вы задумали, и все ссылки в левой панели правильно отображаются и работают.

· Не используйте ничего кроме стандартных шрифтов, предлагаемых Word – все затем можно переопределить через внешний файл стилей.

· Использовать символ # в именах и путях файлов не рекомендуется, поскольку он зарезервирован для определения закладок в URL.

· Не создавайте большое количество стилей, от них рябит в глазах.

· Пишите короткие секции, чтобы она уместилась в 1-2 экрана Справки, а не в 10, иначе придется скролировать текст, а это сбивает с мысли и утомляет.

· Один параграф для одной мысли. Это легче читать и понимать.

· Используйте короткие предложения. Это позволяет более ясно и однозначно выразить мысль. Сложные предложения, говорят скорее о том, что вы сами не ясно представляете, о чем пишите.

· Пишите одному человеку - не группе. Обращайтесь к индивидуальному читателю, чтобы завоевать его доверие и избежать путаницы.

· Избегайте неоднозначности. Избегайте фраз типа "Возможно, это будет...". Не используйте двойных отрицаний.

· При написании документации используйте максимально простой стиль. Добиться наилучшего представления Справки лучше всего через внешний файл стилей. Печатный вариант документации также лучше получить с помощью фирменного стиля через Темы или подбор стиля в MS Word (Формат/Тема…).

· Примите правильную позу (ержите осанку и не сидите слишком близко к монитору). Освещение в комнате должно быть приблизительно такой же яркости как экран дисплея, но не ярче. Дайте своим глазам отдохнуть каждые 15 минут, посмотрите вдаль 15 секунд, 15 секунд попеременно смотрите вправо-влезо-верх-вниз и/или сделайте круговые движения глазами.

· Через 45-50 минут встаньте, пройдитесь, разомнитесь.

Вопросы-ОТветы (ВОТ)

Где можно подробнее почитать про форматы Справки (Help)?

Самый большой и исчерпывающий ресурс - http://www.helpware.net/FAR/help/hh_start.htm.

Как защитить содержимое справки от копирования, печати и пр.?

Это возможно, например, с помощью программы - HTML Password Lock. Правда в ряде случаев пропадает возможность поиска.

Характеристики работы программы по времени

Преобразование Word > СhmHelp на PC 3 ГГц с 1Гб памяти

Чем так интересен компилированный Help еще?

Регулярно я читаю статьи в инете и сохраняю их в папках по теме. Еще чаще мне попадают статьи, которые мне точно интересны, но нет времени их сразу почитать, также периодически попадают e-book, интересные исходные коды и пр., пр., так что получается почти мусорная свалка. Ночью все мои интересующие меня папки сканируются и по ним строятся справки, справки объединяются в коллекции. Что-то найти для меня быстрее и проще. В общем, почти для всех видов хранения информации я в итоге использую коллекцию компилированных справок.

Ошибка при нажатии F1 – Справка зависает и выдает окно выбора.

Это иногда случается, если в файле .hhk (индексном) есть “почти” две одинаковые записи.
            <LI> <OBJECT type="text/sitemap">
            <param name="Name" value="Простое название параграфа">
            <param name="Local" value="zzk\1zzl_Prostoe nazvanie paragrafa.htm">
            </OBJECT>

            <LI> <OBJECT type="text/sitemap">
            <param name="Name" value="Простое название параграфа">
            <param name="Local" value="zzk\1zzl_Prostoe nazvanie paragrafa.htm#TTbtnTest">
Измените, где вам удобно одно из полей ="Name" value="…

Ошибка Fatal Execution Engine Error (0x7927e03e)

Данная ошибка возникает, если имеются какие-то проблемы с .Net Framework 1.1

Setup Error Failed to load resources from resource file Please check your Setup

Встретилось однажды для Windows 2000 – и было устранено установкой SP1 для .Net Framework 1.1.

В общем случае вот примерно, что пишут об этой проблеме.

It caused my service to crash. I did some research in several newsgroup (since the log doesn't really help to find the source of the problem) and I found many people facing this problem in different contexts but no solution. Sometimes it seems to be OS related, sometimes .Net framework versions related, culture

related, binding related, polling related ...

Does anybody have any clue of the reason this error shows up?

Ошибка Не удается открыть файл: mk:@MSITStore:xxx.chm.

Одна из причин, если вы вставляете изображение не как Аппаратно-независимое изображение.

При построении справки, некоторые страницы выглядят как абракадабра?

Это происходит при преобразовании набора папок в справку (dir 2 chm) из-за того, что эти страницы имеют кодировку Unicode. Перед преобразованием Dir в Help (dir2chm) перекодируйте эти файлы в кодировку ANSI.

Как преобразовать chm в pdf (chm 2 pdf, chm to pdf) с сохранением ссылок?

OneClickHelp преобразует chm в doc ( chm 2 doc, chm to doc), далее в Word вы можете сохранить файл в формате pdf с сохранением ссылок.

Как переделать книги в формате cmh в формат txt (chm в txt)?

OneClickHelp преобразует chm в doc ( chm 2 doc, chm to doc), далее в Word вы можете сохранить файл в формате txt.

Как конвертировать RTF в CHM с сохранением всех ссылок?

OneClickHelp преобразует rtf в chm ( rtf 2 chm, rtf to chm) с сохранением всех ссылок. См. раздел Интерфейс программы.

Как можно разбить chm файл на обычные html (htm) страницы?

OneClickHelp из CHM создаст набор html файлов ( chm в htm, chm в html, chm to html), один большой html файл, включающий в себя все другие (с сохранением гиперссылок) и word файл, который можно преобразовать в любой формат.

Как распечатать CHM?

Обычно в справке есть кнопка Печать, и она печатает текущую страницу. Если такой кнопки нет, то можно преобразовать chm в doc и из Word напечатать.

Как изменить шрифт в chm?

В chm нельзя изменить шрифт? Если это не предусмотрено было при компиляции справки. Можно конвертировать chm в doc ( chm 2 doc, chm to doc), далее в Word вы можете напечатать.

Как сделать инкрементное обновление к CHM файлу?

Chm-файлы могут ссылаться на другие chm файлы, например. Разбейте ваш проект так, чтобы создавались несколько chm файлов. Тогда достаточно будет передавать только изменённые chm файлы, т.е. только часть.

Как сделать файл справки chm?

Надо создать документацию, например, в Word, а затем преобразовать doc в chm.

Примеры

При установке, программа создает каталог

XP - C:\Documents and Settings\All Users\Documents\1ch\.

W7, Vista C:\Пользователи\Общие\Общие документы\1ch

В каталоге находится пример документации OneClickHelp со всеми необходимыми файлами, в том числе Word документация OneClickHelp (1ch-ru.doc).

1ch-ru.1ch – файл проекта для русской версии документации

1ch-en.1ch – для английской версии документации

1ch-ru.cmd – командный файл для создания русской справки

1ch-en.cmd – командный файл для создания английской справки

1ch-ru.docx – документация на русском языке

1ch-ru.docx – документация на английском языке

1chCreateImages.cmd – командный файл, запускаемый программой OneClickHelp после преобразования Html2Htmls

_FolderName.txt – файл имен для русской справки

_FolderNameEn.txt – файл имен для английской справки

Внимание: Если вы обычный пользователь, у вас может быть не достаточно прав для работы с файлами в этой папке. Попросите своего администратора, чтобы он вам дал права на запись в этой папке.

Подключение справки

Самый большой и исчерпывающий ресурс - http://www.helpware.net/FAR/help/hh_start.htm.

Для VB.Net.

1. Добавляем на форму HelpProvider и называем его HelpProvider.

2. Определяем его свойства

Добавляем строки вида
При загрузке формы (реакция для клавишы F1)

HelpProvider.HelpNamespace = Application.StartupPath & "\" & AssName & ".chm"

HelpProvider.SetHelpNavigator(Me, HelpNavigator.TableOfContents)

При определении меню

Private Sub mnuHelpChm_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles mnuHelpChm.Click

Help.ShowHelp(Me, HelpProvider.HelpNamespace)

End Sub

Private Sub mnuIndexHelp_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles mnuIndexHelp.Click

' Show index of the help file.

Help.ShowHelpIndex(Me, HelpProvider.HelpNamespace)

End Sub

Private Sub mnuSearchHelp_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles mnuSearchHelp.Click

' Show the search tab of the help file.

Help.ShowHelp(Me, HelpProvider.HelpNamespace, HelpNavigator.Find, "")

End Sub

При инициализации программы для определения контекстной помощи

HelpProvider.SetHelpKeyword(txtFileFolder, Strings.TTtxtFileFolder)

HelpProvider.SetHelpNavigator(txtFileFolder, HelpNavigator.KeywordIndex)

3. В классе Strings

Public TTtxtFileFolder As String = "Путь для Word файла. Тащите сюда файл или используйте кнопку."

Используем класс Strings для определения свойств контрола, таких как Text и ToolTip. Это удобно, так как находится в одном месте, легко может быть сопоставлено с другими описаниями, а также дает возможность относительно легкого перевода на другой язык. Пример файла Strings приведен в приложение 3.

4. ToolTip определяются так

ToolTip.SetToolTip(txtFileFolder, Strings.TTtxtFileFolder)

Таким образом, и для контекстной справки и для ToolTip используем одно определение. Нет разницы, нет расхождений. Скажу больше, блок комментариев в тексте программы может выглядит следующим образом

''' --------------------------------------------------------------------*

''' <summary>Путь для Word файла. Тащите сюда файл или используйте кнопку.</summary>

''' <history>[DPosudin] 7 июля 2005 г. 17:19:00</history>

''' --------------------------------------------------------------------*

Private Sub txtFileFolder_DragEnter(ByVal sender As Object, ByVal e As System.Windows.Forms.DragEventArgs) Handles txtFileFolder.DragEnter

Это означает, что только один раз в теге <summary> описан метод и это описание используется четырежды – как ToolTip, как индекс для контекстной подсказки, в документации и в описании метода.

Для Access а также других языков, см. статьи фирмы Indigoware Ltd.