250717 尝试生成NS-3 API文档的PDF版本

Posted on Edited on In , Disqus: Word count in article: 2.3k Reading time ≈ 2 mins.

问LLM一些代码问题，如果是大家公用的库结果可能还好，但是一些专门的领域出错的概率感觉就大很多。最近问Gemini有关NS-3的代码，结果就不尽如人意。但是想到Gemini支持百万级别的上下文，我就想或许可以把NS-3的API文档喂给Gemini。省流，最后还是失败了。官方也只有HTML版本，可能也是因为文档太庞大了不好生成pdf吧。

尝试的过程

API文档没法直接生成PDF，默认是生成HTML，可以修改配置文件生成Latex或者Docbook。Docbook没听说过，但是Latex可以用来生成PDF，这就好办了。

Latex

先修改一下NS-3项目下doc/doxygen.conf文件，配置下面三个条目

1
2
3
GENERATE_LATEX         = YES
USE_PDFLATEX           = YES
LATEX_OUTPUT           = latex

保存之后运行：

1
./ns3 docs doxygen

之后就能在doc/latex文件夹下找到生成的latex文件。然后用latex编译工具编译成pdf文档。

可惜就在这一步失败了，首先尝试用这个命令编译

1
latexmk -pdf refman.tex

但是报错

1
2
3
! LaTeX Error: Unicode character ┌ (U+250C)

               not set up for use with LaTeX.

Gemini建议是在latex/refman.tex文件里加入一个package，

1
\usepackage{fontspec}

并且改用xelatex编译

1
latexmk -xelatex refman.tex

虽然这解决了字符问题，但是新的问题又出现了，编译继续报错

1
TeX capacity exceeded, sorry [pool size=...]

搜了下解决方案，尝试修改texlive\2025\texmf-dist\web2c\texmf.cnf里的pool_size，也试了在doc/doxygen.conf里禁用生成一些图表

1
2
3
4
5
CALL_GRAPH            = NO
CALLER_GRAPH          = NO
COLLABORATION_GRAPH   = NO
INCLUDE_GRAPH         = NO
INCLUDED_BY_GRAPH     = NO

然而都没用，依然报同样的错误，只能作罢。

Docbook

其实在latex编译失败搜索一会找不到解决方法之后就准备放弃了，但是想起来doc/doxygen.conf里提到可以生成Docbook来帮助生成pdf，还是试一试吧。

首先还是修改doc/doxygen.conf，不生成Latex，开启生成Docbook。

1
2
GENERATE_LATEX         = NO
GENERATE_DOCBOOK       = YES

依然是运行./ns3 docs doxygen，这次会在doc/docbook文件夹下生成Docbook格式文档。

然后需要安装一些工具，用来把Docbook转换成FO，然后转换成PDF。

1
sudo apt install docbook-xsl xsltproc fop

之后在docbook文件夹下运行命令

1
xsltproc --xinclude /usr/share/xml/docbook/stylesheet/docbook-xsl/fo/docbook.xsl index.xml > refman.fo

需要--xinclude这个选项，不加的话会出现一堆这个错误

1
Element include in namespace 'http://www.w3.org/2001/XInclude' encountered in chapter, but no template matches.

之后就是等，xsltproc是个线性过程单线程运行，NS-3的API文档又十分庞大，要花很长时间。
结果等到了第二天，还是没跑完，而且也没有任何进度显示，于是还是终止了程序。

HTML转PDF

都试了这么多了，本来想放弃的，但还是继续试了下去，就想看看能不能成功。这次就看看有没有能把HTML文档批量转换成单个PDF文档的工具了。

确实是找到了一个叫wkhtmltopdf的工具，不过也踩了坑。先是直接用apt install，结果一旦使用toc选项，运行就会报错

1
Exit with code 1, due to unknown error.

Gemini说可能是Ubuntu软件源的问题，建议从官网下载https://github.com/wkhtmltopdf/wkhtmltopdf

先卸载

1
sudo apt remove wkhtmltopdf

然后从deb文件安装

1
sudo dpkg -i xxx.deb

如果提示缺依赖

1
sudo apt -f install

还真是，从官网下载的就可以用toc选项了，但是用这个命令尝试最终生成单个pdf的时候还是报错了

1
wkhtmltopdf --enable-local-file-access --allow /home/liup03/ns-3-dev/doc/html --load-error-handling ignore toc $(find . -name "*.html" | sort) ns3-documentation.pdf

而且也没有详细的错误提示，也只能放弃了

1
Exit with code 1 due to network error: ContentAccessDenied

意料之外……

突然发现Gemini可以直接导入Github的仓库了，说是仓库文件最多可以有5000个，虽然只试了几个小仓库，但是感觉问答也没什么问题，后面可以试试把NS-3仓库喂给它。