Differences between revisions 1 and 2
⇤ ← Revision 1 as of 2009-12-31 02:55:10 →
Size: 420
Editor: ZoomQuiet
Comment:
← Revision 2 as of 2009-12-31 03:17:16 → ⇥
Size: 5646
Editor: ZoomQuiet
Comment: creat from ECUG 老范
Deletions are marked like this. Additions are marked like this.
Line 13: Line 13:
== 章标题1 == 来自: [[https://groups.google.com/group/ecug/browse_thread/thread/5214c1b34b6227b/16171d475a964f93?lnk=gst&q=sphinx#16171d475a964f93|询问sphinx + latex 的用法]] ^ - ECUG~erlang中文用户组 | Google Groups^
Line 15: Line 15:
=== 小节标题1 === === 第一步: 编译为latex ===
Line 17: Line 17:
#!python
Python code		       make latex
Line 20: Line 19:
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 起了两个作用。
  1. 是告诉sphinx 如何编译rst 文件。同时把自己放到了latex文件的第二行{{{
   \documentclass[letterpaper,10pt,english]{manual}
}}}
  1. 告诉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 语法失灵,生成目录时无效,仍然是会生成出多级目录结构

Contents

  1. 用Sphinx生成中文PDF
      1. 第一步: 编译为latex
      2. 第二步:编译为pdf
      3. 第三步:检查和调整
    2. 讨论
      1. 为什么 每次都要 修 改ctexbookutf8 来生 成pdf 文件
      2. 进 一步 控制
      3. TODO

用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 起了两个作用。

    1. 是告诉sphinx 如何编译rst 文件。同时把自己放到了latex文件的第二行

         \documentclass[letterpaper,10pt,english]{manual}
    2. 告诉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]

UsageSphinxExPdf (last edited 2009-12-31 03:17:16 by ZoomQuiet)