path: root/macros/unicodetex/latex/beaulivre/beaulivre-doc-en.tex

\documentclass[English,Chinese,French,JP,TC,use boldface,simple name]{beaulivre}

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

\usepackage{relsize}

\usepackage{blindtext}

\UseLanguage{English}

%%================================
%% For typesetting code
%%================================
\usepackage{listings}
\definecolor{maintheme}{RGB}{70,130,180}
\definecolor{forestgreen}{RGB}{21,122,81}
\definecolor{lightergray}{gray}{0.99}
\lstset{language=[LaTeX]TeX,
    keywordstyle=\color{maintheme},
    basicstyle=\ttfamily,
    commentstyle=\color{forestgreen}\ttfamily,
    stringstyle=\rmfamily,
    showstringspaces=false,
    breaklines=true,
    frame=lines,
    backgroundcolor=\color{lightergray},
    flexiblecolumns=true,
    escapeinside={(*}{*)},
    % numbers=left,
    numberstyle=\scriptsize, stepnumber=1, numbersep=5pt,
    % firstnumber=last,
}
\providecommand{\meta}[1]{$\langle${\normalfont\itshape#1}$\rangle$}
\lstset{moretexcs=%
    {part,parttext,chapter,section,subsection,subsubsection,frontmatter,mainmatter,backmatter,tableofcontents,href,
    color,NameTheorem,CreateTheorem,cref,DNF,needgraph,UseLanguage,UseOtherLanguage,AddLanguageSetting,maketitle,address,curraddr,email,keywords,subjclass,thanks,dedicatory,TheDate,ProjLib,qedhere
    }
}
\lstnewenvironment{code}%
{\setstretch{1.07}%
\setkeys{lst}{columns=fullflexible,keepspaces=true}%
}{}
\lstnewenvironment{code*}%
{\setstretch{1.07}%
\setkeys{lst}{numbers=left,columns=fullflexible,keepspaces=true}%
}{}

%%================================
%% tip
%%================================
\usepackage[many]{tcolorbox}
\newenvironment{tip}[1][Tip]{%
    \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/04/24}

\frontmatter

\TitlePage [ color = { main = forestgreen!75!black, back = forestgreen!10!yellow!30 } ]
  {
    , title     = \beaulivre{}
    , subtitle  = {
                    \textsc{Write your books in \\a colorful way}\\[20pt]
                    \smaller[3] Corresponding to: \texttt{\beaulivre{} \PackageVersion}
                  }
    , author    = Jinwen XU
    , date      = {\TheDate{\PackageVersion}[only-year-month], in Paris}
  }


\chapter{Preface}

\beaulivre{} is a member of the \colorist{} class series. Its name is taken from French words ``beau'' (for ``beautiful'') and ``livre'' (for ``book''). The entire collection includes \colorart{} and \lebhart{} for typesetting articles and \colorbook{} and \beaulivre{} for typesetting books. My original intention in designing this series was to write drafts and notes that look colorful yet not dazzling.

\beaulivre{} has multi-language support, including Chinese (simplified and traditional), English, French, German, Italian, Japanese, Portuguese (European and Brazilian), Russian and Spanish. These languages can be switched seamlessly in a single document. Due to the usage of custom fonts, \lebhart{} requires \hologo{XeLaTeX} or \hologo{LuaLaTeX} to compile.

This documentation is typeset using \beaulivre{} (with the option \texttt{use boldface}). You can think of it as a short introduction and demonstration.

\bigskip
\begin{tip}
    Multi-language support, theorem-like environments, draft marks and some other features are provided by the \ProjLib{} toolkit. Here we only briefly discuss how to use it with this document class. For more detailed information, you can refer to the documentation of \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{Instruction}
\parttext{You can add some introductory text here via \lstinline|\\parttext|\meta{text}.}

\medskip
\LevelOneTitle*{Before you start}
\addcontentsline{toc}{chapter}{Before you start}
In order to use the package or classes described here, you need to:
\begin{itemize}
    \item install TeX Live or MikTeX of the latest possible version, and make sure that \texttt{colorist} and \texttt{projlib} are correctly installed in your \TeX{} system.
    \item download and install the required fonts, see the section "On the default fonts".
    \item be familiar with the basic usage of \LaTeX{}, and know how to compile your document with \hologo{pdfLaTeX}, \hologo{XeLaTeX} or \hologo{LuaLaTeX}.
\end{itemize}


\LevelOneTitle{Usage and examples}

\LevelTwoTitle{How to load it}

One only needs to put

\begin{code}
\documentclass{beaulivre}
\end{code}
as the first line to use the \beaulivre{} class.

\begin{tip}[Attention]
    You need to use either \hologo{XeLaTeX} or \hologo{LuaLaTeX} engine to compile.
\end{tip}

\LevelTwoTitle{Example - A complete document}

Let's first look at a complete document.


\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*}

If you find this example a little complicated, don't worry. Let's now look at this example piece by piece.

\LevelThreeTitle{Initialization}

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

Initialization is straightforward. The first line loads the document class \beaulivre{}, and the second line loads the \ProjLib{} toolkit to obtain some additional functionalities.

\LevelThreeTitle{Set the language}

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

This line indicates that French will be used in the document (by the way, if only English appears in your article, then there is no need to set the language). You can also switch the language in the same way later in the middle of the text. Supported languages include Simplified Chinese, Traditional Chinese, Japanese, English, French, German, Spanish, Portuguese, Brazilian Portuguese and Russian%
.%

For detailed description of this command and more related commands, please refer to the section on the multi-language support.


\LevelThreeTitle{Draft marks}

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

When you have some places that have not yet been finished yet, you can mark them with this command, which is especially useful during the draft stage.

\LevelThreeTitle{Theorem-like environments}

\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}

Commonly used theorem-like environments have been pre-defined. Also, when referencing a theorem-like environment, it is recommended to use \lstinline|\cref{|\meta{label}\texttt{\}} --- in this way, there is no need to explicitly write down the name of the corresponding environment every time.




\LevelOneTitle{On the default fonts}
By default, this document class uses Palatino Linotype as the English main font; Source Han Serif, Source Han Sans and Source Han Mono as the Chinese main font, sans serif font and typewriter font; and partially uses Neo Euler as the math font. You need to download and install these fonts by yourself. The Source Han font series can be downloaded at \url{https://github.com/adobe-fonts} (It is recommended to download the Super-OTC version, so that the download size is smaller). Neo Euler can be downloaded at \url{https://github.com/khaledhosny/euler-otf}. When the corresponding font is not installed, the font that comes with TeX Live will be used instead, and the effect may be discounted.

In addition, Source Code Pro is used as the English sans serif font, New Computer Modern Mono as the English monospace font, as well as some symbols in the mathematical fonts of Asana Math, Tex Gyre Pagella Math, and Latin Modern Math. These fonts are already available in TeX Live or MikTeX, which means you don't need to install them yourself.

\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 Math demonstration: \( \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{The options}

\beaulivre{} offers the following options:

\begin{itemize}
    \item The language options \texttt{EN} / \texttt{english} / \texttt{English}, \texttt{FR} / \texttt{french} / \texttt{French}, etc.
        \begin{itemize}
            \item For the option names of a specific language, please refer to \meta{language name} in the next section. The first specified language will be used as the default language.
            \item The language options are optional, mainly for increasing the compilation speed. Without them the result would be the same, only slower.
        \end{itemize}
    \item \texttt{draft} or \texttt{fast}
        \begin{itemize}
            \item The option \verb|fast| enables a faster but slightly rougher style, main differences are:
            \begin{itemize}
                \item Use simpler math font configuration;
                \item Do not use \textsf{hyperref};
                \item Enable the fast mode of \ProjLib{} toolkit.
            \end{itemize}
        \end{itemize}
    \begin{tip}
        During the draft stage, it is recommended to use the \verb|fast| option to speed up compilation. When in \verb|fast| mode, there will be a watermark ``DRAFT'' to indicate that you are currently in the draft mode.
    \end{tip}
    \item \texttt{a4paper} or \texttt{b5paper}
        \begin{itemize}
            \item Paper size options. The default paper size is 8.5in $\times$ 11in.
        \end{itemize}
    \item \texttt{palatino}, \texttt{times}, \texttt{garamond}, \texttt{noto}, \texttt{biolinum} ~$|$~ \texttt{useosf}
        \begin{itemize}
            \item Font options. As the name suggest, font with corresponding name will be loaded.
            \item The \texttt{useosf} option is used to enable the old-style figures.
        \end{itemize}
    \item \texttt{use boldface}
        \begin{itemize}
            \item Allow boldface. When this option is enabled, the main title, the titles of all levels and the names of theorem-like environments will be bolded.
        \end{itemize}
    \item \texttt{runin}
        \begin{itemize}
            \item Use the ``runin'' style for \lstinline|\subsubsection|
        \end{itemize}
    \item \texttt{nothms}
        \begin{itemize}
            \item Pure text mode. Do not load theorem-like environments.
        \end{itemize}
    \item \texttt{nothmnum}, \texttt{thmnum} or \texttt{thmnum=}\meta{counter}
        \begin{itemize}
            \item Theorem-like environments will not be numbered / numbered in order 1, 2, 3... / numbered within \meta{counter}. If no option is used, they will be numbered within \texttt{chapter} (book) or \texttt{section} (article).
        \end{itemize}
    \item \texttt{regionalref}, \texttt{originalref}
        \begin{itemize}
            \item When referencing, whether the name of the theorem-like environment changes with the current language. The default is \texttt{regionalref}, \emph{i.e.}, the name corresponding to the current language is used; for example, when referencing a theorem-like environment in English context, the names "Theorem, Definition..." will be used no matter which language context the original environment is in. If \texttt{originalref} is enabled, then the name will always remain the same as the original place; for example, when referencing a theorem written in the French context, even if one is currently in the English context, it will still be displayed as ``Théorème''.
            \item In \texttt{fast} mode, the option \texttt{originalref} will have no effect.
        \end{itemize}
\end{itemize}

\bigskip
In addition, the commonly used \texttt{oneside} and \texttt{twoside} options are also available. Two-page layout is used by default.

\LevelOneTitle{Instructions by topic}

\LevelTwoTitle{Language configuration}

\beaulivre{} has multi-language support, including Chinese (simplified and traditional), English, French, German, Italian, Japanese, Portuguese (European and Brazilian), Russian and Spanish. The language can be selected by the following macros:

\begin{itemize}
    \item \lstinline|\UseLanguage{|\meta{language name}\lstinline|}| is used to specify the language. The corresponding setting of the language will be applied after it. It can be used either in the preamble or in the main body. When no language is specified, ``English'' is selected by default.
    \item \lstinline|\UseOtherLanguage{|\meta{language name}\lstinline|}{|\meta{content}\lstinline|}|, which uses the specified language settings to typeset \meta{content}. Compared with \lstinline|\UseLanguage|, it will not modify the line spacing, so line spacing would remain stable when CJK and Western texts are mixed.
\end{itemize}

\meta{language name} can be (it is not case sensitive, for example, \texttt{French} and \texttt{french} have the same effect):
\begin{itemize}
    \item Simplified Chinese: \texttt{CN}, \texttt{Chinese}, \texttt{SChinese} or \texttt{SimplifiedChinese}
    \item Traditional Chinese: \texttt{TC}, \texttt{TChinese} or \texttt{TraditionalChinese}
    \item English: \texttt{EN} or \texttt{English}
    \item French: \texttt{FR} or \texttt{French}
    \item German: \texttt{DE}, \texttt{German} or \texttt{ngerman}
    \item Italian: \texttt{IT} or \texttt{Italian}
    \item Portuguese: \texttt{PT} or \texttt{Portuguese}
    \item Portuguese (Brazilian): \texttt{BR} or \texttt{Brazilian}
    \item Spanish: \texttt{ES} or \texttt{Spanish}
    \item Japanese: \texttt{JP} or \texttt{Japanese}
    \item Russian: \texttt{RU} or \texttt{Russian}
\end{itemize}

\medskip
In addition, you can also add new settings to selected language:
\begin{itemize}
    \item \lstinline|\AddLanguageSetting{|\meta{settings}\lstinline|}|
    \begin{itemize}
        \item Add \meta{settings} to all supported languages.
    \end{itemize}
    \item \lstinline|\AddLanguageSetting(|\meta{language name}\lstinline|){|\meta{settings}\lstinline|}|
    \begin{itemize}
        \item Add \meta{settings} to the selected language \meta{language name}.
    \end{itemize}
\end{itemize}
For example, \lstinline|\AddLanguageSetting(German){\color{orange}}| can make all German text displayed in orange (of course, one then need to add \lstinline|\AddLanguageSetting{\color{black}}| in order to correct the color of the text in other languages).

\LevelTwoTitle{Theorems and how to reference them}

Environments such as \texttt{definition} and \texttt{theorem} have been preset and can be used directly.

More specifically, preset environments include:
\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}, and the corresponding unnumbered version with an asterisk \lstinline|*| in the name. The titles will change with the current language. For example, \texttt{theorem} will be displayed as ``Theorem" in English mode and ``Théorème" in French mode.

When referencing a theorem-like environment, it is recommended to use \lstinline|\cref{|\meta{label}\texttt{\}}. In this way, there is no need to explicitly write down the name of the corresponding environment every time.

\begin{tip}[Example]
\begin{code}
\begin{definition}[Strange things] \label{def: strange} ...
\end{code}

will produce
\begin{definition}[Strange things]\label{def: strange}
    This is the definition of some strange objects. There is approximately a one-line spacing before and after the theorem environment, and there will be a symbol to mark the end of the environment.
\end{definition}

\lstinline|\cref{def: strange}| will be displayed as: \cref{def: strange}.

After using \lstinline|\UseLanguage{French}|, a theorem will be displayed as:

\UseLanguage{French}
\begin{theorem}[Inutile]\label{thm}
    Un théorème en français.
\end{theorem}

By default, when referenced, the name of the theorem matches the current context. For example, the definition above will be displayed in French in the current French context: \cref{def: strange,thm}. If you want the name of the theorem to always match the language of the context in which the theorem is located, you can add \texttt{originalref} to the global options.
\end{tip}

\UseLanguage{English}

The following are the main styles of theorem-like environments:
\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
For aesthetics, adjacent definitions will be connected together automatically:
\begin{definition}
    First definition.
\end{definition}

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

\begin{tip}
    Please refer to the documentation of the package \textsf{create-theorem} to see how to declare new theorem-like environments.
\end{tip}

% \clearpage
\LevelTwoTitle{Draft mark}

You can use \lstinline|\DNF| to mark the unfinished part. For example:
\begin{itemize}
    \item \lstinline|\DNF| or \lstinline|\DNF<...>|. The effect is: \DNF~ or \DNF<...>. \\The prompt text changes according to the current language. For example, it will be displayed as \UseOtherLanguage{French}{\DNF} in French mode.
\end{itemize}


\bigskip
\LevelOneTitle{Known issues}

\begin{itemize}
    \item The font settings are still not perfect.
    \item The TOC design does not look very nice.
    \item Since many features are based on the \ProjLib{} toolkit, \colorist{} (and hence \colorart{}, \lebhart{} and \colorbook{}, \beaulivre{}) inherits all its problems. For details, please refer to the ``Known Issues'' section of the \ProjLib{} documentation.
    \item The error handling mechanism is incomplete: there is no corresponding error prompt when some problems occur.
    \item There are still many things that can be optimized in the code.
\end{itemize}

\part{Demonstration}
\blinddocument

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