ctex: 宏包文档的讨论

[ghost]

现在的文档看起来有一点点怪，我也说不准是哪里的问题。

第一次阅读的时候，比较大的感受有两个。

一是内容有重复。主要是宏包选项和 \ctexset 的部分，fontset 和 punct 讲了两遍。我觉着挺没必要的，第一次阅读的时候还花时间仔细对比了一下两部分是不是有差别。读完之后，发现 3.5.1 节又来一遍 fontset……

二是有些纠结。编码、编译方式、字体设置、支持方式，四个部分纠缠在一起，对这些内容的解释又分散在文档的不同地方。不熟悉的用户，读起来可能很费劲。

现在的想法是把原来的第三节「参考手册」拆开，原来的几个 subsection 按照功能重新组成 section。关于编码、编译方式、字体设置、中文支持方式这一块，在讲完配置方法之后，对这一块做一个总结。把 ctex 宏包对这一块的处理逻辑做一个梳理，最好搞出一个表格或者流程图之类的东西。

参考手册这节的内容，暂时想拆成这些部分：

• 下载、依赖与安装
• CTeX 宏包的组成
• 宏包配置
  • 宏包选项和 \ctexset
  • 只能在宏包选项里配置的选项
  • 可以在宏包选项里配置也可以用 \ctexset 配置的选项
  • 只能用 \ctexset 配置的选项
• 文档汉化与中文版式
• 编码、编译方式、字体设置、中文支持
• LuaLaTeX 下的中文支持的特别内容

---

还有一些私货。

• 感觉 \parskip 可以加大一点
• heading 和 cap/nocap 的关系我单看文档没看懂，看了代码才明白

[ghost]

@qinglee @leo-liu

[leo-liu]

heading/cap 的关系是不大好看清楚。其实 heading 的意义是很明确的。cap 主要是名字起得不好，我觉得，目前还叫它 cap 主要是为了兼容性，不然或许 scheme、theme 之类的名字才贴切一点。

[leo-liu]

对于结构，虽然说整体上移一层和整体下移一层本质上是相同的，我也觉得一个 section 太大了。整个文档分成几个 part：

• 简介和快速入门
• 参考手册
• 代码实现

每个 part 若干 section，这样可能会好看一点了。

[ghost]

按照我的思路，可能会出现 1.2.3.4 这样的编号。四级，太多了。

所以我才提议把内容整体上移一层。或者用 \part?

cap 的问题，是不是考虑改成 scheme？cap 和 nocap 都当做过时选项，保留一个兼容性即可。

—
Sent from Mailbox

On Wed, Apr 8, 2015 at 10:36 PM, Liu Haiyang notifications@github.com
wrote:

对于结构，虽然说整体上移一层和整体下移一层本质上是相同的，我也觉得一个 section 太大了。整个文档分成几个 part：

• 简介和快速入门
• 参考手册

• 代码实现
  每个 part 若干 section，这样可能会好看一点了。

  Reply to this email directly or view it on GitHub:
  ctex: 宏包文档的讨论 #177 (comment)

[leo-liu]

这个提纲里面也重复吧，选项是各方面的都有，后面几节大多也是用选项设置的。
2015-4-8 下午10:22于 "Liam Huang" notifications@github.com写道：

现在的文档看起来有一点点怪，我也说不准是哪里的问题。

第一次阅读的时候，比较大的感受有两个。

一是内容有重复。主要是宏包选项和 \ctexset 的部分，fontset 和 punct
讲了两遍。我觉着挺没必要的，第一次阅读的时候还花时间仔细对比了一下两部分是不是有差别。读完之后，发现 3.5.1 节又来一遍 fontset……

二是有些纠结。编码、编译方式、字体设置、支持方式，四个部分纠缠在一起，对这些内容的解释又分散在文档的不同地方。不熟悉的用户，读起来可能很费劲。

现在的想法是把原来的第三节「参考手册」拆开，原来的几个 subsection 按照功能重新组成
section。关于编码、编译方式、字体设置、中文支持方式这一块，在讲完配置方法之后，对这一块做一个总结。把 ctex
宏包对这一块的处理逻辑做一个梳理，最好搞出一个表格或者流程图之类的东西。

参考手册这节的内容，暂时想拆成这些部分：

• 下载、依赖与安装
• CTeX 宏包的组成
• 宏包配置
  • 宏包选项和 \ctexset
  • 只能在宏包选项里配置的选项
  • 可以在宏包选项里配置也可以用 \ctexset 配置的选项
  • 只能用 \ctexset 配置的选项
    • 文档汉化与中文版式
• 编码、编译方式、字体设置、中文支持
• LuaLaTeX 下的中文支持的特别内容

---

还有一些私货。

• 感觉 \parskip 可以加大一点
• heading 和 cap/nocap 的关系我单看文档没看懂，看了代码才明白

—
Reply to this email directly or view it on GitHub
#177.

[ghost]

想了一下，确实如此。所以按照这些选项的功能来分章节叙述比较好。至于在 ctexset 里用还是在宏包选项里使用，就不作为分类的依据了。没提到一批选项的时候，单独说这么一句话好了。

[ghost]

@leo-liu @qinglee
这个表格有问题吗= =？

[qinglee]

就是这样，没问题。

[ghost]

eb20fec 调整之后的文档结构。