Code this. Any Thoughts During Code this

介绍专业的文档系统LaTeX

摘要

TeX家族是一个专业的排版系统。本文简要地介绍了TeX家族的常见成员, 并整理出了LaTeX入门使用过程中会遇到的一些问题,

同时,将演示LaTeX在网页中的集成。最后在附录部分,给出了样式模板的参考代码。

TeX家族简介

TeX可以视为出版行业的专业排版系统,由Donald Knuth于1978年发布, 当前的稳定版本编号为

TeX是脚本化的排版系统,所有的排版格式都是用TeX语法描述的。比如使用\begin{tabular} \end{tabular}来绘制表格。 TeX接收一系列的语法命令和文本内容,经过TeX系统编译(macro compiler)之后,输出到显示屏、DVI或者PDF文档。 对于同样的一份TeX脚本,在任意的环境下编译后的输出文档:格式、字体、间距等都应该是一样的。

TeX的基础上,可以定义一系列的宏包(macro),可以更方便地描述排版样式。比如上述的表格语法,其实来自LaTeX宏包, 如果要使用纯TeX(plain TeX)来绘制表格,则要使用更多的排版命令 (参考这两个网页文献 AB )。 LaTeX是非常流行的宏包,除此之外还有AMS-TeXXeTeX1

为什么使用TeX家族排版

和Office这类所见所得的文档处理器不同的是,TeX系列使用大量的命令来描述排版格式。 此外,所见非得的TeX和所见即得的Office相比:

  • 使用TeX,不需要考虑软件的版权费用问题,它是免费的。
  • 使用TeX,不需要担心跨软件、跨平台的格式兼容问题。 不同的Office软件在排版格式上并不完全兼容,即使同一个软件公司的不同Office版本, 格式上也不完全兼容。但是,同样的一份TeX文档,经过不同的环境编译之后,输出的排版都是完全一样的。
  • 使用LaTeX,精力可以放在撰写文档的内容,而非花大量的时间,用鼠标选中不同的文本段落,调整大量的排版样式。
  • TeX更多用于学术领域,很多出版社、大学会提供指定的学术论文模板, 比如MIT thesis templates或者非官方的上海交通大学学位论文模板。使用这些 模板,基本上不用考虑排版格式的问题,只要专心写文章就好了。
  • 很多专业的学术语言——复杂的数学公式,化学分子式,五线谱,电路图——是没法仅仅使用Office就能编写的。TeX可以2
  • TeX文档是一个普通的文本文档,这意味着,可以进行源代码的版本管理。

类似的所见非得系统还有Markdown,不过,Markdown更常用于网页展示:

  • Markdown语法定义了不同的HTML节点;
  • 不同的Markdown处理系统(在线编译网站,或者软件)定义不同的CSS样式;
  • 使得同样的Markdown文档,最终的展示并不一样。以“online markdown”为关键字搜索, 可以找到不同的在线Markdown编辑网站,它们对同一份文档的渲染结果是不同的。

TeX的使用说明

目前,我会优先考虑使用LaTeX,而非直接使用纯粹的TeX,因为前者的使用,能够将精力更多 的放在撰写的内容上。

使用LaTeX的过程中,建议积累自己的一份样式模板,并通过源代码管理这个过程。后面的附录会附上我自己积累的一份样式模板。

目前在LaTeX的使用过程中,碰到的问题有如下几类(详细的问题清单,也会附在后文的附录中,供参考):

  • 中文等CJK字体的编译问题:解决方案通常是选用合适的字体,配置不同格式的字体名称,需要留意字体的版权声明;
  • 文档编译出错:这时,需要仔细阅读编译日志,通常用编译日志中的错误信息在网上搜索,都能得到解决方案;
  • 不知道如何实现具体的排版样式:我目前没有精力仔细研究纯粹的TeX(plain TeX)语法,所以还是通过搜索 来解决问题。

可以从LaTexWikibook开始读起。 另外官方的tug.org和无所不知的stackoverflow都能找到 很多帮助文档。

准备一张 LaTeX Cheat Sheet 供参考。

TeXLaTeX的区别

正如前面说的那样:

  • TeX是一个排版系统的基础;
  • LaTeXTeX基础上,定义了很多便捷的样式模板;
  • XeLaTeX增加了对CJK的更好支持。

TeX注重排版

TeX更像一个排版系统,参考tex.stack问答 或者此处

Learn TeX only if you would like to become a typesetter

TeX is a system designed for typesetting

LaTeX注重内容

LaTeX能够更快地编写文档,但是没法体会到TeX的很多特性, 参考tug.org上的文档

知乎问答上,也给出了一个分类列表——TeX之于LaTeX,就像“引擎”之于“格式”。 知乎另一份问答里提到,TeXLaTeX的选择,需要一定的权衡:

用LaTeX的时候,还真有你想要某些功能而没有的情况。怎么办?两种办法:花钱找高人帮着写;自己写。

首先需要熟悉LaTeX的内部命令(大部分是含有@字符的命令),有时候这还不够, 万一碰到\expandafter,\futurelet,\ifvoid等等还得碰底层的primitive(基本命令)。 这个时候,还真就没plain TeX用着舒服。不过舒服也是有代价的, 因为plain TeX很短,能很快看完,但是前提是能够顺利地把TeXbook看完。

样例模板参考

LaTeX的格式样例

参考附录部分的样例模板。

学术论文格式样例

在互联网上总能找到很多学术论文的模板样例:

编译命令参考

# 文件名: build.sh

# 编译过程中如果出现异常中断,可能需要清除临时文件
# 谨慎使用git clean命令,这会删除untracked文件
# git clean -fx

# 编译入口
xelatex index.tex
# 编译索引
makeindex idx_finance.idx
# 编译参考文献
for x in {c,f} ; do
	bibtex $x
done

# 引用参考文献编号
xelatex index.tex
xelatex index.tex

LaTeX在Web页面的使用——基于KaTeX

如果想要体验在线编辑TeX文档,可以试用这两个网站:

  • sharelatex.com
  • overleaf.com

这里主要讨论Web页面中使用LaTeX语法,显示数学公式。常用的解决方案是在网页中嵌入MathJax库, 然后使用$$ \equation $$语法在网页中显示数学公式。

但是MathJax库的加载和公式渲染(render)比较耗时。 一个替代方案是使用KaTeX——出自Khan Academy 团队。 KaTeX的渲染速度得益于它将所有的数学公式用CSS的方式展示。

使用KaTeX需要注意的是:

  • 使用$$ \equation $$而非$ \equation $
  • 如果需要居中显示行级公式,可以自定义CSS
  • 目前KaTeX v0.5.0并不支持所有的LaTeX语法, 比如$$\LaTeX{}$$就无法被渲染。

Jekyll中的集成KaTeX

如下的公式就是通过KaTeX渲染的:

KaTeXJekyll中的集成,可以参考这篇文章(链接)。

gitbook中的集成KaTeX

gitbook已经提供了KaTeX的插件:gitbook-plugin-katex

附录

LaTeX使用过程中的问题列表

LaTeX Font Warning: Font shape undefined

如果一个字体集,少了粗体定义,则会出现这样的提示。解决方案是, 手动指定文档中粗体对应的字体:

% CJK for XeTeX
% http://www.ctan.org/pkg/xetexref
% https://zh.wikipedia.org/wiki/XeTeX
-\usepackage{xltxtra}
-\setmainfont[Mapping=tex-text]{WenQuanYi Micro Hei}
+% http://mirror.bjtu.edu.cn/CTAN/macros/xetex/latex/xecjk/xeCJK.pdf
+\usepackage{xltxtra, xeCJK}
+\setCJKmainfont[Mapping=tex-text]{WenQuanYi Micro Hei}
+\xeCJKsetup{AutoFakeBold=true, LoadFandol=false}

\begin{document}
\maketitle

latex error: file `multind.sty’ not found

Windows 下的MiKTeX 2.9不会出现这样的问题, Lubuntu 14.04下的TeX Live出现过这样的问题。 tex.ac.uk下的一份文档 指出:

makeidx.sty (is) Part of the LaTeX distribution

所以该文档尝试安装texlive-full来解决问题:

sudo apt-get install texlive-full
sudo texhash
sudo texconfig

如果想要尝试手动安装multind.sty,可以按照如下步骤:

makeindex finance不会生成Multi Index页面

finance是一个文件名,而非命令。对比如下两个命令:

scott@c9 [~/repo/notes] (master *)
$ makeindex finance
This is makeindex, version 2.15 [TeX Live 2013] (kpathsea + Thai support).
Scanning input file finance...done (0 entries accepted, 0 rejected).
Nothing written in finance.ind.
Transcript written in finance.ilg.

scott@c9 [~/repo/notes] (master *)
$ makeindex finance.idx
This is makeindex, version 2.15 [TeX Live 2013] (kpathsea + Thai support).
Scanning input file finance.idx....done (22 entries accepted, 0 rejected).
Sorting entries....done (106 comparisons).
Generating output file finance.ind....done (59 lines written, 0 warnings).
Output written in finance.ind.
Transcript written in finance.ilg.

xeCJK error: “key-unknown”

可能会在Lubuntu 14.04下遇到这样的问题:

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!
! xeCJK error: "key-unknown"
!
! Sorry, but xeCJK/options does not have a key called `LoadFandol'.
!
! The key `LoadFandol' is being ignored.
!
! See the xeCJK documentation for further information.
!
! Type <return> to continue.
!...............................................  

l.37 ...setup{AutoFakeBold=true, LoadFandol=false}

解决方案是,更换字体配置:

 \usepackage{xltxtra, xeCJK}
-\setCJKmainfont[Mapping=tex-text]{WenQuanYi Micro Hei}
+\setCJKmainfont[BoldFont=Adobe Heiti Std]{Adobe Song Std}
 \xeCJKsetup{AutoFakeBold=true, CJKmath=true}

+% Latin
+\usepackage{fontspec, pifont}
+\setmainfont{Gentium Book Basic}
+
 \begin{document}

CJK字体的选用

字体的选用,首先要注意版权的问题。

开源的CJK字体,可以选用文泉驿,或者思源黑体。 建议在配置中指定粗体、斜体等格式对应的字体文件。 不过,目前并不能顺利地在LaTeX中使用思源黑体, 参考知乎问答。 而且使用思源黑体,可能会遇到如下错误:

xelatex.exe: The font file could not be found.
xelatex.exe: Data: Source Sans Pro/OT

可以参考知乎专题的解决方案, 或者stackoverflow上的问答

除此之外,可以为印刷出版物选用经典的Adobe Song Std字体,但需留意 版权

顺带提一下,拉丁字符字体,可选用开源的Gentium字体集, 非常适合印刷出版物。

CJK字体不能在数学公式环境中显示

解决方案如下:

-\xeCJKsetup{AutoFakeBold=true}
+\xeCJKsetup{AutoFakeBold=true, CJKmath=true}

使用强调\emph而非加粗\textbf

对于需要加粗的段落,建议使用声明式的强调(\emph),而非命令式的加粗(\textbf)。

Wkibook/LaTeX中提到:

Do not use bold text in your paragraphs.

tex.stackexchange/Stefan Kottwitz也有这样的说明:

Further, I rarely use physical font commands in my body text. I use them to define styles in the preamble and use the styles in the document afterwards, ensuring consistency and allowing changes to be easily made.

可以参考此处 定义强调段落的样式:

+% bold emphasized text
+\makeatletter
+\DeclareRobustCommand{\em}{\%
+  \@nomath\em \if b\expandafter\@car\f@series\@nil
+  \normalfont \else \bfseries \fi}
+\makeatother

编译之后的文档输出有乱码

检查.tex文档的编码,是否为UTF-8

file -i *.tex

文献引用编号显示为[?]

仔细阅读编译日志,可以找到解决方案:

makeindex idx_finance.idx
bibtex index.aux
xelatex index.tex
+xelatex index.tex

也就是说,编译过程中,执行两次编译命令。

修改目录中“索引”的层级

如果想要将目录中“索引”的层级提高到“章节”级别,可以定义如下的排版格式:

+  \makeatletter
+  % Put section depth at the same level as \chapter.
+  \renewcommand*{\toclevel@section}{0}
   \printindex{idx_finance}{Index of Finance}
+  % Put section depth back to its default value.
+  \renewcommand*{\toclevel@section}{1}
+  \makeatother

定义“摘要”章节的样式

参考stackoverflow中的讨论:

% http://stackoverflow.com/q/2737326
+\chapter*{\centering \begin{normalsize}Abstract\end{normalsize}}
+\begin{quotation}
+\noindent % abstract text
% Abstract
+\end{quotation}
+\clearpage

模板样例

\documentclass[a4paper]{book}

% shortcut for scozv's github homepage
\usepackage{hyperref}
\newcommand{\scozv}{https://github.com/scozv}

% shortcut for \ding{213}
\newcommand{\To}{\ding{213}}

\usepackage{listings, color}
% shortcut for inline code snippet, like `code` in markdown
% \newcommand{\cd}[1]{\colorbox[rgb]{0.86,0.86,0.86}{\lstinline$#1$}}
\newcommand{\cd}[1]{\lstinline$#1$}

% shortcut for section, subsection, subsubsection
% mb stands for member
\newcommand{\mb}[1]{\subsection*{#1}}
\newcommand{\mmb}[1]{\subsubsection*{#1}}

% set style for multiple lines code snippet
\lstset{numbers=left, numberstyle=\tiny
	, stepnumber=2, numbersep=5pt
	, backgroundcolor=\color[rgb]{0.86,0.86,0.86}
	, basicstyle=\footnotesize\ttfamily
	, breaklines=true}

% set index
\usepackage{multind}
\makeindex{idx_finance}
\newcommand{\idxf}[1]{\index{idx_finance}{#1}}
% heading
\setcounter{secnumdepth}{3}

% set multi-ref
\usepackage{multibib}
\newcommand{\bibnamec}{References of Programming}
\newcites{c}{\bibnamec}
\newcommand{\bibnamef}{References of Finance}
\newcites{f}{\bibnamef}

% CJK for XeTeX
% http://www.ctan.org/pkg/xetexref
% https://zh.wikipedia.org/wiki/XeTeX
% http://ctan.org/pkg/xecjk
\usepackage{xltxtra, xeCJK}
\setCJKmainfont[BoldFont=Adobe Heiti Std]{Adobe Song Std}
\xeCJKsetup{AutoFakeBold=true, CJKmath=true}

% Latin
\usepackage{fontspec, pifont}
\setmainfont{Gentium Book Basic} %[ItalicFont=Gentium Book Basic Bold]

% intertext, trigleq and proof
\usepackage{amsmath, amssymb, amsthm}

% bold emphasized text
\makeatletter
\DeclareRobustCommand{\em}{\%
  \@nomath\em \if b\expandafter\@car\f@series\@nil
  \normalfont \else \bfseries \fi}
\makeatother

% tiny margin note
\makeatletter
  \long\def\@ympar#1{\%
  \@savemarbox\@marbox{\small #1}%
  \global\setbox\@currbox\copy\@marbox
  \@xympar}
\makeatother

% reduce the space of itemize
\newlength{\wideitemsep}%
\setlength{\wideitemsep}{.5\itemsep}%
\addtolength{\wideitemsep}{-7pt}%
\let\olditem\item
\renewcommand{\item}{\setlength{\itemsep}{\wideitemsep}\olditem}

\begin{document}
\title{Introduction of Building Documents with LaTeX}
\author{Scott}
\date{Aug, 12, 2015}
\maketitle

\chapter*{\centering \begin{normalsize}Abstract\end{normalsize}}
\begin{quotation}
\noindent % abstract text
This artical will give brief introduction for TeX and LaTeX,
then discuss a few issues during using LaTeX
and how to display LaTeX eqation on web page.
Finally, a LaTeX template will be attached in Appendix.
\end{quotation}
\clearpage

% no indent of second ... paragraphs of each section
\setlength{\parindent}{0pt}
\setlength{\parskip}{1.3ex plus 0.5ex minus 0.3ex}
\part{Part I}
  \chapter{C01-01}
    \include{p1_c01}
\part{Part II}
  \chapter{C02-01}
    \include{p2_c01}
  \chapter{C02-02}
    \include{p2_c02}

  \cleardoublepage
  \phantomsection
  \addcontentsline{toc}{chapter}{\bibnamec}
  \bibliographystylec{GBT7714-2005NLang}
  \bibliographyc{code/ref}

  \makeatletter
  % Put section depth at the same level as \chapter.
  \renewcommand*{\toclevel@section}{0}
  \printindex{idx_finance}{Index of Finance}
  % Put section depth back to its default value.
  \renewcommand*{\toclevel@section}{1}
  \makeatother  

  \cleardoublepage
  \phantomsection
  \addcontentsline{toc}{chapter}{\bibnamef}
  \bibliographystylef{GBT7714-2005NLang}
  \bibliographyf{finance/ref}

\appendix
\part{Appendix}
\chapter{Appendix I}
\include{appendix}
\end{document}

参考文献