Я по образованию филолог. Специализируюсь на разработке пользовательской документации на английском и русском языках. С формулами в документации сталкиваюсь редко и поэтому придерживаюсь общепринятого подхода: набрал в редакторе формул, вставил в документацию и забыл. Но что делать, если у вас в документации много формул, и их нужно донести до пользователя в формате 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) формулы заработали сразу же. О тонкостях расскажу ниже.
Код:
<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
HTML Help (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 на рисунке выше:
- чтобы формула отображалась отдельным блоком, укажите ее в разделителях $$...$$ или \[…\];
- чтобы формула отображалась в строке, используйте разделители \(…\).
Источники
- Статья на Википедии про MathJax.
- Сайт проекта MathJax.
- Статья на сайте Help Information (de) о том, как подключить MathJax к CHM "Compiled Help (CHM) and MathJax".
