v0.1

.gitignore

@@ -19,7 +19,7 @@
 # these rules might exclude image files for figures etc.
 # *.ps
 # *.eps
-# *.pdf
+tlmgr-intro-zh-cn.pdf
 
 ## Generated if empty string is given at "Please type another file name for output:"
 .pdf
@@ -274,3 +274,5 @@ TSWLatexianTemp*
 
 # Makeindex log files
 *.lpz
+
+.history

.latexmkrc

@@ -0,0 +1,33 @@
+
+@default_files = ('tlmgr-intro-zh-cn.tex');
+
+# Cleanup mode 
+# [2 is for doing aux files cleanup before building, ex]
+# [1 is for doing ALL output files cleanup]
+# [0 is for not doing cleanup]
+$cleanup_mode = 0;
+
+# Use XeLaTeX to compile. 
+# [5 is XeLaTeX]
+$pdf_mode = 1;
+
+$clean_ext = "synctex.gz acn acr alg aux bbl bcf blg brf fdb_latexmk glg glo gls idx ilg ind lof log lot out run.xml toc pdf thm toe ist idx";
+
+# Preview mode & Auto complie after save. 
+$preview_continuous_mode = 1;
+
+# Set XeLaTeX option.
+$pdflatex = "xelatex -halt-on-error  -interaction=nonstopmode -synctex=1 %O %S";
+
+# Process index. [Use Chinese index program]
+# $makeindex = 'zhmakeindex %O -o %D %S';
+
+# Preview mode 
+# [1 is for running a previewer after building]
+# [0 is for not running it]
+# $preview_mode = 1;
+
+
+$show_time=1;
+
+$sleep_time=1;

README.md

@@ -1 +1,8 @@
-# tlmgr-intro-zh-cn
+# 关于 `tlmgr` 使用方法的简介
+
+这个文档是对 [texdoc tlmgr](https://www.tug.org/texlive/devsrc/Master/texmf-dist/doc/latex/tlmgrbasics/tlmgr.pdf) 的翻译以及补充. 由于翻译水平与专业知识有限, 文档中有一些词汇和语句翻译的并不好, 如果您有更好的翻译或者纠正我的错误, 可以在该项目处提出 [issue](https://github.com/syvshc/tlmgr-intro-zh-cn/issues) 或者 [PR](https://github.com/syvshc/tlmgr-intro-zh-cn/pulls). 
+
+TeX Live 使用 `tlmgr` 来管理安装方案, 集合和软件包, 如果还没有安装 TeX Live, 可以参考 [install-latex-guide-zh-cn](https://www.tug.org/texlive/devsrc/Master/texmf-dist/doc/latex/install-latex-guide-zh-cn/install-latex-guide-zh-cn.pdf) 与 [texlive-zh-cn](https://www.tug.org/texlive/doc/texlive-zh-cn/texlive-zh-cn.pdf) 进行安装. 但是 [`tlmgr` 官方文档](https://www.tug.org/texlive/doc/tlmgr.html) 过于冗长, 有很多一般用户接触不到的功能, 在这里将它简化, 拿出一些比较基础使用的命令来介绍. 
+
+# 开源协议
+本文档遵循 GNU GPL 3.0 及以后的开源协议. 

body/examples.tex

@@ -0,0 +1,20 @@
+% !TeX root = ../tlmgr-intro-zh-cn.tex
+
+\section{例子}\label{sec:examples}
+
+在成功安装 \tl 后, 可以使用一些 \tlmgr 上的常用配置. 
+
+\begin{description}
+    \item \tlmgr{} \ac{option} \key{repository} \val{ctan}\par
+    告诉 \tlmgr 它可以从一个附近的 CTAN 镜像去获取最近的更新. 
+    \item \tlmgr{} \ac{update} \op{-list}\par
+    列出所有可以被更新的内容. 
+    \item \tlmgr{} \ac{update} \op{-all}\par
+    更新全部的安装包. 
+    \item \tlmgr{} \ac{update} \op{-self}\par
+    升级 \tlmgr 本身. 
+    \item \tlmgr{} \ac{info} \marg{pkgs}\par
+    列出 \marg{pkgs} 的详细信息, 比如它们的安装状态, 版本号, 介绍等等. 
+\end{description}
+
+

body/mirrors.tex

@@ -0,0 +1,53 @@
+% !TeX root = ../tlmgr-intro-zh-cn.tex
+\section{中国大陆地区的源}\label{app:mirror}
+
+如果要更换大陆地区的源, 需要使用\footnote{这一节的内容来自 \href{https://www.tug.org/texlive/doc/texlive-zh-cn/texlive-zh-cn.pdf}{install-latex-guide-zh-cn}}
+\begin{quote}
+    \tlmgr{} \ac{option} \key{repository} \marg{url}\texttt{/tlnet}
+\end{quote}
+需要将 \marg{url} 更换为表 \ref{tab:appendix:mirror} 中的 \tl 源地址. 
+\begin{table}[!hb]
+    \centering
+    \caption{大陆地区目前可用的源 (名称按拼音排序)}\label{tab:appendix:mirror}
+    \begin{tabular}{*{2}{l}}
+      \toprule
+      镜像站名称 & \tl 源地址\\\midrule
+      \href{https://developer.aliyun.com/mirror/}{阿里云}
+      & \url{https://mirrors.aliyun.com/CTAN/systems/texlive/}\\
+      \href{https://mirror.bjtu.edu.cn/}{北京交通大学}
+      & \url{https://mirror.bjtu.edu.cn/ctan/systems/texlive/}\\
+      \href{https://mirrors.bit.edu.cn/web/}{北京理工大学}
+      & \url{https://mirrors.bit.edu.cn/CTAN/systems/texlive/}\\
+      \href{https://mirrors.bfsu.edu.cn/}{北京外国语大学}
+      & \url{https://mirrors.bfsu.edu.cn/CTAN/systems/texlive/}\\
+      \href{https://mirrors.cqu.edu.cn/}{重庆大学}
+      & \url{https://mirrors.cqu.edu.cn/CTAN/systems/texlive/}\\
+      \href{https://mirrors.dgut.edu.cn/}{东莞理工学院}
+      & \url{https://mirrors.dgut.edu.cn/CTAN/systems/texlive/}\\
+      \href{https://mirrors.hit.edu.cn/}{哈尔滨工业大学}
+      & \url{https://mirrors.hit.edu.cn/CTAN/systems/texlive/}\\
+      \href{https://mirrors.huaweicloud.com/}{华为云}
+      & \url{https://mirrors.huaweicloud.com/CTAN/systems/texlive/}\\
+      \href{http://mirrors.hust.edu.cn/}{华中科技大学}
+      & \url{http://mirrors.hust.edu.cn/CTAN/systems/texlive/}\\
+      \href{https://mirror.lzu.edu.cn/}{兰州大学}
+      & \url{https://mirror.lzu.edu.cn/CTAN/systems/texlive/}\\
+      \href{https://mirrors.nju.edu.cn/}{南京大学}
+      & \url{https://mirrors.nju.edu.cn/CTAN/systems/texlive/}\\
+      \href{https://mirrors.tuna.tsinghua.edu.cn/}{清华大学}
+      & \url{https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/}\\
+      \href{https://mirrors.sjtug.sjtu.edu.cn/}{上海交通大学}
+      & \url{https://mirrors.sjtug.sjtu.edu.cn/ctan/systems/texlive/}\\
+      \href{https://mirrors.geekpie.club/}{上海科技大学}
+      & \url{https://mirrors.geekpie.club/CTAN/systems/texlive/}\\
+      \href{https://mirrors.cloud.tencent.com/}{腾讯云}
+      & \url{https://mirrors.cloud.tencent.com/CTAN/systems/texlive/}\\
+      \href{https://mirrors.ustc.edu.cn/}{中国科学技术大学}
+      & \url{https://mirrors.ustc.edu.cn/CTAN/systems/texlive/}\\
+      % \href{https://mirrors.zju.edu.cn/}{浙江大学}
+      % & \url{https://mirrors.zju.edu.cn/CTAN/systems/texlive/}\\
+      % \href{http://mirror.neu.edu.cn/}{东北大学}
+      % & \url{http://mirror.neu.edu.cn/CTAN/systems/texlive/}\\
+      \bottomrule
+    \end{tabular}
+\end{table}

body/options.tex

@@ -0,0 +1,20 @@
+% !TeX root = ../tlmgr-intro-zh-cn.tex
+\section{全局选项 (GLOBAL OPTIONS)}
+\begin{description}
+    \item \op{-help}, \op{-h}, \op{-?}\par
+    这些选项可以显示任何一个操作的参考文档. 
+    \item \op{-version}\par
+    显示 \tl 发行版以及 \tlmgr 本身的版本信息, 如果同时指定了 \op{-v} 选项, \tl{} Perl 模块的版本号也会被显示. 
+    \item \op{-q}\par
+    抑致输出信息的生成. 
+    \item \op{-v}\par
+    显示调试信息, 重复使用 \op{-v} 来显示更多的调试信息. 
+    \item \op{-command-logfile} \marg{file}\par
+    \tlmgr 把所有程序 (\texttt{mktexlr}, \texttt{mtxrun}, \texttt{fmtutil}, \texttt{updmap}) 的输出都记录在了一个 log 文件中, 这个文件默认在 \texttt{TEXMFSYSVAR/web2c/tlmgr-commands.log}. 这个选项允许用户把日志存放在 \marg{file} 中. 
+    \item \op{-package-logfile} \marg{file}\par
+    \tlmgr 把所有对软件包的操作 (\ac{install}, \ac{remove}, \ac{update}, failed updates, failed restores) 记录在一个 log 文件中, 这个文件默认在 \texttt{TEXMFSYSVAR/web2c/tlmgr.log}. 这个选项允许用户把日志存放在 \marg{file} 中. 
+    \item \op{-pause}\par
+    这个选项让 \tlmgr 在退出之前等待用户输入. 可以有效地防止 Windows 10 中命令行窗口在运行后直接消失. 
+    \item \op{-repository} \marg{url\textup{|}path}\par
+    用来临时修改当前命令的仓库位置, 可以选择远端位置 \marg{url} 或者本地位置 \marg{path}, 如果想更改默认仓库位置, 可以使用 \tlmgr{} \ac{option} \key{repository}, 见 \nameref{subsec:option}. 
+\end{description}

body/preface.tex

@@ -0,0 +1,22 @@
+% !TeX root = ../tlmgr-intro-zh-cn.tex
+\section*{前\quad 言}
+\addcontentsline{toc}{section}{前言}
+
+这个文档是对 \href{https://www.tug.org/texlive/devsrc/Master/texmf-dist/doc/latex/tlmgrbasics/tlmgr.pdf}{\texttt{texdoc tlmgr}} 的翻译以及补充. 由于翻译水平与专业知识有限, 文档中有一些词汇和语句翻译的并不好, 如果您有更好的翻译或者纠正我的错误, 可以在该项目处提出 \href{https://github.com/syvshc/tlmgr-intro-zh-cn/issues}{issue} 或者 \href{https://github.com/syvshc/tlmgr-intro-zh-cn/pulls}{PR}. 
+
+\tlmgr 管理着 \tl 的安装, 包括软件包以及配置选项. 如果还没有安装 \tl, 可以参考 \href{https://www.tug.org/texlive/devsrc/Master/texmf-dist/doc/latex/install-latex-guide-zh-cn/install-latex-guide-zh-cn.pdf}{install-latex-guide-zh-cn} 与 \href{https://www.tug.org/texlive/doc/texlive-zh-cn/texlive-zh-cn.pdf}{texlive-zh-cn} 进行安装. 
+
+\tl 是由一些最高级别的\textbf{安装方案} (schemes) 构成的, 每一种方案中包含一些\textbf{集合} (collections) 和\textbf{软件包} (packages), 而每一个集合中也包含了一些软件包, 软件包中包含了一些可以看到的文件. 在安装 \tl 的时候, 我们可以选择在不同的级别来进行安装和管理. 比如在安装的时候可以只选则安装最小的安装方案 \texttt{minimal scheme (plain only)}, 以及一部分语言和功能的集合, 比如 \texttt{Chinese} 与 \texttt{LaTeX additional packages}
+
+\begin{center}
+    \includegraphics[height=4cm]{scheme.png} \quad 
+    \includegraphics[height=4cm]{collection.png}
+    \captionof{figure}{Schemes 与 collections}
+\end{center}
+
+使用 \tlmgr 管理这些安装方案, 集合和软件包是很有必要的, 但是 \href{https://www.tug.org/texlive/doc/tlmgr.html}{\tlmgr 官方文档} 过于冗长, 有很多一般用户接触不到的功能, 在这里将它简化, 拿出一些比较基础使用的命令来介绍. 
+
+\tlmgr 也提供了图形界面: \texttt{tlshell}, \texttt{tlcockpit}, 在 Mac 上, 有 \tl{} Utility, 这些都需要启动另外的程序, 这篇简介只介绍命令行下的使用, 关于图形界面的使用可以看
+\begin{center}
+    \url{https://tug.org/texlive/doc/tlmgr.html#GUI-FOR-TLMGR}.
+\end{center}

body/syntex.tex

@@ -0,0 +1,25 @@
+% !TeX root = ../tlmgr-intro-zh-cn.tex
+
+\section{基本格式与说明}
+
+\subsection{{\mdseries\tlmgr} 命令的基本格式:}
+
+
+% \begin{lstlisting}
+%         +\tlmgr+ [+\textit{global option}+] <+\textit{action}+> [+\textit{action-specific option}+] [+\textit{operand}+]
+% \end{lstlisting}
+
+\begin{quote}
+    \tlmgr{} \texttt{[}\op{\textit{global options}}\texttt{]} \texttt{<}\ac{\textit{action}}\texttt{>} \texttt{[}\op{\textit{action-specific options}}\texttt{]} \oarg{operand}
+\end{quote}
+
+\subsection{文档记号说明}
+
+\begin{enumerate}[(1)]
+    \item \tlmgr 的\textbf{选项} (option) 分为全局选项与特定命令的选项, 它们一般以 \texttt{-} 或 \texttt{-{}-} 开头. 但是所有的选项可以在一条命令的任意位置, 按任意顺序调用. 一条命令中第一个不是选项的参数会称为这条命令的主要\textbf{操作} (action). 
+    \item 在所有的情况中, \texttt{-option} 与 \texttt{-{}-option} 等价. 
+    \item 文档中被中括号 \texttt{[arg]} 框起来的为可选参数, 如 \texttt{install [\textit{option}]},
+    \item 文档中被尖括号 \texttt{<arg>} 框起来的为必选参数, 如 \texttt{info <\textit{pkg}>},
+    \item 文档中被竖线 \texttt{|} 分隔的参数为 $ n $ 选 $ 1 $, 如 \op{-repository} \marg{url\textup{|}path} 表示选项 \op{-repository} 后面可以选择远端地址 \texttt{\textit{url}} 或本地位置 \texttt{\textit{path}},
+    \item 文档中用斜体标出的参数 \texttt{\textit{arg}} 表示参数的类型, 用直立体标出的参数 \texttt{arg} 表示参数需要直接填 \texttt{arg}, 比如 \ac{backup} \marg{pkgs\textup{|-all}} 表示 \ac{backup} 操作后可以跟参数 \texttt{-all} 或软件包类型的参数. 
+\end{enumerate}

tlmgr-intro-zh-cn.sty

@@ -0,0 +1,67 @@
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{tlmgr-intro-zh-cn}[20200306 v0.1 test]
+
+% 版式设计
+\RequirePackage[margin=2.4cm]{geometry}
+\RequirePackage{fancyhdr}
+\pagestyle{fancy}
+\RequirePackage{tocloft}
+\renewcommand{\cftsecleader}{\bfseries\cftdotfill{\cftdotsep}}
+\RequirePackage{FiraMono}
+
+% 超链接与颜色
+\RequirePackage[colorlinks]{hyperref}
+\RequirePackage[dvipsnames]{xcolor}
+\hypersetup{linkcolor = Purple}
+
+\RequirePackage{listings}
+\RequirePackage[shortlabels]{enumitem}
+
+% 浮动体
+\RequirePackage{tabularx}
+\RequirePackage{booktabs}
+\RequirePackage{graphicx}
+\RequirePackage{caption}
+\graphicspath{{./fig/}}
+
+\lstset{
+    basicstyle      = {\ttfamily},
+    keywordstyle  = \color{blue}\bfseries,
+    commentstyle    = \color{gray}, 
+    stringstyle     = \color{brown}, 
+    breaklines      = true,
+    gobble          = 2,
+    escapechar      = +,
+}
+
+\ctexset{
+    section         = {
+        % afterskip    = {}, 
+        format       = \Large\bfseries\raggedright,
+        number       = \arabic{section},
+        name         = {},
+    },
+    subsection       = {
+        afterskip    = {1.5ex plus .2ex},
+        format       = \large\bfseries\raggedright,
+    }  
+}
+
+\newcommand{\tlmgr}{\texttt{tlmgr}}
+\newcommand{\tl}{\TeX\,Live}
+
+\newcommand{\marg}[2][\textit]{\texttt{<#1{#2}>}}
+\newcommand{\oarg}[2][\textit]{\texttt{[#1{#2}]}}
+\newcommand{\op}[1]{\texttt{#1}}
+\newcommand{\ac}[1]{\texttt{#1}}
+\newcommand{\key}[1]{\texttt{#1}}
+\newcommand{\val}[1]{\texttt{#1}}
+
+% textlabel from https://tex.stackexchange.com/questions/54854/reference-plain-text
+% \makeatletter
+% \newcommand*{\textlabel}[2]{%
+%   \edef\@currentlabel{#1}% Set target label
+%   \phantomsection% Correct hyper reference link
+%   #1\label{#2}% Print and store label
+% }
+% \makeatother

tlmgr-intro-zh-cn.tex

@@ -0,0 +1,20 @@
+\documentclass[fontset=fandol, 9pt]{ctexart}
+\usepackage{tlmgr-intro-zh-cn}
+\title{\bfseries 关于 {\mdseries\texttt{tlmgr}} 使用方法的简介%
+\thanks{\url{https://github.com/syvshc/tlmgr-intro-zh-cn}}%
+}
+\author{Syvshc}
+\date{\today}
+\begin{document}
+    \maketitle
+
+    \include{./body/preface}
+    \tableofcontents
+    \clearpage
+    \include{./body/syntex.tex}
+    \include{./body/examples}
+    \include{./body/options}
+    \include{./body/actions}
+    \appendix
+    \include{./body/mirrors}
+\end{document}