В каком виде удобнее держать оглавление HTML Help (CHM), чтобы параллельно и без лишних операций поддерживать одну и ту же документацию как на сайте, так и в отдельно распространяемом CHM-файле?
HTML-страницы там, как известно, одни и те же, а вот оглавление для CHM описывается в TOC-файле, в XML специального формата. То есть, нужны средства автопреобразования либо из TOC в HTML-оглавление для сайта, либо обратно, либо из чего-то третьего и в TOC, и в HTML-оглавление.
Здравствуйте, Евгений Музыченко, Вы писали:
ЕМ>Есть такое?
Я так понимаю, у вас есть готовый статический сайт с навигацией, и вы просто хотите запаковать его в CHM? Если да, то увы простого способа сделать навигацию там и там я не знаю.
Мы делали иначе — собирали документацию в MAML-формате, обрабатывали с помощью Sandcastle Help File Builder (SHFB) и выдавали все нужные нам форматы — и сайт и CHM.
Но это, по сути то, что предлагают многие платные систем документирования — делаешь всё у них, в их редакторе, а потом генерируешь нужные форматы.
Плюс SHFB
— бесплатный
— открытый
— есть сторонние плагины (например, сгенерировать документацию по XSD)
— работает как проект в студии или как standalone приложение
— сборка построена на MSBuild — легко включить в релиз-процесс
Если заинтересуетесь, взгляните на документацию http://ewsoftware.github.io/SHFB/ — она как раз собрана в самом SHFB, а исходный проект (из которого это собиралось) тут
P.S. Только имейте в виду, что исходно Sandcastle делался для генерации документации по XML-комментариям из C# и VB.Net поэтому исходно там много функционала именно для этих нужд.
Здравствуйте, Михаил Романов, Вы писали:
МР>Я так понимаю, у вас есть готовый статический сайт с навигацией, и вы просто хотите запаковать его в CHM?
Наоборот — есть исходники для изготовления CHM из HHP/HHC стандартным компилятором от MS. Хочется то же самое выкладывать на сайте, но перспектива заниматься еще и ручной синхронизацией оглавлений расстраивает. По сути, только в оглавлениях и дело, остальное — просто набор файлов.
МР>Мы делали иначе — собирали документацию в MAML-формате, обрабатывали с помощью Sandcastle Help File Builder (SHFB) и выдавали все нужные нам форматы — и сайт и CHM.
Спасибо, посмотрю SHFB, но сложноват, на первый взгляд.
Здравствуйте, Евгений Музыченко, Вы писали: ЕМ>В каком виде удобнее держать оглавление HTML Help (CHM), чтобы параллельно и без лишних операций поддерживать одну и ту же документацию как на сайте, так и в отдельно распространяемом CHM-файле? ЕМ>HTML-страницы там, как известно, одни и те же, а вот оглавление для CHM описывается в TOC-файле, в XML специального формата. То есть, нужны средства автопреобразования либо из TOC в HTML-оглавление для сайта, либо обратно, либо из чего-то третьего и в TOC, и в HTML-оглавление. ЕМ>Есть такое?
У меня сайт генерировался в HTML и CHM препроцессором (Template Toolkit).
Болванка для оглавления(?) CHM выглядела так
[% MACRO menu_help_list BLOCK %]
<UL>
[% FOREACH el = navigation.siblings %]
<LI><OBJECT type="text/sitemap">
<param name="Name" value="[% FILTER html %][% el.1 %][% END %]">
<param name="Local" value="[% root %][% navigation.current_dir %][% el.0 %]">
</OBJECT>
[% END %]
</UL>
[% END %]
[% BLOCK menu_help_list1 %]
[% local__open=0 %]
[% FOREACH el = navigation.siblings %]
[% IF el.2==id -%][% IF local__open==0 %][% local__open=1 %]<UL>[% END %]
<LI><OBJECT type="text/sitemap">
<param name="Name" value="[% FILTER html %][% el.1 %][% END %]">
<param name="Local" value="[% root %][% navigation.current_dir %][% el.0 %]">
</OBJECT>
[% content %]
[%- END %]
[% END %][% IF local__open==1 %]</UL>[% END %]
[% END %]
[% PROCESS misc %]
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
</HEAD><BODY>
<OBJECT type="text/site properties">
<param name="ImageType" value="Folder">
</OBJECT>
[%# ------------------------------------------------------------- %]
[% PROCESS news %]
[% news_text = menu_help_list %]
[%# ------------------------------------------------------------- %]
[% PROCESS license %]
[% license_text = menu_help_list %]
[%# ------------------------------------------------------------- %]
[% PROCESS examples %]
[% samples_text = menu_help_list %] [%# используется в doc_text_x %]
[%# ------------------------------------------------------------- %]
[% PROCESS doc %]
[% doc_text__examples = BLOCK %]
[% WRAPPER menu_help_list1 id="examples" %][% samples_text %][% END %]
[% END %]
[% doc_text__mssql = BLOCK %]
[% WRAPPER menu_help_list1 id="mssql" %][% END %]
[% END %]
[% doc_text__ibp_props = BLOCK %]
[% WRAPPER menu_help_list1 id="ibp_props" %][% END %]
[% END %]
[% doc_text__other = BLOCK %]
[% WRAPPER menu_help_list1 id="" %][% END %]
[% END %]
[%# ------------------------------------------------------------- %]
[% PROCESS root %]
<UL>
[% FOREACH el = navigation.siblings %]
<LI><OBJECT type="text/sitemap">
<param name="Name" value="[% el.1 %]">
[% IF el.0 == "purchase.html" ||
el.0 == "download.html" %]
<param name="Local" value="[% www_root %][% el.0 %]">
[% ELSE %]
<param name="Local" value="[% root %][% navigation.current_dir %][% el.0 %]">
[% END %]
</OBJECT>
[% SWITCH el.0 %]
[% CASE "news.html" %]
[% news_text %]
[% CASE "license.html" %]
[% license_text %]
[% CASE "documentation.html" %]
[% doc_text__examples %]
<UL>
<LI><OBJECT type="text/sitemap">
<param name="Name" value="[% c_help_topic_title__doc__IBProvider_And_MSSQL_Services %]">
<param name="Local" value="[% root %][% navigation.current_dir %]documentation.html#mssql">
</OBJECT>
[% doc_text__mssql %]
</UL>
<UL>
<LI><OBJECT type="text/sitemap">
<param name="Name" value="[% c_help_topic_title__doc__IBProvider_Objects_Properties %]">
<param name="Local" value="[% root %][% navigation.current_dir %]documentation.html#ibp_props">
</OBJECT>
[% doc_text__ibp_props %]
</UL>
[% doc_text__other %]
[% END %]
[% END %]
</UL>
</BODY></HTML>
Но потом (в 2015-ом) сайт переехал на WP и на CHM был положен болт
-- Пользователи не приняли программу. Всех пришлось уничтожить. --
Здравствуйте, Коваленко Дмитрий, Вы писали:
КД>У меня сайт генерировался в HTML и CHM препроцессором (Template Toolkit).
Похоже, мне будет проще придумать формат исходного дерева, и генерить оглавления скриптом. Думалось, что задача вполне себе типовая, должны быть готовые решения, но нашлись только комплексные, вроде HelpNDoc.
