Блог технического писателя Ильи Жукова

Формулы в HTML Help (CHM)

Я по образованию филолог. Специализируюсь на разработке пользовательской документации на английском и русском языках. С формулами в документации сталкиваюсь редко и поэтому придерживаюсь общепринятого подхода: набрал в редакторе формул, вставил в документацию и забыл. Но что делать, если у вас в документации много формул, и их нужно донести до пользователя в формате CHM? И при этом вы хотите, чтобы в проекте формулы были редактируемыми, а в документации выглядели профессионально и так, как вы их набрали. В этой статье я расскажу, как подключить js-библиотеку MathJax в HTML Help (CHM).

 

Формулы и HAT-программы

Для работы с формулами в HAT-программах предусмотрены редакторы формул. В платной программе Help and Manual редактор формул был добавлен, начиная с версии 8. Редактор формул продвинутый: в нем поддерживается вставка кода формул из LaTeX с проверкой выражений. В бесплатной версии HelpNDoc редактор формул появился, начиная с версии 8.5. Он гораздо проще, но позволяет набирать основные математические выражения, если не забывать о переключении экранной клавиатуры клавишей Shift.

В обеих программах используется общий подход. В проекте формулы хранятся в редактируемом виде. В выходные документы формулы экспортируются в виде рисунков. Аналогично работает программа LATEX2HTML. Так пользователь в любом формате гарантированно видит формулу в том виде, в котором ее набрал автор.

Единственный минус такого общепринятого подхода: не очень высокое качество рисунка, оптимизированного для сети Интернет. Если у вас формул не много, то имеет смысл набрать формулу в редакторе формул, например в MS Word, подобрать шрифт и его размер так, чтобы снимок получился качественный.

В бесплатных программах для сборки CHM-файлов, таких как Microsoft HTML Help Workshop, KEL CHM Creator и других подобных программах редактора формул нет.

 

Формулы в HTML

Для отображения формул в HTML Американское математическое общество разработало в 2009 году MathJax. Это бесплатная библиотека JavaScript, отображающая математические выражения в большинстве популярных браузеров с использованием разметки MathML, LaTeX и ASCIIMathML. У разработчика есть инструкция, как использовать данную библиотеку на сайтах. Добавляем указанный код, и MathJax версии 3 работает в WebHelp без проблем. В проекте Help and Manual (Configuration \ HTML Page Templates \ Default \ HTML Source Code) формулы заработали сразу же. О тонкостях расскажу ниже.

 

формулы в проекте Help and Manual

 

Код:

<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

 

В CHM в таком виде код не работает. Код, приведенный разработчиком для подключения MathJax версии 2, не работает ни в CHM, ни в WebHelp, хотя в документации сказано, что версия 2 поддерживает устаревшие браузеры, плоть до IE 6.

 

Формулы в CHM

Решение было найдено на сайте Help Information (de). Меняем конфигурацию на общую ?config=TeX-AMS-MML_HTMLorMML, и MathJax версии 2 работает и в WebHelp и в CHM.

 

пример рабочего кода

 

Код:

<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
<script async src="https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

 

 HTML Help (CHM) в Windows 10

 

CHM в Windows 10

 

 HTML Help (CHM) в Windows 7

CHM в Windows 7

 

Тонкости

1. Старая ссылка для загрузки версии библиотеки из CDN (cdn.mathjax.org) пока работает и загружает последнюю версию MathJax, подходящую для WebHelp и CHM:

<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

2. Актуальность новой ссылки (cdn.jsdelivr.net) желательно проверять.

3. Если вы используете бесплатные программы Microsoft HTML Help Workshop, KEL CHM Creator и т.п. и пишете HTML самостоятельно, добавьте в HTML-код мета-тег X-UA-Compatible, управляющий режимом отображения страниц:

<meta http-equiv="X-UA-Compatible" content="IE=11">

Формулы в CHM корректно отображаются со значениями тега IE=10, IE=11, IE=Edge.

Мета-тег X-UA-Compatible рекомендуется располагать как можно выше в блоке, чтобы страница загружалась быстрее.

4. И, разумеется: чтобы в CHM работал JavaScript, в настройках IE нужно включить скрипты и сценарии.

 

Минусы решения

Чтобы формулы корректно отображались при помощи MathJax, нужно подключение к сети Интернет. Иначе вместо формул будет отображаться код.

 

код формул

 

Разметка

Прокомментирую примеры разметки формул из LaTeX на рисунке выше:

  • чтобы формула отображалась отдельным блоком, укажите ее в разделителях $$...$$ или \[\];
  • чтобы формула отображалась в строке, используйте разделители \(\).

 

Источники

  1. Статья на Википедии про MathJax.
  2. Сайт проекта MathJax.
  3. Статья на сайте Help Information (de) о том, как подключить MathJax к CHM "Compiled Help (CHM) and MathJax".

 

Добавить комментарий

Последние статьи

Подключение таблицы стилей к проекту Hel…

При работе с форматами, основанными на HTML, для оформления контента в документах можно использовать каскадные таблицы стилей, cascading style sheets или CSS. Данная т...

Читать полностью...

Импорт документов MS Word в Help+Manual…

Часто технический писатель получает исходные данные от аналитиков, разработчиков, тестировщиков, маркетологов и других специалистов в форматах DOC, DOCX и RTF (реже, и...

Читать полностью...

Поиск в WebHelp находит удаленные раздел…

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

Читать полностью...

Контекстная справка в приложениях Window…

Понятие контекстной или контекстно-зависимой справки (от англ. context-sensitive help) появилось в 1987 году с выходом формата WinHelp. Изначально контекстная справка ...

Читать полностью...

Как поддерживать скриншоты в актуальном …

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

Читать полностью...

Книга «Разработка технической документац…

Уважаемые коллеги! Если вам нужно быстро освоить разработку документации по ГОСТ, рекомендую обратить внимание на книгу В.А. Глаголева «Разработка технической документ...

Читать полностью...

Перевод выходных документов в Help and M…

Выбрав русский язык и русскую кодировку в настройках проекта Help and Manual, многие авторы после первой сборки удивляются, увидев в выходных документах английские сло...

Читать полностью...

Размер и расположение окна CHM при перво…

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

Читать полностью...

Рваные края скриншотов в Help and Manual…

Многие платные редакторы скриншотов, например, SnagIt, FastStone Capture и др., умеют создавать эффект рваных краев. В сети Интернет можно найти множество видеоуроков ...

Читать полностью...
новое в Help and Manual 9

Новое в Help and Manual 9

23 ноября 2022 года компания EC Software к 25-летнему юбилею выпустила 9-ю версию программного комплекса Help and Manual (выходит c 1997 года). Комплект шаблонов Premi...

Читать полностью...

Создание CHM-справки в бесплатной програ…

KEL CHM Creator — это «новая» хорошо забытая программа, выпущенная в 2012 году, предназначенная для создания и декомпиляции CHM-файлов. Программа не требовательна к ре...

Читать полностью...

KEL CHM Creator — бесплатная программа д…

Если вам нужно создать CHM-файл, и вы больше не хотите пользоваться глючной программой HTML Help Workshop, тогда KEL CHM Creator — это ваш вариант. Программа позволяет...

Читать полностью...
ключевые слова

Ключевые слова в Help+Manual…

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

Читать полностью...

HTML Help Workshop – бесплатная программ…

В 1997 году Microsoft выпустила новый формат справки, HTML Help (CHM), а также бесплатную программу для создания и редактирования справки в этом формате — HTML Help Wo...

Читать полностью...

HelpNDoc — бесплатная альтернатива Help+…

Еще одной альтернативой RoboHelp и Help&Manual является программа HelpNDoc от французского разработчика, компании IBE Software. Это практически полный аналог HelpS...

Читать полностью...

HelpSmith — достойная альтернатива Help+…

Продолжая тему средств разработки справки и пользовательской документации, нельзя не рассказать о программе HelpSmith. Она работает по принципу единого источника и под...

Читать полностью...

Все о справке и документации для пользователей!

Следить за новыми статьями:

© Илья Жуков, 2019-2024. Охраняется законом об авторском праве.