【记录】把Docbook所生成的htmls的主文件（入口文件）改为index.html

之前用docbook生成htmls时，主文件，入口文件是 project_name.html

而不是index.html。

导致进入对应的文件夹，比如：

https://www.crifan.com/files/doc/docbook/rec_soft_npp/release/htmls/

可以看到很多文件的列表：

而不是直接打开对应的主文件：

https://www.crifan.com/files/doc/docbook/rec_soft_npp/release/htmls/rec_soft_npp.html

而已经知道了，如果当前路径下面有index.html之类的入口文件的话，则会自动打开对应的主文件index.html的

即如果

https://www.crifan.com/files/doc/docbook/rec_soft_npp/release/htmls/

下面有indx.html

则去访问

https://www.crifan.com/files/doc/docbook/rec_soft_npp/release/htmls/

则会自动找到index.html并打开的

而不是由于找不到入口文件，只是显示文件列表。

此功能是由之前折腾过的：

【已解决】基于Apache服务器的文件列表，即文件的http下载模式

中所提到的，apache的mod_autoindex去控制的。

【解决过程】

1.去自己的makefile中，把对应的htmls所生成的文件名从：

OUTPUT_FILE_HTMLS   = $(OUTPUT_DIR_HTMLS)/$(PROJECT_NAME).html

改为：

OUTPUT_FILE_HTMLS   = $(OUTPUT_DIR_HTMLS)/$(HTMLS_MAIN_FILENAME).html

其中：

HTMLS_MAIN_FILENAME = index

2.再去找docbook中，所生成的主文件名，如何从

$(PROJECT_NAME).html

变为index.html

然后就去：

http://docbook.sourceforge.net/release/xsl/1.77.1/doc/html/index.html

找，这个：

root.filename — Identifies the name of the root HTML file when chunking

好像有点关系。

3.然后就去看看对应的配置。

自己的xsl中：

E:\Dev_Root\docbook\dev\config\docbook-xsl-ns-1.77.1\html\multi\chunk_crl.xsl

没有这个配置。

是使用的官方标配的：

E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.1\html\chunk.xsl

其中其又调用了：

E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.1\html\chunk-common.xsl

和

E:\Dev_Root\docbook\tools\docbook-xsl-ns-1.77.1\html\chunk-code.xsl

最后是在后者中，找到了有root.filename。

不过其是使用此参数，而没有设置此参数的默认值。

4.所以，就去在自己的xsl中：

E:\Dev_Root\docbook\dev\config\docbook-xsl-ns-1.77.1\html\multi\chunk_crl.xsl

添加此参数：

<!--
http://docbook.sourceforge.net/release/xsl/1.77.1/doc/html/root.filename.html
set root file name for chunk html
-->
<xsl:param name="root.filename">index</xsl:param>

结果却是没有起效果，主文件还是rec_soft_npp.html，而不是期望的index.html

5.然后又去看了看。

感觉，不知道，是不是由于之前把use.id.as.filename设置成1了，所以覆盖了此参数，所以去把use.id.as.filename改为0：

<!-- <xsl:param name="use.id.as.filename">1</xsl:param> -->
<xsl:param name="use.id.as.filename">0</xsl:param>

再去试试结果如何。

结果主文件还是rec_soft_npp.html。

6.然后就怀疑，是不是自己之前在makefile或者参数配置方面，写死了主文件的输出的名字了。

所以再去找找相关配置。

其中注意到，编译输出中，相关内容是：

Writing ch03s18.html for sect1(npp_func_multi_themes)
Writing ch03s19.html for sect1(npp_func_misc)
Writing ch03.html for chapter(npp_function)
Writing bi01.html for bibliography(reference)
Writing rec_soft_npp.html for book
Writing rec_soft_npp.html.manifest
Catalogs cleanup

所以，去找找，哪里控制输出那个book的。

7.不过后来找到官网的解释了：

Chunking into multiple HTML files

Chunk filenames

Each chunk has to have a filename. The filename (before adding .html) can come from three sources, selected in this order:

• A dbhtml filename processing instruction embedded in the element.

• If it is the root element of the document, then the chunk is named using the value of the parameter root.filename, which is index by default.

• The chunk element’s id attribute value (but only if the use.id.as.filename parameter is set).

• A unique name generated by the stylesheet.

所以，我这里，刚才把

use.id.as.filename设置为0了。

又设置了root.filename为index了

结果还是不对，那么只剩下，最可能的是，在stylesheet的某处，固定设置了对应的文件名了。

8.后来果然，在makefile中，找到了之前的，针对于htmls的配置：

–stringparam root.filename $(PROJECT_NAME)

所以，结果始终是rec_soft_npp.html

所以，makefile中去掉这行，xsl中保留之前的配置：

<!--
http://docbook.sourceforge.net/release/xsl/1.77.1/doc/html/use.id.as.filename.html
the filename of chunk elements that have IDs will be derived from the ID value
-->
<xsl:param name="use.id.as.filename">1</xsl:param>

<!--
http://docbook.sourceforge.net/release/xsl/1.77.1/doc/html/generate.manifest.html
a list of HTML files generated by the stylesheet transformation is written to the file named by the manifest parameter.
-->
<xsl:param name="generate.manifest">1</xsl:param>

<!--
http://docbook.sourceforge.net/release/xsl/1.77.1/doc/html/manifest.html
Name of manifest file
has set this value in docbook.mk
<xsl:param name="manifest">HTML.manifest</xsl:param>
-->

<!--
http://docbook.sourceforge.net/release/xsl/1.77.1/doc/html/root.filename.html
The root.filename is the base filename for the chunk created for the root of each document processed.
-->
<xsl:param name="root.filename">index</xsl:param>

然后再去试试。

然后的确就可以了：

Writing npp_function.html for chapter(npp_function)
Writing reference.html for bibliography(reference)
Writing index.html for book
Writing rec_soft_npp.html.manifest
Catalogs cleanup

9.然后再去把之前的模板中的，htmls的链接，也更新掉。

从：

<entry><link xl:href="https://www.crifan.com/files/doc/docbook/&cur_book_name;/release/htmls/&cur_book_name;.html">HTML</link></entry>

改为：

<entry><link xl:href="https://www.crifan.com/files/doc/docbook/&cur_book_name;/release/htmls/index.html">HTMLs</link></entry>

【总结】

对于折腾docbook时，在xsl中配置参数 和 在makefile编译时通过–stringparam传递参数时，一定不能搞混了。

对于同一个参数，不能同时在两边都出现，否则很容易混乱的。

其实，最好的做法是，尽量都在xsl中配置。

而尽量少使用–stringparam。

这样对于参数配置方面，就尽量统一，不容易混淆出错了。

转载请注明：在路上 » 【记录】把Docbook所生成的htmls的主文件（入口文件）改为index.html