Я по образованию филолог. Специализируюсь на разработке пользовательской документации на английском и русском языках. С формулами в документации сталкиваюсь редко и поэтому придерживаюсь общепринятого подхода: набрал в редакторе формул, вставил в документацию и забыл. Но что делать, если у вас в документации много формул, и их нужно донести до пользователя в формате 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. У разработчика есть инструкция, как использовать данную библиотеку на сайтах (https://www.mathjax.org/#gettingstarted). Добавляем указанный код, и MathJax версии 3 работает в WebHelp без проблем. В проекте Help and Manual (Configuration \ HTML Page Templates \ Default \ HTML Source Code) формулы заработали сразу же. О тонкостях расскажу ниже.
Примеры кода можно скопировать в статье "Формулы в HTML Help (CHM)" на моем сайте.
В CHM в таком виде код не работает. Код, приведенный разработчиком для подключения MathJax версии 2, не работает ни в CHM, ни в WebHelp, хотя в документации сказано, что версия 2 поддерживает устаревшие браузеры, плоть до IE 6.
Формулы в CHM
Решение было найдено на сайте Help Information (de).
Меняем конфигурацию на общую ?config=TeX-AMS-MML_HTMLorMML, и MathJax версии 2 работает и в WebHelp и в CHM.
Примеры кода можно скопировать в статье "Формулы в HTML Help (CHM)" на моем сайте.
Тонкости
- Старая ссылка для загрузки версии библиотеки из CDN (cdn.mathjax.org) пока работает и загружает последнюю версию MathJax, подходящую для WebHelp и CHM. Примеры кода можно скопировать в статье "Формулы в HTML Help (CHM)" на моем сайте.
- Актуальность новой ссылки (cdn.jsdelivr.net) желательно проверять.
- Если вы используете бесплатные программы Microsoft HTML Help Workshop, KEL CHM Creator и т.п. и пишете HTML самостоятельно, добавьте в HTML-код мета-тег X-UA-Compatible, управляющий режимом отображения страниц. Формулы в CHM корректно отображаются со значениями тега IE=10, IE=11, IE=Edge. Мета-тег X-UA-Compatible рекомендуется располагать как можно выше в блоке <head>, чтобы страница загружалась быстрее.
- И, разумеется: чтобы в CHM работал JavaScript, в настройках IE нужно включить скрипты и сценарии.
Минусы решения
Чтобы формулы корректно отображались при помощи MathJax, нужно подключение ПК к сети Интернет. Иначе вместо формул будет отображаться код.
Разметка
Прокомментирую примеры разметки формул из LaTeX на рисунке выше:
- чтобы формула отображалась отдельным блоком, укажите ее в разделителях $$...$$ или \[…\];
- чтобы формула отображалась в строке, используйте разделители \(…\).
Источники:
- Статья на сайте Help Information (de) о том, как подключить MathJax к CHM
"Compiled Help (CHM) and MathJax"
#chm
#htmlhelp
#mathjax
#helpandmanual
#helpndoc
#kelchmcreator
#microsofthtmlhelpworkshop
#формулывchm
#формулывhtml