\documentclass[title in boldface, title in scshape, simple name]{beaulivre}

%%================================
%% Import toolkit
%%================================
\usepackage{ProjLib}
\usepackage{longtable}  % breakable tables
\usepackage{hologo}     % more TeX logo
\usetikzlibrary{calc}

\usepackage{blindtext}

\UseLanguage{Chinese}

%%================================
%% For typesetting code
%%================================
\usepackage{listings}
\usepackage{xcolor}
\usepackage{setspace}
\definecolor{code-main}{RGB}{70,130,180}
\definecolor{code-expl3}{RGB}{240,50,60}
\definecolor{code-option}{RGB}{40,110,20}
\definecolor{code-keys}{RGB}{100,130,150}
\definecolor{code-comment}{RGB}{20,120,80}
\definecolor{code-background}{gray}{0.99}
\lstset{
    language = [LaTeX]TeX,
    basicstyle = \ttfamily,
    keywordstyle = \color{code-main},
    commentstyle = \color{code-comment},
    showstringspaces = false,
    breaklines = true,
    frame = lines,
    backgroundcolor = \color{code-background},
    flexiblecolumns = true,
    escapeinside = {(*}{*)},
    alsoletter = {_,:},
    % numbers = left,
    % firstnumber = last,
    numberstyle = \scriptsize\ttfamily,
    stepnumber = 1,
    numbersep = 5pt,
}
\newcommand{\meta}[1]{$\langle${\normalfont\itshape#1}$\rangle$}
\lstset{% LaTeX2 commands
    classoffset = 0,
    texcsstyle =* \color{code-main},
    moretexcs =
      {
        linenumbers,nolinenumbers,
        part,parttext,chapter,section,subsection,subsubsection,
        frontmatter,mainmatter,backmatter,
        tableofcontents,
        href,
        color,
        NameTheorem,CreateTheorem,
        cref,
        ProjLib,
        DNF,
        UseLanguage,UseOtherLanguage,AddLanguageSetting,
        maketitle,address,curraddr,email,keywords,subjclass,thanks,dedicatory,TheDate,
        qedhere,
      }
}
\lstset{% LaTeX3 commands
    classoffset = 1,
    texcsstyle =* \color{code-expl3},
    moretexcs =
      {
      }
}
\lstnewenvironment{code}{\setstretch{1.05}}{\vspace{-.3\baselineskip}\vspace{-.5\parskip}}
\lstnewenvironment{code*}{\setstretch{1.05}\lstset{numbers=left}}{\vspace{-.3\baselineskip}\vspace{-.5\parskip}}

\newcommand{\classoption}[1]{\texttt{\textcolor{code-option}{#1}}}
\newcommand{\packageoption}[1]{\texttt{\textcolor{code-option}{#1}}}
\newcommand{\commandoption}[1]{\texttt{\textcolor{code-keys}{#1}}}

%%================================
%% tip
%%================================
\usepackage[many]{tcolorbox}
\newenvironment{tip}[1][提示]{%
    \begin{tcolorbox}[breakable,
        enhanced,
        width = \textwidth,
        colback = paper, colbacktitle = paper,
        colframe = gray!50, boxrule=0.2mm,
        coltitle = black,
        fonttitle = \sffamily,
        attach boxed title to top left = {yshift=-\tcboxedtitleheight/2, xshift=.5cm},
        boxed title style = {boxrule=0pt, colframe=paper},
        before skip = 0.3cm,
        after skip = 0.3cm,
        top = 3mm,
        bottom = 3mm,
        title={\scshape\sffamily #1}]%
}{\end{tcolorbox}}

%%================================
%% Names
%%================================
\providecommand{\colorist}{\textsf{colorist}}
\providecommand{\colorart}{\textsf{colorart}}
\providecommand{\colorbook}{\textsf{colorbook}}
\providecommand{\lebhart}{\textsf{lebhart}}
\providecommand{\beaulivre}{\textsf{beaulivre}}

%%================================
%% Titles
%%================================
\let\LevelOneTitle\chapter
\let\LevelTwoTitle\section
\let\LevelThreeTitle\subsection

%%================================
%% Main text
%%================================
\begin{document}

\def\PackageVersion{2022/09/03}

\frontmatter

\TitlePage [ color = { main = forestgreen!75!black, back = forestgreen!10!yellow!30 } ]
  {
    , title     = \beaulivre{}
    , subtitle  = {
                    \textsc{以多彩的方式排版你的图书}\\[20pt]
                    \smaller[3] 对应版本. \texttt{\beaulivre{} \PackageVersion}
                  }
    , author    = 许锦文
    , date      = {\TheDate{\PackageVersion}[only-year-month]，巴黎}
  }


\chapter{前言}

\beaulivre{} 是 \colorist{} 文档类系列的成员之一，其名称取自于法文的beau (美丽)，以及livre (书)，由二者组合而成。整个 \colorist{} 系列包含用于排版文章的 \colorart{}、\lebhart{} 以及用于排版书的 \colorbook{}、\beaulivre{}。我设计这一系列的初衷是为了撰写草稿与笔记，使之多彩而不缭乱。

\beaulivre{} 支持英语、法语、德语、意大利语、葡萄牙语、巴西葡萄牙语、西班牙语、简体中文、繁体中文、日文、俄文，并且同一篇文档中这些语言可以很好地协调。由于采用了自定义字体，需要用 \hologo{XeLaTeX} 或 \hologo{LuaLaTeX} 引擎进行编译。

这篇说明文档即是用 \beaulivre{} 排版的 (使用了参数 \classoption{use boldface})，你可以把它看作一份简短的说明与演示。

\bigskip
\begin{tip}
    多语言支持、定理类环境、未完成标记等功能是由 \ProjLib{} 工具箱提供的，这里只给出了将其与本文档类搭配使用的要点。如需获取更详细的信息，可以参阅 \ProjLib{} 的说明文档。
\end{tip}

\begin{tip}
    This documentation has not been fully up-to-date with the new \texttt{expl3} version of this class series. Some options or commands introduced here might be obsolete.
\end{tip}

\tableofcontents

\mainmatter

\part{说明}
\parttext{可以通过 \lstinline|\\parttext|\meta{text} 在这里添加一些说明}

\medskip
\LevelOneTitle*{开始之前}
为了使用这篇文档中提到的文档类，你需要：
\begin{itemize}
    \item 安装一个尽可能新版本的 TeX Live 或 MikTeX 套装，并确保 \texttt{colorist} 和 \texttt{projlib} 被正确安装在你的 \TeX 封装中。
    \item 下载并安装所需的字体，参考“关于默认字体”这一节。
    \item 熟悉 \LaTeX{} 的基本使用方式，并且知道如何用 \hologo{pdfLaTeX}、\hologo{XeLaTeX} 或 \hologo{LuaLaTeX} 编译你的文档。
\end{itemize}


\LevelOneTitle{使用示例}

\LevelTwoTitle{如何加载}

只需要在第一行写：

\begin{code}
\documentclass{beaulivre}
\end{code}

即可使用 \beaulivre{} 文档类。

\begin{tip}[请注意]
    要使用 \hologo{XeLaTeX} 或 \hologo{LuaLaTeX} 引擎才能编译。
\end{tip}

\LevelTwoTitle{一篇完整的文档示例}

首先来看一段完整的示例。


\begin{code*}
\documentclass{beaulivre}
\usepackage{ProjLib}

\UseLanguage{French}

\begin{document}

\frontmatter

\begin{titlepage}
    (*\meta{code for titlepage}*)
\end{titlepage}

\tableofcontents

\mainmatter

\part{(*\meta{part title}*)}
\parttext{(*\meta{text after part title}*)}

\chapter{(*\meta{chapter title}*)}

\section{(*\meta{section title}*)}

\DNF<(*\meta{some hint}*)>

\begin{theorem}\label{thm:abc}
    Ceci est un théorème.
\end{theorem}
Référence du théorème: \cref{thm:abc}

\backmatter

...

\end{document}
\end{code*}

如果你觉得这个例子有些复杂，不要担心。现在我们来一点点地观察这个例子。

\LevelThreeTitle{初始化部分}

\begin{code}
\documentclass{beaulivre}
\usepackage{ProjLib}
\end{code}

初始化部分很简单：第一行加载文档类 \beaulivre{}，第二行加载 \ProjLib{} 工具箱，以便使用一些附加功能。

\LevelThreeTitle{设定语言}

\begin{code}
\UseLanguage{French}
\end{code}

这一行表明文档中将使用法语（如果你的文章中只出现英语，那么可以不需要设定语言）。你也可以在文章中间用同样的方式再次切换语言。支持的语言包括简体中文、繁体中文、日文、英语、法语、德语、西班牙语、葡萄牙语、巴西葡萄牙语、俄语。

对于这一命令的详细说明以及更多相关命令，可以参考后面关于多语言支持的小节。


\LevelThreeTitle{未完成标记}

\begin{code}
\DNF<(*\meta{some hint}*)>
\end{code}
当你有一些地方尚未完成的时候，可以用这条指令标记出来，它在草稿阶段格外有用。

\LevelThreeTitle{定理类环境}

\begin{code}
\begin{theorem}\label{thm:abc}
    Ceci est un théorème.
\end{theorem}
Référence du théorème: \cref{thm:abc}
\end{code}

常见的定理类环境可以直接使用。在引用的时候，建议采用智能引用 \lstinline|\cref{|\meta{label}\lstinline|}|——这样就不必每次都写上相应环境的名称了。




\LevelOneTitle{关于默认字体}
本文档类中默认使用 Palatino Linotype 作为英文主字体，思源宋体、思源黑体、思源等宽作为中文主字体、无衬线字体以及等宽字体，并部分使用了 Neo Euler 作为数学字体。这些字体需要用户自行下载安装。其中，思源字体系列可在 \url{https://github.com/adobe-fonts} 下载 (推荐下载 Super-OTC 版本，这样下载的体积较小)。Neo Euler可以在 \url{https://github.com/khaledhosny/euler-otf} 下载。在没有安装相应的字体时，将采用TeX Live中自带的字体来代替，效果可能会有所折扣。

另外，还使用了 Source Code Pro 作为英文无衬线字体、New Computer Modern Mono 作为英文等宽字体，以及 Asana Math、Tex Gyre Pagella Math、Latin Modern Math 数学字体中的部分符号。这些字体在 TeX Live 或 MikTeX 中已经提供，无需自行下载安装。

\begin{itemize}
    \item English main font. \textsf{English sans serif font}. \texttt{English typewriter font}.
    \item 简体中文主要字体，\textsf{简体中文无衬线字体}，\texttt{简体中文等宽字体}
    \item \UseOtherLanguage{TC}{繁體中文主要字體，\textsf{繁體中文無襯線字體}，\texttt{繁體中文等寬字體}}
    \item \UseOtherLanguage{JP}{日本語のメインフォント、\textsf{日本語のサンセリフフォント}、\texttt{日本語の等幅フォント}}
    \item 数学示例： \( \alpha, \beta, \gamma, \delta, 1,2,3,4, a,b,c,d \), \[\mathrm{li}(x)\coloneqq \int_2^{\infty} \frac{1}{\log t}\,\mathrm{d}t \]
\end{itemize}


\LevelOneTitle{选项}

\beaulivre{} 文档类有下面几个选项：

\begin{itemize}[label=,leftmargin=1.25em,itemindent=-1.25em]
    \item 语言选项 \classoption{EN} / \classoption{english} / \classoption{English}、\classoption{FR} / \classoption{french} / \classoption{French}，等等
        \begin{itemize}
            \item 具体选项名称可参见下一节的 \meta{language name}。第一个指定的语言将作为默认语言。
            \item 语言选项不是必需的，其主要用途是提高编译速度。不添加语言选项时效果是一样的，只是会更慢一些。
        \end{itemize}
    \item \classoption{draft} 或 \classoption{fast}
        \begin{itemize}
            \item 你可以使用选项 \verb|fast| 来启用快速但略微粗糙的样式，主要区别是：
            \begin{itemize}
                \item 使用较为简单的数学字体设置；
                \item 不启用超链接；
                \item 启用 \ProjLib{} 工具箱的快速模式。
            \end{itemize}
        \end{itemize}
    \begin{tip}
        在文章的撰写阶段，建议使用 \verb|fast| 选项以加快编译速度，改善写作时的流畅度。使用 \verb|fast| 模式时会有“DRAFT”字样的水印，以提示目前处于草稿阶段。
    \end{tip}
    \item \classoption{a4paper} 或 \classoption{b5paper}
        \begin{itemize}
            \item 可选的纸张大小。默认的纸张大小为 8.5in $\times$ 11in。
        \end{itemize}
    \item \classoption{palatino}、\classoption{times}、\classoption{garamond}、\classoption{noto}、\classoption{biolinum} ~$|$~ \classoption{useosf}
        \begin{itemize}
            \item 字体选项。顾名思义，会加载相应名称的字体。
            \item \classoption{useosf} 选项用来启用“旧式”数字。
        \end{itemize}
    \item \classoption{use boldface}
        \begin{itemize}
            \item 允许加粗。启用这一选项时，题目、各级标题、定理类环境名称会被加粗。
        \end{itemize}
    \item \classoption{runin}
        \begin{itemize}
            \item \lstinline|\subsubsection| 采用 ``runin'' 风格。
        \end{itemize}
    \item \classoption{nothms}
        \begin{itemize}
            \item 纯文本模式，不加载定理类环境。
        \end{itemize}
% \clearpage
    \item \classoption{nothmnum}、\classoption{thmnum} 或 \classoption{thmnum=}\meta{counter}
        \begin{itemize}
            \item 定理类环境均不编号 / 按照 1、2、3 顺序编号 / 在 \meta{counter} 内编号。在没有使用任何选项的情况下将按照 \texttt{chapter} (书) 或 \texttt{section} (文章) 编号。
        \end{itemize}
    \item \classoption{regionalref}、\classoption{originalref}
        \begin{itemize}
            \item 在智能引用时，定理类环境的名称是否随当前语言而变化。默认为 \classoption{regionalref}，即引用时采用当前语言对应的名称；例如，在中文语境中引用定理类环境时，无论原环境处在什么语境中，都将使用名称“定理、定义……”。若启用 \classoption{originalref}，则引用时会始终采用定理类环境所处语境下的名称；例如，在英文语境中书写的定理，即使稍后在中文语境下引用时，仍将显示为 Theorem。
            \item 在 \classoption{fast} 模式下，\classoption{originalref} 将不起作用。
        \end{itemize}
\end{itemize}
\bigskip
另外，排版图书时常用的 \classoption{oneside}、\classoption{twoside} 选项也是可以使用的。默认采用双页排版。

\LevelOneTitle{具体说明}

\LevelTwoTitle{语言设置}

\beaulivre{} 提供了多语言支持，包括英语、法语、德语、意大利语、葡萄牙语、巴西葡萄牙语、西班牙语、简体中文、繁体中文、日文、俄文。可以通过下列命令来选定语言：
\begin{itemize}
    \item \lstinline|\UseLanguage{|\meta{language name}\lstinline|}|，用于指定语言，在其后将使用对应的语言设定。
    \begin{itemize}
        \item 既可以用于导言部分，也可以用于正文部分。在不指定语言时，默认选定 “English”。
    \end{itemize}
    \item \lstinline|\UseOtherLanguage{|\meta{language name}\lstinline|}{|\meta{content}\lstinline|}|，用指定的语言的设定排版 \meta{content}。
    \begin{itemize}
        \item 相比 \lstinline|\UseLanguage|，它不会对行距进行修改，因此中西文字混排时能保持行距稳定。
    \end{itemize}
\end{itemize}

\meta{language name} 有下列选择 (不区分大小写，如 \texttt{French} 或 \texttt{french} 均可)：
\begin{itemize}
    \item 简体中文：\texttt{CN}、\texttt{Chinese}、\texttt{SChinese} 或 \texttt{SimplifiedChinese}
    \item 繁体中文：\texttt{TC}、\texttt{TChinese} 或 \texttt{TraditionalChinese}
    \item 英文：\texttt{EN} 或 \texttt{English}
    \item 法文：\texttt{FR} 或 \texttt{French}
    \item 德文：\texttt{DE}、\texttt{German} 或 \texttt{ngerman}
    \item 意大利语：\texttt{IT} 或 \texttt{Italian}
    \item 葡萄牙语：\texttt{PT} 或 \texttt{Portuguese}
    \item 巴西葡萄牙语：\texttt{BR} 或 \texttt{Brazilian}
    \item 西班牙语：\texttt{ES} 或 \texttt{Spanish}
    \item 日文：\texttt{JP} 或 \texttt{Japanese}
    \item 俄文：\texttt{RU} 或 \texttt{Russian}
\end{itemize}

另外，还可以通过下面的方式来填加相应语言的设置：
\begin{itemize}
    \item \lstinline|\AddLanguageSetting{|\meta{settings}\lstinline|}|
    \begin{itemize}
        \item 向所有支持的语言增加设置 \meta{settings}。
    \end{itemize}
    \item \lstinline|\AddLanguageSetting(|\meta{language name}\lstinline|){|\meta{settings}\lstinline|}|
    \begin{itemize}
        \item 向指定的语言 \meta{language name} 增加设置 \meta{settings}。
    \end{itemize}
\end{itemize}
例如，\lstinline|\AddLanguageSetting(German){\color{orange}}| 可以让所有德语以橙色显示（当然，还需要再加上 \lstinline|\AddLanguageSetting{\color{black}}| 来修正其他语言的颜色）。

\LevelTwoTitle{定理类环境及其引用}

定义、定理等环境已经被预定义，可以直接使用。

具体来说，预设的定理类环境包括：
\texttt{assumption}、\texttt{axiom}、\texttt{conjecture}、\texttt{convention}、\texttt{corollary}、\texttt{definition}、\texttt{definition-proposition}、\texttt{definition-theorem}、\texttt{example}、\texttt{exercise}、\texttt{fact}、\texttt{hypothesis}、\texttt{lemma}、\texttt{notation}、\texttt{observation}、\texttt{problem}、\texttt{property}、\texttt{proposition}、\texttt{question}、\texttt{remark}、\texttt{theorem}，以及相应的带有星号 \lstinline|*| 的无编号版本。

在引用定理类环境时，建议使用智能引用 \lstinline|\cref{|\meta{label}\lstinline|}|。这样就不必每次都写上相应环境的名称了。

\medskip
\begin{tip}[例子]
\begin{code}
\begin{definition}[奇异物品] \label{def: strange} ...
\end{code}
将会生成
\begin{definition}[奇异物品]\label{def: strange}
    这是奇异物品的定义。定理类环境的前后有一行左右的间距。在定义结束的时候会有一个符号来标记。
\end{definition}

\lstinline|\cref{def: strange}| 会显示为：\cref{def: strange}。

\medskip
使用 \lstinline|\UseLanguage{English}| 后，定理会显示为：

\UseLanguage{English}
\begin{theorem}[Useless]\label{thm}
    A theorem in English.
\end{theorem}

默认情况下，引用时，定理类环境的名称总是与当前语言相匹配，例如，上面的定义在现在的英文模式下将显示为英文：\cref{def: strange,thm}。如果在引用时想让定理的名称总是与原定理所在区域的语言匹配，即总是显示原始名称，可以在全局选项中加入 \texttt{originalref}。
\end{tip}

\UseLanguage{Chinese}

\bigskip
下面是定理类环境的几种主要样式：
\begin{theorem}
    Theorem style: theorem, proposition, lemma, corollary, ...
\end{theorem}

\begin{proof}
    Proof style
\end{proof}

\begin{remark}
    Remark style
\end{remark}

\begin{conjecture}
    Conjecture style
\end{conjecture}

\begin{example*}
    Example style: example, fact, ...
\end{example*}

\begin{problem}
    Problem style: problem, question, ...
\end{problem}

\medskip
% \clearpage
为了美观，相邻的定义环境会自动连在一起：
\begin{definition}
    First definition.
\end{definition}

\begin{definition}
    Second definition.
\end{definition}

\begin{tip}
    请参阅 \textsf{create-theorem} 的说明文档以获知如何定义新的定理类环境。
\end{tip}

\LevelTwoTitle{未完成标记}

你可以通过 \lstinline|\DNF| 来标记尚未完成的部分。例如：
\begin{itemize}
    \item \lstinline|\DNF| 或 \lstinline|\DNF<...>|。效果为：\DNF~或 \DNF<...>。\\其提示文字与当前语言相对应，例如，在法语模式下将会显示为 \UseOtherLanguage{French}{\DNF}。
\end{itemize}


\bigskip
\LevelOneTitle{目前存在的问题}
\begin{itemize}
    \item 对于字体的设置仍然不够完善。
    \item 目录的设计还不够美观。
    \item 由于很多核心功能建立在 \ProjLib{} 工具箱的基础上，因此 \colorist{} (进而 \colorart{}、\lebhart{} 与 \colorbook{}、\beaulivre{}) 自然继承了其所有问题。详情可以参阅 \ProjLib{} 用户文档的“目前存在的问题”这一小节。
    \item 错误处理功能不完善，在出现一些问题时没有相应的错误提示。
    \item 代码中仍有许多可优化之处。
\end{itemize}

\part{演示}
\blinddocument

\end{document}
\endinput
%%
%% End of file `beaulivre/beaulivre-doc-cn.tex'.
