【背景】
折腾:
【记录】修复用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