Introduction of Building Documents with LaTeX

摘要

TeX家族是一个专业的排版系统。本文简要地介绍了TeX家族的常见成员,并整理出了LaTeX入门使用过程中会遇到的一些问题, 同时,将演示LaTeX在网页中的集成。最后在附录部分,给出了样式模板的参考代码。

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.

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相比:

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

TeX的使用说明

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

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

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

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

准备一张 LaTeX Cheat Sheet 供参考。

TeXLaTeX的区别

正如前面说的那样:

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文档,可以试用这两个网站:

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

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

使用KaTeX需要注意的是:

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}

参考文献