【背景】
折腾：
【记录】修复用docbook的docbook-xsl-ns-1.77.1生成的webhelp在浏览器中目录列表显示异常的问题
和：
【记录】将docbook的xsl-ns从当前的docbook-xsl-ns-1.77.1升级到docbook-xsl-ns-1.78.1
期间，发现：
对于webhelp来说，由于xls-ns升级了，
编译webhelp的，从之前的ant，改为现在的GNU make了。
所以，需要去：
将之前的，用ant去编译webhelp的过程，改为利用最新的docbook-xsl-ns-1.78.1中的webhelp的内容，
去用make去编译webhelp。
【折腾过程】
1.那就去看看，docbook-xsl-ns-1.78.1中的webhelp中的说明文档，如何编译的。
2.看了看：
D:\tmp\tmp_dev_root\cgwin\home\CLi\develop\docbook\tools\docbook-xsl-ns-1.78.1\webhelp\Makefile.sample
相关webhelp部分是：
webhelp: $(INPUT_XML) copyfiles chunk index
copyfiles:
-rm -rf $(OUTPUT_DIR)
mkdir -p $(OUTPUT_DIR)
cp -r template/common ${OUTPUT_DIR}
test ! -d $(USER_IMAGES_PARENT_DIR)/images/ || cp -r $(USER_IMAGES_PARENT_DIR)/images ${OUTPUT_DIR}/images
cp template/favicon.ico ${OUTPUT_DIR}/
chunk:
xsltproc --xinclude --output xincluded-profiled.xml \
--stringparam profile.arch ${PROFILE.ARCH} \
--stringparam profile.audience ${PROFILE.AUDIENCE} \
--stringparam profile.condition ${PROFILE.CONDITION} \
--stringparam profile.conformance ${PROFILE.CONFORMANCE} \
--stringparam profile.lang ${PROFILE.LANG} \
--stringparam profile.os ${PROFILE.OS} \
--stringparam profile.revision ${PROFILE.REVISION} \
--stringparam profile.revisionflag ${PROFILE.REVISIONFLAG} \
--stringparam profile.role ${PROFILE.ROLE} \
--stringparam profile.security ${PROFILE.SECURITY} \
--stringparam profile.status ${PROFILE.STATUS} \
--stringparam profile.userlevel ${PROFILE.USERLEVEL} \
--stringparam profile.vendor ${PROFILE.VENDOR} \
--stringparam profile.wordsize ${PROFILE.WORDSIZE} \
--stringparam profile.attribute ${PROFILE.ATTRIBUTE} \
--stringparam profile.value ${PROFILE.VALUE} \
../profiling/profile.xsl \
${INPUT_XML}
xsltproc ${OTHER_XSLTPROC_ARGS} xsl/webhelp.xsl xincluded-profiled.xml
rm xincluded-profiled.xml
index:
java \
-DhtmlDir=$(OUTPUT_DIR) \
-DindexerLanguage=en \
-DhtmlExtension=html \
-DdoStem=true \
-DindexerExcludedFiles=$(INDEXER_EXCLUDED_FILES) \
-Dorg.xml.sax.driver=org.ccil.cowan.tagsoup.Parser \
-Djavax.xml.parsers.SAXParserFactory=org.ccil.cowan.tagsoup.jaxp.SAXFactoryImpl \
-classpath $(classpath) \
com.nexwave.nquindexer.IndexerMain
cp -r template/search/* ${OUTPUT_DIR}/search很明显，
此处生成webhelp的话，
- 先拷贝相关的文件
- 再去生成chunk
- 再去建立index索引：内部是直接调用java，传递对应的参数过去的。其中也还是用到了SAXParser之类的东西
3.所以，打开cygwin，直接去make这个webhelp试试：
先把Makefile.sample拷贝出来另存为Makefile，再去make webhelp，结果出现"Error: Could not find or load main class com.nexwave.nquindexer.IndexerMain"的错误：
由此，实现了，对于示例docbook的src，可以去用make而不是ant编译webhelp的效果。
4.接着，想办法，集成到我自己的docbook的环境中去：
就是，想办法，把当前这个示例makefile文件，整合进我的：
D:\tmp\tmp_dev_root\cgwin\home\CLi\develop\docbook\config\docbook.mk
中。
然后就是一堆的修改了。
5.最后，终于算是，基本的实现了效果。
用如下相关的makefile内容：
TOOLS_XSL_NS_FO = $(TOOLS_XSL_NS_BASE_CMD)/fo
TOOLS_XSL_NS_HTML = $(TOOLS_XSL_NS_BASE_CMD)/html
TOOLS_XSL_NS_HTMLHELP = $(TOOLS_XSL_NS_BASE_CMD)/htmlhelp
TOOLS_XSL_NS_WEBHELP = $(TOOLS_XSL_NS_BASE_CMD)/webhelp
TOOLS_XSL_NS_WEBSITE = $(TOOLS_XSL_NS_BASE_CMD)/website
TOOLS_XSL_NS_PROFILING = $(TOOLS_XSL_NS_BASE_CMD)/profiling
TOOLS_XSL_NS_EXTENSIONS = $(TOOLS_XSL_NS_BASE_CMD)/extensions
# ----------------------- common environment variable -----------------------
OS_NAME = $(shell uname -o)
OS_NAME_LOWCASE = $(shell echo $(OS_NAME) | tr '[A-Z]' '[a-z]')
#===============================================================================
# Webhelp related
#===============================================================================
# A list of files to exclude from indexing
INDEXER_EXCLUDED_FILES = ix01.html
# Use this variable to pass in other stringparams
# to the xsltproc pass that generates DocBook output.
# For example:
# WEBHELP_OTHER_XSLTPROC_ARGS = --stringparam example.param ""
#http://docbook.sourceforge.net/release/xsl/1.78.1/doc/html/webhelp.base.dir.html
#if not set, default will be docs under current docbook book src directory
WEBHELP_OTHER_XSLTPROC_ARGS = --stringparam webhelp.base.dir $(OUTPUT_DIR_WEBHELP)
# Profiling params. For more information on
# profiling (conditional text) and DocBook documents, see
# http://www.sagehill.net/docbookxsl/Profiling.html
PROFILE.ARCH = ""
PROFILE.AUDIENCE = ""
PROFILE.CONDITION = ""
PROFILE.CONFORMANCE = ""
PROFILE.LANG = ""
PROFILE.OS = ""
PROFILE.REVISION = ""
PROFILE.REVISIONFLAG = ""
PROFILE.ROLE = ""
PROFILE.SECURITY = ""
PROFILE.STATUS = ""
PROFILE.USERLEVEL = ""
PROFILE.VENDOR = ""
PROFILE.WORDSIZE = ""
PROFILE.ATTRIBUTE = ""
PROFILE.VALUE = ""
# =================================================
# You probably don't need to change anything below
# unless you choose to add a validation step.
# ================================================
INDEXER_JAR := $(TOOLS_XSL_NS_EXTENSIONS)/webhelpindexer.jar
TAGSOUP_JAR := $(TOOLS_XSL_NS_EXTENSIONS)/tagsoup-1.2.1.jar
LUCENE_ANALYZER_JAR := $(TOOLS_XSL_NS_EXTENSIONS)/lucene-analyzers-3.0.0.jar
LUCENE_CORE_JAR := $(TOOLS_XSL_NS_EXTENSIONS)/lucene-core-3.0.0.jar
#WEBHELP_CLASSPATH := $(INDEXER_JAR):$(TAGSOUP_JAR):$(LUCENE_ANALYZER_JAR):$(LUCENE_CORE_JAR)
#under Windows(Cygwin), (java classpath)
#(1)path seperator is semicolon ';' (not Linux's colon ':')
#(2) command contain semicolon means multile command, so need quote
# so become -> "path1;path2;path3"
#detail can refer:
#【已解决】docbook中去make webhelp编译webhelp结果出错：Error: Could not find or load main class com.nexwave.nquindexer.IndexerMain
#https://www.crifan.com/docbook_make_webhelp_error__could_not_find_or_load_main_class_com_nexwave_nquindexer_indexermain/
ifeq ($(OS_NAME_LOWCASE), cygwin)
WEBHELP_CLASSPATH := "$(INDEXER_JAR);$(TAGSOUP_JAR);$(LUCENE_ANALYZER_JAR);$(LUCENE_CORE_JAR)"
else
WEBHELP_CLASSPATH := $(INDEXER_JAR):$(TAGSOUP_JAR):$(LUCENE_ANALYZER_JAR):$(LUCENE_CORE_JAR)
endif
webhelp_make: $(MAIN_SRC_FILE) $(SUB_SRC_FILES) $(MAKE_FILE) webhelp_copyfiles webhelp_chunk webhelp_index
@echo "=============================== generating ${PROJECT_NAME} webhelp =============================="
webhelp_copyfiles:
-rm -rf $(OUTPUT_DIR_WEBHELP)
mkdir -p $(OUTPUT_DIR_WEBHELP)
cp -r $(TOOLS_XSL_NS_WEBHELP)/template/common ${OUTPUT_DIR_WEBHELP}
cp -a $(IMG_DIR) $(OUTPUT_DIR_WEBHELP)
test ! -d $(IMG_DIR)/ || cp -a $(IMG_DIR)/ ${OUTPUT_DIR_WEBHELP}
cp $(TOOLS_XSL_NS_WEBHELP)/template/favicon.ico ${OUTPUT_DIR_WEBHELP}/
webhelp_chunk:
xsltproc \
--xinclude --output xincluded-profiled.xml \
--stringparam profile.arch ${PROFILE.ARCH} \
--stringparam profile.audience ${PROFILE.AUDIENCE} \
--stringparam profile.condition ${PROFILE.CONDITION} \
--stringparam profile.conformance ${PROFILE.CONFORMANCE} \
--stringparam profile.lang ${PROFILE.LANG} \
--stringparam profile.os ${PROFILE.OS} \
--stringparam profile.revision ${PROFILE.REVISION} \
--stringparam profile.revisionflag ${PROFILE.REVISIONFLAG} \
--stringparam profile.role ${PROFILE.ROLE} \
--stringparam profile.security ${PROFILE.SECURITY} \
--stringparam profile.status ${PROFILE.STATUS} \
--stringparam profile.userlevel ${PROFILE.USERLEVEL} \
--stringparam profile.vendor ${PROFILE.VENDOR} \
--stringparam profile.wordsize ${PROFILE.WORDSIZE} \
--stringparam profile.attribute ${PROFILE.ATTRIBUTE} \
--stringparam profile.value ${PROFILE.VALUE} \
$(TOOLS_XSL_NS_PROFILING)/profile.xsl \
$(MAIN_SRC_FILE)
xsltproc ${WEBHELP_OTHER_XSLTPROC_ARGS} $(TOOLS_XSL_NS_WEBHELP)/xsl/webhelp.xsl xincluded-profiled.xml
@#rm xincluded-profiled.xml
webhelp_index:
java \
-DhtmlDir=$(OUTPUT_DIR_WEBHELP) \
-DindexerLanguage=en \
-DhtmlExtension=html \
-DdoStem=true \
-DindexerExcludedFiles=$(INDEXER_EXCLUDED_FILES) \
-Dorg.xml.sax.driver=org.ccil.cowan.tagsoup.Parser \
-Djavax.xml.parsers.SAXParserFactory=org.ccil.cowan.tagsoup.jaxp.SAXFactoryImpl \
-classpath $(WEBHELP_CLASSPATH) \
com.nexwave.nquindexer.IndexerMain
mkdir -p ${OUTPUT_DIR_WEBHELP}/search
cp -r $(TOOLS_XSL_NS_WEBHELP)/template/search/* ${OUTPUT_DIR_WEBHELP}/search然后去make webhelp_make：
CLi@PC-CLI-1 ~/develop/docbook/books/docbook_dev_note/src
$ make webhelp_make
rm -rf ../output/webhelp
mkdir -p ../output/webhelp
cp -r D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/tools/docbook-xsl-ns-1.78.1/webhelp/template/common ../output/webhelp
cp -a ./images ../output/webhelp
test ! -d ./images/ || cp -a ./images/ ../output/webhelp
cp D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/tools/docbook-xsl-ns-1.78.1/webhelp/template/favicon.ico ../output/webhelp/
xsltproc \
--xinclude --output xincluded-profiled.xml \
--stringparam profile.arch "" \
--stringparam profile.audience "" \
--stringparam profile.condition "" \
--stringparam profile.conformance "" \
--stringparam profile.lang "" \
--stringparam profile.os "" \
--stringparam profile.revision "" \
--stringparam profile.revisionflag "" \
--stringparam profile.role "" \
--stringparam profile.security "" \
--stringparam profile.status "" \
--stringparam profile.userlevel "" \
--stringparam profile.vendor "" \
--stringparam profile.wordsize "" \
--stringparam profile.attribute "" \
--stringparam profile.value "" \
D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/tools/docbook-xsl-ns-1.78.1/profiling/profile.xsl \
./docbook_dev_note.xml
xsltproc --stringparam webhelp.base.dir ../output/webhelp D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/tools/docbook-xsl-ns-1.78.1/webhelp/xsl/webhelp.xsl xincluded-profiled.xml
language: en
Writing ../output/webhelp/background_docbook_come.html for sect2(background_docbook_come)
Writing ../output/webhelp/screenshot_docbook_one_in_multi_out.html for sect3(screenshot_docbook_one_in_multi_out)
Writing ../output/webhelp/what_is_the_docbook.html for sect2(what_is_the_docbook)
Writing ../output/webhelp/what_is_docbook.html for sect1(what_is_docbook)
Writing ../output/webhelp/why_use_docbook.html for sect1(why_use_docbook)
Writing ../output/webhelp/preface.html for preface(preface)
Writing ../output/webhelp/our_target.html for sect2(our_target)
Writing ../output/webhelp/format_convert_knowledge.html for sect2(format_convert_knowledge)
Writing ../output/webhelp/should_know_before_docbook.html for sect1(should_know_before_docbook)
Writing ../output/webhelp/ch01s02s01.html for sect2
Writing ../output/webhelp/download_xsltproc_win.html for sect2(download_xsltproc_win)
Writing ../output/webhelp/download_xsl_ns.html for sect2(download_xsl_ns)
Writing ../output/webhelp/download_fop.html for sect3(download_fop)
Writing ../output/webhelp/config_fop_home.html for sect3(config_fop_home)
Writing ../output/webhelp/add_fop_xconf.html for sect3(add_fop_xconf)
Writing ../output/webhelp/download_fop_add_conf.html for sect2(download_fop_add_conf)
Writing ../output/webhelp/prepare_docbook_src_xml.html for sect2(prepare_docbook_src_xml)
Writing ../output/webhelp/prepare_xml_config.html for sect3(prepare_xml_config)
Writing ../output/webhelp/convert_xml_to_html.html for sect3(convert_xml_to_html)
Writing ../output/webhelp/from_xml_generate_html.html for sect2(from_xml_generate_html)
Writing ../output/webhelp/prepare_pdf_config.html for sect3(prepare_pdf_config)
Writing ../output/webhelp/convert_xml_to_fo.html for sect3(convert_xml_to_fo)
Writing ../output/webhelp/convert_fo_to_pdf.html for sect3(convert_fo_to_pdf)
Writing ../output/webhelp/from_xml_generate_pdf.html for sect2(from_xml_generate_pdf)
Writing ../output/webhelp/pure_win_docbook_dev_env.html for sect1(pure_win_docbook_dev_env)
Writing ../output/webhelp/install_cygwin.html for sect2(install_cygwin)
Writing ../output/webhelp/download_fop_for_cygwin.html for sect2(download_fop_for_cygwin)
Writing ../output/webhelp/cygwin_docbook_dev_env.html for sect1(cygwin_docbook_dev_env)
Writing ../output/webhelp/ch01_build_env.html for chapter(ch01_build_env)
Writing ../output/webhelp/docbook4_vs_docbook5.html for sect1(docbook4_vs_docbook5)
Writing ../output/webhelp/entity_definition.html for sect1(entity_definition)
Writing ../output/webhelp/qanda_usage.html for sect1(qanda_usage)
Writing ../output/webhelp/fop_font_config.html for sect2(fop_font_config)
Writing ../output/webhelp/fop_notes.html for sect1(fop_notes)
Writing ../output/webhelp/docbook_some_concept.html for sect1(docbook_some_concept)
Writing ../output/webhelp/docbook_id_abbrev.html for sect3(docbook_id_abbrev)
Writing ../output/webhelp/docbook_best_practice.html for sect2(docbook_best_practice)
Writing ../output/webhelp/docbook_dev_notes.html for sect1(docbook_dev_notes)
Writing ../output/webhelp/example_docbook_debug_pdf.html for sect2(example_docbook_debug_pdf)
Writing ../output/webhelp/docbook_debug.html for sect1(docbook_debug)
Writing ../output/webhelp/docbook_focus_content.html for sect2(docbook_focus_content)
Writing ../output/webhelp/docbook_vs_building.html for sect2(docbook_vs_building)
Writing ../output/webhelp/docbook_summary.html for sect1(docbook_summary)
Writing ../output/webhelp/dobook_evolution_process.html for sect1(dobook_evolution_process)
Writing ../output/webhelp/ch02_notes.html for chapter(ch02_notes)
Writing ../output/webhelp/ch03_faq.html for chapter(ch03_faq)
Writing ../output/webhelp/intro_explain_docbook_materials.html for sect1(intro_explain_docbook_materials)
Writing ../output/webhelp/docbook_refer_materials.html for sect1(docbook_refer_materials)
Writing ../output/webhelp/ch04_materials.html for chapter(ch04_materials)
Writing ../output/webhelp/unknown_code_syntax_highlight.html for sect1(unknown_code_syntax_highlight)
Writing ../output/webhelp/unknown_zhcn_hypernate.html for sect1(unknown_zhcn_hypernate)
Writing ../output/webhelp/unknown_callout_co_re_number.html for sect1(unknown_callout_co_re_number)
Writing ../output/webhelp/ch05_issues.html for chapter(ch05_issues)
Writing ../output/webhelp/example_chapter_section.html for sect1(example_chapter_section)
Writing ../output/webhelp/example_para.html for sect1(example_para)
Writing ../output/webhelp/example_figure.html for sect1(example_figure)
Writing ../output/webhelp/example_table.html for sect1(example_table)
Writing ../output/webhelp/example_callout.html for sect1(example_callout)
Writing ../output/webhelp/example_link_xref.html for sect1(example_link_xref)
Writing ../output/webhelp/example_equation.html for sect1(example_equation)
Writing ../output/webhelp/example_list.html for sect1(example_list)
Writing ../output/webhelp/example_simplelist_literallayout.html for sect1(example_simplelist_literallayout)
Writing ../output/webhelp/example_xinclude.html for sect1(example_xinclude)
Writing ../output/webhelp/example_filename.html for sect1(example_filename)
Writing ../output/webhelp/example_admonitions_note.html for sect2(example_admonitions_note)
Writing ../output/webhelp/example_admonitions_caution.html for sect2(example_admonitions_caution)
Writing ../output/webhelp/example_admonitions_warning.html for sect2(example_admonitions_warning)
Writing ../output/webhelp/example_admonitions_tip.html for sect2(example_admonitions_tip)
Writing ../output/webhelp/example_admonitions_important.html for sect2(example_admonitions_important)
Writing ../output/webhelp/example_admonitions.html for sect1(example_admonitions)
Writing ../output/webhelp/ch06_examples.html for chapter(ch06_examples)
Writing ../output/webhelp/docbook_released_basic.html for sect1(docbook_released_basic)
Writing ../output/webhelp/docbook_released_embedded.html for sect1(docbook_released_embedded)
Writing ../output/webhelp/docbook_released_upper.html for sect1(docbook_released_upper)
Writing ../output/webhelp/docbook_released_other.html for sect1(docbook_released_other)
Writing ../output/webhelp/appendix.html for appendix(appendix)
Writing ../output/webhelp/index.html for book
Writing ../output/webhelp/search/l10n.js
java \
-DhtmlDir=../output/webhelp \
-DindexerLanguage=en \
-DhtmlExtension=html \
-DdoStem=true \
-DindexerExcludedFiles=ix01.html \
-Dorg.xml.sax.driver=org.ccil.cowan.tagsoup.Parser \
-Djavax.xml.parsers.SAXParserFactory=org.ccil.cowan.tagsoup.jaxp.SAXFactoryImpl \
-classpath "D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/tools/docbook-xsl-ns-1.78.1/extensions/webhelpindexer.jar;D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/tools/docbook-xsl-ns-1.78.1/extensions/tagsoup-1.2.1.jar;D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/tools/docbook-xsl-ns-1.78.1/extensions/lucene-analyzers-3.0.0.jar;D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/tools/docbook-xsl-ns-1.78.1/extensions/lucene-core-3.0.0.jar" \
com.nexwave.nquindexer.IndexerMain
Stemming enabled
The created index files are located in ..\output\webhelp\search
Indexed the contents in 1 seconds
mkdir -p ../output/webhelp/search
cp -r D:/tmp/tmp_dev_root/cgwin/home/CLi/develop/docbook/tools/docbook-xsl-ns-1.78.1/webhelp/template/search/* ../output/webhelp/search
=============================== generating docbook_dev_note webhelp ==============================
CLi@PC-CLI-1 ~/develop/docbook/books/docbook_dev_note/src
$编译出来相关的输出文件到../output/webhelp中：
然后运行其中的：
index.html
可以看到，可以在Firefox中正常显示了：
6.对应的，makefile的：
webhelp_chunk:
xsltproc \
--xinclude --output xincluded-profiled.xml \编译生成的中间文件：
xincluded-profiled.xml
去看了看：
很明显，是：
xi:include
的执行过后的，
完整的，独立的，docbook的xml文件。
然后后期，才调用：
xsltproc ${WEBHELP_OTHER_XSLTPROC_ARGS} $(TOOLS_XSL_NS_WEBHELP)/xsl/webhelp.xsl xincluded-profiled.xml 去处理的。
7.然后，此处，还是有其他一些细节需要优化的。
包括：
- 确保，本地和在线，都只有一份webhelp\template\common的内容
- 其下包含很多子文件夹和公用文件的，比如：
- css
- ie.css
- positioning.css
- images
- admon\
- callouts\
- …
- jquery
- jquery-1.7.2.min.js
- jquery-ui-1.8.2.custom.min.js
- …
- browserDetect.js
- main.js
- splitterInit.js
- 将之前的，各种对应chunk等方面的公用配置，比如html中所有的programlisting背景色都是蓝色，等等配置，都集成进来
- 确保后续设置更多webhelp方面的参数的时候，很方便的设置
- 除了WEBHELP_OTHER_XSLTPROC_ARGS设置之外，是发还有其他更好的做法
等等方面。都要去继续再优化makefile的。
8.所以先去：
【记录】docbook的docbook-xls-ns-1.78.1中的webhelp：优化使得共享webhelp的（css和js等）模板文件
9.再去集成共用的webhelp的xsl的配置：
【记录】docbook的docbook-xsl-ns-1.78.1中的webhelp：优化使得共用之前的chunk等公共的xsl配置
10.然后再去确保webhelp可以在线正常显示：
【记录】docbook的docbook-xsl-ns-1.78.1中的webhelp：将webhelp上传到在线网站确认是否显示正常
【总结】
至此，关于webhelp部分的内容，就算彻底解决了：
本地测试webhelp，三种浏览器都支持；
上传到在线网站，也都是正常的，三种浏览器都可以正常显示的。
剩下的，就是之后，再去：
【记录】将docbook的xsl-ns从当前的docbook-xsl-ns-1.77.1升级到docbook-xsl-ns-1.78.1
继续去验证其余的html，htmls（即chunk），fo等等的配置，是否需要修改了，即更新使用最新的1.78.1的docbook-xsl的配置。
转载请注明：在路上 » 【记录】使用docbook的docbook-xsl-ns-1.78.1替换旧的ant改用make去编译webhelp