Contents
用Sphinx生成中文PDF
来自: 询问sphinx + latex 的用法 - ECUG~erlang中文用户组 | Google Groups
第一步: 编译为latex
make latex
sphinx 自动将reST 文件编译为latex 文件;目标文件在 _build/latex 目录中
第二步:编译为pdf
- 运行SciTE Latex IDE;打开上一步骤编译成功的*.tex 文档;此时很可能是乱码,不用管,应为其实内
容是对的,只是IDE 显示问题(可以通过选项看到正常文字);在文档的第二行
documentclass[letterpaper,10pt,english]{manual}
需要将{manual}改为{ctexbookutf8};修改并保存后,点击pdf完全排版按钮。就生成出一个pdf 文件。
文件保存在_build/latex 目录下。文件名和前面的latex 文件同名。
小贴士:每次生成,文档封面上的编写日期都会自动更新,非常方便。
第三步:检查和调整
- 毕竟sphinx 不是一个所见即所得的工具。如果没有正确理解语法,没用通过空行和缩进来控制段落的
话,可能输出文档和预想的有差异。另外也需要对于图片通过scale 进行微调,让其大小看起来更加美观。 通读生成的pdf文档,将其中不理想的地方,以及错别字等修订后,再次生成。再检查,直到满意。
- 刚开始编写时,可能错误很多,改起来也麻烦。或者编写的时候担心用错了符号。不过其实语法并不
多,写写就熟了。虽然在所见即所得方面有损失,但是通过sphinx 我们可以进行团队化的文档编写,可以逐 步修正,片段修改,让文档总是保持最新状态,所有文档都有相同的look and feel。其带来的好处也是非常 大的。熟悉之后,其实一次成功的情况也很多。
讨论
为什么 每次都要 修 改ctexbookutf8 来生 成pdf 文件
- Sphinx 生成的工程项目中,在conf.py 中
latex_documents = [ (’index’, ’project-management.tex’, u’唯智项目管理规范(V1.0)’, u’vtradex’, ’manual’),
最后一位manual 表明了按照何种格式编译rst 文件;
make 后可以在_build/latex 目录中看到有两个cls 文件。一个是manul.cls, 一个是howto.cls。
- cls 文件是将latex 文件编译成pdf 文件的配置文件,其中有非常复杂的latex 语法。
- 上述配置中的manul 起了两个作用。
是告诉sphinx 如何编译rst 文件。同时把自己放到了latex文件的第二行
\documentclass[letterpaper,10pt,english]{manual}
- 告诉latex 如何编译成pdf. 这个就是通过latex 输出文件中上述内容来关联起来的。latex 编译成pdf 和sphinx 没有任何其他关系。
但是由于manual.cls 文件无法正确的解析utf8 编码的文件,如果直接生成,大部分中文内容都丢掉了。在MiCTekLocal Datetexlatex 目录下,MicTek 自带了一系列的cls 文件。经过反复测试ctexbookutf8 可以正确的解析sphinx 输出的latex ,并生成和manual 定义格式类似的pdf 文件(格式略有改变)。
- 但是不能在conf.py 中直接配置ctexbookutf8,否则sphinx 无法正确生成latex 文件。
- 因此只能在每次生成latex 文件后,手工修改,然后再生成pdf 文件
进 一步 控制
- 修改conf.py 配置,可以对于输出文档进行进一步控制
# 控制纸张大小 latex_paper_size = ‘letter’ # 控制字体大小 latex_font_size = ‘10pt’
TODO
- 如果对于sphinx 和latex 的配置有进一步理解的情况下,理论上来讲能够修改cls 文件,以及sphinx 生成
- 算法,将现有的文档生成出更好的格式,而不需要对于文档进行任何修改。也可以解决现在反复修 改ctexbookutf8 的毛病。
- 表格生成出来,仅表头有横向分割线,其他行没有分隔线,这个问题估计是sphinx bug. 从生成的latex
- 文档看,确实没有分割线。
- 生成的章节头过大,造成章节那页的空间比较浪费。这个既是问题也不是问题。应为本来ctextbook就
- 是设计成这种样子,估计还是有人喜欢这种风格。如果要改的话,就要熟悉latex 语法,修改cls 文件
- 对于熟悉的人员,可以通过命令行来编译pdf 文件,不需要竟如IDE 来生成。如果解决了ctexbookutf8
- 问题,就可以配置shell 批处理程序实现一键式生成pdf 文档。甚至在服务上配置自动编译脚本,每当 有新版本,可以自动编译,并发给需要的人员。
- 编译后,会发现pdf 中很多地方出现空页。这个是应为ctexbookutf8 模版是用于输出书籍的。书籍都是
- 双面打印的,一般如果一个章节完了占了奇数页的话,其偶数页就是该纸张的背面。此时一般都是留 空,然后从新的一页另起来一章开始打印。
- 生成pdf 本身,以及目录章节都是正确的。但是pdf 阅读其左边列出的文档结构图是乱码。这个不影响
- 文档的美观,可以容忍
- 目录使用的:maxdepth: 2 语法失灵,生成目录时无效,仍然是会生成出多级目录结构
反馈
创建 by -- ZoomQuiet [2009-12-31 02:55:10]