diff --git a/.gitignore b/.gitignore index 859f705..463fd3a 100644 --- a/.gitignore +++ b/.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 \ No newline at end of file diff --git a/.latexmkrc b/.latexmkrc new file mode 100644 index 0000000..3643a21 --- /dev/null +++ b/.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; \ No newline at end of file diff --git a/README.md b/README.md index 4a832b5..61e720f 100644 --- a/README.md +++ b/README.md @@ -1 +1,8 @@ -# tlmgr-intro-zh-cn \ No newline at end of file +# 关于 `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 及以后的开源协议. \ No newline at end of file diff --git a/body/actions.tex b/body/actions.tex new file mode 100644 index 0000000..91a4a84 --- /dev/null +++ b/body/actions.tex @@ -0,0 +1,354 @@ +% !TeX root = ../tlmgr-intro-zh-cn.tex +\section{操作 (ACTIONS)} + +\subsection{\mdseries\ac{info}} + +\paragraph{使用方法:} + +% \begin{lstlisting} +% tlmgr info [collections|schemes|+\textit{pkgs}+] +% \end{lstlisting} + +\begin{quote} + \tlmgr{} \ac{info} \oarg{\upshape collections|schemes|\textit{pkgs}}. +\end{quote} + +如果不带参数, 将会列出所有软件包仓库中的软件包, 把哪些已经被安装的软件包加上前缀 \texttt{i}. + +如果带参数 \texttt{collections} 或 \texttt{schemes}, 将会列出全部的集合或安装方案, 而不列出软件包, 同样地, 把已经安装的集合或安装方案加上前缀 \texttt{i}. + +如果带了任意其他的参数, 将会依次列出 \marg{pkgs} 中的每一个软件包的信息: 名称 (name), 分类 (category), 简短和详细的介绍 (short and long description), 软件包大小 (size), 安装状态 (status), 以及 \tl 中的版本号. 如果这个软件包没有在本地安装, 那么 \tlmgr 将会在远端仓库去查找它. + +对于普通的软件包 (除了集合与安装方案), 软件包大小是分 4 个部分显示的 (run/src/doc/bin). 对于集合, 显示的是所有直接\textbf{从属} (dependent) 于它的软件包的大小总和, 但是不包括从属的集合. 对于安装方案, 显示的是所有直接从属于它的集合与软件包的大小总和. + +如果在本地与线上都没有完整的匹配结果, 那么 \tlmgr 将会使用 \ac{search} 操作寻找名称与它相关的软件包, 见 \nameref{subsec:search} 小节. + +\ac{info} 操作也会显示从 \TeX\,Catalogue 获取的信息: 软件包版本 (package revision), 日期 (date), 以及许可证 (license). 不过这些信息, 尤其是软件包版本, 获得的信息只能用做参考, 这是由于不同部分的更新有时间差. + +旧操作 \ac{show} 与 \ac{list} 已经被合并到了 \ac{info} 操作中, 但是为了兼容性这两个操作仍然可用. + +\paragraph{{\mdseries\ac{info}} 的特有选项:} +\begin{description} + \item \op{-list}\par + 如果 \op{-list} 与一个软件包一起指定, 那么将会同时列出这个软件包包含的文件, 包括那些特定平台上的从属包. 如果与 \texttt{collections} 或者 \texttt{schemes} 一起指定, 那么 \op{-list} 将会以一个相似的方式输出依赖关系. + \item \op{-only-installed}\par + 如果指定这个选项, 那么将不会使用安装源的信息, 只会显示本地已经安装的软件包, 集合或安装方案. + \item \op{-only-remote}\par + 只列出远端仓库中的软件包, 下面是一条测试哪些软件包在某远端仓库中可用的命令: + \begin{quote} + \tlmgr{} \op{-repo} \marg{url} \op{-only-remote} \ac{info} + \end{quote} + 注意 \op{-only-installed} 与 \op{-only-remote} 不能同时使用. +\end{description} + +\clearpage + +\subsection{\mdseries\ac{search}}\label{subsec:search} + +\paragraph{使用方法:} +\begin{quote} + \tlmgr{} \ac{search} \marg{what}. +\end{quote} + +默认状态下, \tlmgr{} 会在所有本地安装的软件包中搜索名字, 短描述与长描述中是否含有参数 \marg{what}, 其中 \marg{what} 被解释为一个 (Perl) 正则表达式. + +\paragraph{{\mdseries\ac{search}} 的特有选项:} +\begin{description} + \item \op{-file}\par + 列出含有 \marg{what} 的文件名 (含路径), 比如使用 + \begin{quote} + \tlmgr{} \ac{search} \op{-file} \texttt{amsmath} + \end{quote} + 那么包含在文件夹 \texttt{amsmath} 下的文件也会被显示, 无论它们的文件名是否含有 \texttt{amsmath}. + \item \op{-global}\par + 在安装介质 (installation medium) 的 \tl{} Database 中搜索, 而不是本地安装. + \item \op{-word}\par + 严格匹配软件包的名字与描述 (并不是文件名). 比如使用 + \begin{quote} + \tlmgr{} \ac{search} \op{-word} \texttt{table} + \end{quote} + 就不会匹配到含有 \texttt{tables} 的软件包, 除非它同时含有一个 \texttt{table}. + \item \op{-all}\par + 匹配所有的项目: 软件包名, 长短描述与文件名 (含路径). +\end{description} + +\clearpage + +\subsection{\mdseries\ac{install}} +\paragraph{使用方法:} +\begin{quote} + \tlmgr{} \ac{install} \marg{pkgs}. +\end{quote} + +安装 \marg{pkgs} 中的每一个软件包, 除非某软件包已经被安装过了. 默认状态下所有指定的的软件包的从属文件也会被同时安装. \ac{install} 操作不会更改已经安装的软件包, 如果想使用最新版本的软件包, 可以使用 \nameref{subsec:update} 小节介绍的 \ac{update} 操作. + +\paragraph{{\mdseries\ac{install}} 的特有选项:} +\begin{description} + \item \op{-dry-run}\par + 在终端显示将要执行的操作, 而不进行安装. + \item \op{-reinstall}\par + 重新安装一个软件包 (包括对集合的依赖), 即使它看起来已经安装了, 比如它已经存在于 TLPDB (\tl{} Package Database) 中. 这个选项对于恢复在层级中不小心删除的软件包很有用. + + 重新安装时，只遵循对普通包的依赖 (不遵循类别Scheme或Collection的依赖)% + \footnote{When re-installing, only dependencies on normal packages are followed (i.e., not those of category Scheme or Collection).}. + \item \op{-with-doc}, \op{-with-src}\par + \texttt{install-tl} 给了一个 ``不安装文档/源文件'' 的选项, 但是我们不推荐使用这个选项. (默认状态下会安装所有的文件). 如果用了这个选项, 那么当用户想获得软件包的文档或者源文件的时候, 可以使用这两个选项与 \op{--reinstall}, 用 \texttt{fontspec} 宏包为例: + \begin{quote} + \tlmgr{} \ac{install} \op{-reinstall} \op{-with-doc} \op{-with-src} \texttt{fontspec} + \end{quote} + \item \op{-no-depends}\par + 不安装软件包的从属. (默认状态下, 安装一个软件包会保证它包含它所有的从属. ) +\end{description} + + \textbf{注意}: \ac{install} 操作并不会自动向系统目录中添加新的\textbf{符号链接} (symlinks), 需要自行运行 + \begin{quote} + \tlmgr{} \ac{path} \key{add} + \end{quote} + 如果您想使用这个功能并且想添加新的符号链接, 可以阅读 \href{https://www.tug.org/texlive/doc/tlmgr.html#path}{path} 操作. + +\subsection{\mdseries{\ac{update}}}\label{subsec:update} + +\paragraph{使用方法:} +\begin{quote} + \tlmgr{} \ac{update} \marg{\textup{-all|}pkgs} +\end{quote} + +把参数 \marg{pkgs} 中的宏包升级到安装源中最新的可用版本, 必须指定 \marg{\textup{-all}} 或至少一个软件包. + +\paragraph{{\mdseries\ac{update}} 的特有选项:} +\begin{description} + \item \op{-all}\par + 升级全部的软件包 (除了 \tlmgr{} 本身). 如果把 \tlmgr 也列出安装范围将会报错, 除非同时指定了 \op{-force} 与 \op{-self} 选项. (见下) + + 除了对已安装的软件包进行升级之外, 对本地安装的集合的升级 (默认是) 将它与服务器上的集合进行同步, 无论是新增还是移除. + + 类似地, 如果服务器上的一个本地已经安装的集合新增了一个软件包, 那么它将会被加入本地安装, 这被称作 ``auto-install'', 同时会在使用选项 \op{-list} 的时候被显示. + + 在集合从属软件包的检查中, 如果有一些被用户强制删除 (forcibly removed), 也就是用户使用对它们使用了 \tlmgr{} \ac{remove} \op{-force} 命令 (见 \nameref{subsec:remove} 小节). 如果想重新安装任何一个被强制删除的软件包, 要使用 \hyperlink{op:-reinstall-forcibly-removed}{\op{-reinstall-forcibly-removed}} 选项. + + 重申一遍: 自动新增与移除是完全通过集合之间的比较完成的. 因此, 如果用户手动安装了一个稍后将被服务器移除的软件包, \tlmgr{} 不会注意到它, 也不会在本地移除它. (尽量不要主动进行架构重组，因为 TLPDB 不记录软件包的来源仓库\footnote{It has to be this way, without major rearchitecture work, because the tlpdb does not record the repository from which packages come from.}) + + 如果用户想在最近的更新中忽略某些软件包, 可以使用下面的 \hyperlink{op:exclude}{\op{-exclude}} 选项. + \item \op{-self}\par + 如果有更新的 \tlmgr 版本存在, 那么升级 \tlmgr{} 本身, 即 \tlmgr 的基础架构. 在 Windows 设备上这个选项也会升级 \tl 自带的 Perl 解释器. + + 如果这个选项与 \op{-all} 一起被指定, 那么 \tlmgr 将会先升级自身, 如果成功了, \tlmgr 将会自动重启并执行接下来的升级. + + 表 \ref{tab:update} 展示了 \ac{update} 中 \op{-self} 与 \op{-all} 的关系. + \begin{table} + \caption{\ac{update}的几种关系}\label{tab:update} + \begin{center} + \begin{tabularx}{35em}{>{\raggedright}p{14em}@{\texttt{\#}\ }>{\raggedright\arraybackslash\ttfamily}X}\toprule + \tlmgr{} \ac{update} \op{-self} & 仅升级 \tlmgr 本身\\ + \tlmgr{} \ac{update} \op{-self} \op{-all} & 升级 \tlmgr 本身和全部可升级软件包\\ + \tlmgr{} \ac{upadte} \op{-force} \op{-all} & 升级全部软件包但是\textbf{不}升级 \tlmgr\\ + & 最后一个有风险, 不建议使用!\\\bottomrule + \end{tabularx} + \end{center} + \end{table} + \item \op{-dry-run}\par + 在终端显示将要执行的操作, 而不进行安装. 这个选项有比 \op{-list} 更详细的显示内容. + \item \op{-list} \oarg{pkgs}\par + 简略地列出即将被更新, 新增或移除的软件包, 但不做实质的更改. 如果同时指定了 \op{-all}, 那么将列出所有可用的更新. 如果同时指定了 \op{-self} 但是不指定 \op{-all}, 那么只会列出可更新的核心软件包 (\tlmgr, \tl 的核心架构, Windows 上的 Perl 等等). + + 如果不指定 \op{-all} 或 \op{-self}, 但是给出了具体的软件包 \oarg{pkgs}, 那么将检查 \oarg{pkgs} 中的可更新软件包并列出. + + 如果不指定 \op{-all} 或 \op{-self}, 同时也没有给出 \oarg{pkg}, 那么 \tlmgr 就会假定使用了 \op{-all}, 也就是说 \tlmgr{} \ac{update} \op{-\op{list}} 与 \tlmgr{} \ac{update} \op{-list} \op{-all} 是一样的. + \item \hypertarget{op:exclude}{\op{-exclude} \marg{pkg}} \par + 在更新程序中排除软件包 \marg{pkg} 本身以及所有平台特定的软件包, 比如 + \begin{quote} + \tlmgr{} \ac{update} \op{-all} \op{-exclude} \texttt{a2ping} + \end{quote} + 将不会升级 \texttt{a2ping}, \texttt{a2ping.i386-linux}, 以及任何其它的 \texttt{a2ping.xxx} 软件包. + + 如果这个选项指定了一个宏包, 程序将会在以下情况报错并退出: \marg{pkg} 将被自动安装, \marg{pkg} 将被自动移除, 或者 \marg{pkg} 是被手动删除并需要被重新安装\footnote{reinstallation of a forcibly removed package.}的时候. \op{-exclude} 选项不支持这些情况. + \item \op{-no-dependent}\par + 如果用户升级一个软件包, 正常情况下所有依赖的软件包在必要的情况下都会被升级. 这个选项会抑致这个行为. + \item \hypertarget{op:-reinstall-forcibly-removed}{\op{-reinstall-forcibly-removed}}\par + 在通常情况下 \tlmgr 不会自动安装那些被用户强制删除的软件包, 比如被 \ac{remove} \op{-force} 删除, 或者在之前的升级中被选项 \op{-no-auto-install} 禁止安装的软件包. + \item \op{-no-auto-remove} \oarg{pkgs}\par + 默认状态下, \tlmgr 将会尝试删除存在于集合中但是在服务器中已经被删除的软件包. 这个选项会阻止这些删除操作, 如果同时指定 \op{-all} 则范围为全部软件包, 如果指定 \oarg{pkgs}, 则范围为给定的软件包. 这可能导致 \TeX 安装的不一致, 因为软件包的作者可能重命名软件包或者改变软件包的位置, 所以这个选项不推荐使用\footnote{This can lead to an inconsistent TeX installation, since packages are not infrequently renamed or replaced by their authors. Therefore this is not recommended.}. + \item \op{-no-auto-install} \oarg{pkgs}\par + 默认状态下, \tlmgr 会自动安装服务器上的新软件包, 与指定选项 \op{-all} 的效果相同. 这个选项阻止了所有的自动安装, 如果同时指定 \op{-all} 则范围为全部软件包, 如果指定 \oarg{pkgs}, 则范围为给定的软件包. + + 此外, 在 \op{-no-auto-install} 选项下完成升级之后, 那些应该被自动安装的软件包会被认为成\textbf{被用户强制删除的}. 所以, 如果 \texttt{foobar} 是唯一一个服务器上新增的软件包, 那么 + \begin{quote} + \tlmgr{} \ac{update} \op{-all} \op{-no-auto-install} + \end{quote} + 等价于 + \begin{quote} + \tlmgr{} \ac{upadte} \op{-all}\\ + \tlmgr{} \ac{remove} \op{-force} \texttt{foobar} + \end{quote} + 同样地, 因为软件包的作者可能重命名软件包或者改变软件包的位置, 所以这个选项不推荐使用. + \item \hypertarget{op:backup}{\op{-backup}, \op{-backupdir} \marg{dir}}\par + 这两个选项会在\textbf{升级之前}创建软件包的备份, 也就是说会备份升级之前最新的软件包, 如果不指定这两个选项, 那么将不会创建备份. 如果指定了 \op{-backupdir} 同时 \marg{dir} 是一个可写且有足够空间的路径, 那么 \tlmgr 将会在这个路径下创建备份文件. 如果仅指定了 \op{-backup}, 那么备份将会被创建在 \nameref{subsec:option} 小节中设置的位置, 默认在 \tl 根目录下的 \texttt{texlive//tlpkg/backups} 中. + + \textbf{注}: \href{https://www.tug.org/texlive/doc/tlmgr.html#update-option...-pkg}{tlmgr 文档} 原文为: If neither option is given, no backup will made. 但是 \tlmgr 在 \tl{}2010 以后将自动备份关键词 \key{autobackup} 默认设置为 1, 也就是说, 即使不使用 \op{-backup} 选项, 也会自动将软件包备份在默认位置, 方便用户使用 \nameref{subsec:restore} 操作回滚. 更新日志见 \href{https://www.tug.org/texlive/doc/texlive-en/texlive-en.html#x1-780009.1.7}{texlive-en} + + \item \op{-force}\par + 强制升级所有软件包, 不包括 \tlmgr 本身, 除非同时指定了 \op{-self} 选项. 不推荐. + + 同样地, \ac{update} \op{-list} 将会无视这个选项按它本身该有的样子显示. +\end{description} + +\textbf{注意}: 如果本地安装的软件包的版本高于服务器端的时候 (比如设置的镜像站过时了), \tlmgr 会忽略这个软件包而不进行降级. + +\clearpage + +\subsection{\mdseries{\ac{restore}}}\label{subsec:restore} + +\paragraph{使用方法:} + +\begin{quote} + \ac{restore} \oarg{pkg} \oarg{revision} \\ + \ac{restore} \marg{\upshape -all} +\end{quote} + +这个操作将从之前的备份中回滚软件包版本. + +如果指定了 \marg{\upshape -all}, 那么将会从可找到的备份中回滚所有的软件包版本. + +如果不指定 \oarg{pkg} 与 \oarg{revision}, 那么将列出所有软件包的可用备份的版本. + +如果指定了 \oarg{pkg} 但是没有指定 \oarg{revision}, 那么就列出软件包 \oarg{pkg} 的所有可用的备份版本, 比如使用 \tlmgr{} \ac{restore} \texttt{fancyhdr}, 那么将会得到如下形式的输出 +\begin{verbatim} + Available backups for fancyhdr: xxxxx (yyyy-MM-dd HH:mm) +\end{verbatim} +其中 \texttt{xxxxx} 为 \texttt{fancyhdr} 可用备份的版本号. + +当且仅当同时指定 \oarg{pkg} 与一个可用的版本号 \oarg{revision} 时, \tlmgr 会从备份中将 \oarg{pkg} 回滚到版本 \oarg{revision}. + +\paragraph{\textmd{\ac{restore}}的特有选项:} +\begin{description} + \item \op{-all}\par + 尝试从从可找到的备份中回滚所有的软件包版本. 其他的非选项 (non-option) 的参数, 如 \oarg{pkg} 将不可用. + \item \op{-backupdir} \marg{dir}\par + 指定一个供 \tlmgr 获取备份的路径, 如果不使用这个选项, 那么 \tlmgr 就会使用从 TLPDB 的配置文件. + \item \op{-dry-run}\par + 在终端显示将要执行的操作, 而不进行回滚. + \item \op{-force}\par + 强制进行回滚\footnote{原文为: Don't ask questions.}. + \item \op{-json}\par + 将输出打印为 JSON 样式. +\end{description} + +\clearpage + +\subsection{\mdseries{\ac{remove}}}\label{subsec:remove} + +\paragraph{使用方法:} + +\begin{quote} + \tlmgr{} \ac{remove} \marg{pkgs} +\end{quote} + +移除 \marg{pkgs} 中给出的软件包. 如果要移除一个集合, 那么将移除这个集合下的所有软件包. 除非指定了 \op{-no-depends}, 入市不移除这个集合下的任何集合. 然而, 当移除一个软件包的时候, 它的从属永远不会被移除. + +\paragraph{\textmd{\ac{remove}}的特有选项:} +\begin{description} + \item \op{-dry-run}\par + 在终端显示将要执行的操作, 而不进行实质的删除. + \item \op{-no-depends}\par + 不移除从属软件包. + \item \op{-all}\par + 卸载整个 \tl, 会询问用户是否删除, 除非指定了 \op{-force} 选项. + \item \op{-force}\par + 默认状态下, 移除一个软件包或者一个集合的从属集合是不允许的. 使用这个选项可以无条件地轶软件包, 要谨慎使用. + + 如果使用 \tlmgr{} \ac{remove} \op{-force} 移除了一个软件包, 那它在 \tlmgr{} \ac{update} \op{-list} 中被认为是 \texttt{forcibly removed}. +\end{description} + +\clearpage + +\subsection{\mdseries{\ac{option}}}\label{subsec:option} +\paragraph{使用方法:} + +\begin{quote} + \tlmgr{} \ac{option} \\ + \tlmgr{} \ac{option} \texttt{help} \\ + \tlmgr{} \ac{option} \marg{key} \\ + \tlmgr{} \ac{option} \marg{key} \oarg{value} +\end{quote} + +\begin{enumerate}[(1)] + \item 第一种形式列出当前的全局 \tl 设置, 带有一个简短的介绍, 每一种设置里括号中的词就是修改这个设置需要的 \key{key}, 比如要修改备份文件的路径 可以使用 \tlmgr{} \ac{option} \key{backupdir} \oarg{dir}. + \begin{quote} + \ttfamily Directory for backups (\textbf{backupdir}): tlpkg/backups + \end{quote} + \item 第二种形式与第一种很像, 它会在 \tlmgr{} \ac{option} 的基础上列出可以被设置但是当前没有值的选项, + \item 第三种形式是列出 \marg{key} 对应的值, + \item 第四种形式将 \marg{key} 的值设置为 \oarg{value} +\end{enumerate} + +表 \ref{tab:option} 中是一些可用的 \marg{key} 值. 使用 \tlmgr{} \ac{option} \key{help} 来获得更详细的列表 + +\begin{table}[!hpb] + \caption{\tlmgr{} \ac{option} 的部分可用选项}\label{tab:option} + \begin{center} + \begin{small} + \begin{tabular}{>{\ttfamily}ll} + autobackup & 升级操作是否备份,\\ + backupdir & 备份文件的位置,\\ + repository & 默认的软件包仓库,\\ + docfiles & 安装文档文件,\\ + srcfiles & 安装源文件,\\ + sys\_bin & 通过 \texttt{path} 操作链接到的可执行文件的目录\\ + sys\_man & 通过 \texttt{path} 操作链接到的手册文件的目录\\ + sys\_info& 通过 \texttt{path} 动作链接到的信息文件的目录\\ + desktop\_integration & 仅 Windows: 创建开始菜单的快捷方式\\ + fileassocs& 仅 Windows: 改变文件关联\\ + multiuser & 仅 Windows: 为所有用户安装\\ + \end{tabular} + \end{small} + \end{center} +\end{table} + + +一个常见 \ac{option} 的用法是它可以在从 DVD 安装以后, 永久地改变安装的设置来通过互联网获得更新. 比如, 用户可以使用 +\begin{quote} + \tlmgr{} \ac{option} \key{repository} \val{ctan} +\end{quote} +来从一个附近的 CTAN 镜像来获得更新. + +但是中国大陆用户可能无法获取到实际``附近''的镜像站, 很多时候需要用户手动指定大陆地区的源. 详细信息见 \nameref{app:mirror} 一节. + +\key{docfiles} 与 \key{srcfiles} 分别控制着每个软件包的文件组 (文档, 源文件)\footnote{The \texttt{\scriptsize docfiles} and \texttt{\scriptsize srcfiles} keys control the installation of their respective file groups documentation, sources; grouping is approximate) per package.} 这两个 \marg{key} 的默认值都是 \texttt{1}, 如果用户的硬盘空间不足, 或者只是想做一个最小的安装测试, 那么每一个都可以被修改成 \texttt{0}, 这样就不会再下载这些相关的文件了. + +\key{sys\_bin}, \key{sys\_man}, \key{sys\_info} 选项是在 Unix 系统上使用的, 控制着对于可执行文件, 信息文件, 手册页面链接的生成. 详细信息见 \href{https://www.tug.org/texlive/doc/tlmgr.html#path}{path} 操作 + +其余的选项控制着 Windows 安装的表现. +\begin{itemize} + \item 如果设置了 \key{desktop\_integration}, 那么一些软件包将会把文件安装在开始菜单的 \tlmgr{} \ac{gui} 中, 比如文档等等. + \item 如果设置了 \key{fileassocs}, 将会建立 Windows 下的文件关联. 见 \href{https://www.tug.org/texlive/doc/tlmgr.html#postaction}{\ac{postaction}} 操作. + \item 如果设置了 \key{multiuser}, 那么对注册表和菜单的调整将针对系统上的所有用户, 而不仅仅是当前用户. +\end{itemize} +这三个选项默认都是开启的. + +\clearpage + +\subsection{\mdseries{\ac{backup}}}\label{subsec:backup} +\paragraph{使用方法:} + +\begin{quote} + \tlmgr{} \ac{backup} \marg{pkgs\textup{|-all}} +\end{quote} + +如果没有指定 \op{-clean} 选项, 那么这个操作会在默认位置, 为 \marg{pkgs} 中的每一个软件包创建一个备份文件, 如果使用了 \texttt{-all} 选项, 那么将创建全部软件包的备份. + +备份文件的位置由 \op{-backupdir} \marg{dir} 指定, 前提是 \marg{dir} 存在且可写. 如果没有指定 \op{-backupdir}, 那么就会使用 TLPDB 设置中的 \key{backupdir} 路径. 如果二者皆空, 那么就不会创建备份. 关于 \op{backupdir} 的信息可以参考 \ac{update} 操作的 \hyperlink{op:backup}{\op{-backupdir}} 选项. + +如果指定了 \op{-clean} 选项, 那么将会删除备份文件, 而不是创建备份. 这个选项有一个可选的整数值 \texttt{N} 来指定清理时保留的备份数量. 如果没有指定 \texttt{N}, 那么将会使用 \key{autobackup} 的值, 它在 TLPDB 中的默认值为 \texttt{1}, 如果二者皆空, 那么将会报错. + +\paragraph{\textmd{\ac{backup}}的特有选项:} +\begin{description} + \item \op{-backupdir} \marg{dir}\par + 临时盖 TLPDB 中 \key{backupdir} 的值, 参数 \marg{dir} 必须指定, 这是备份文件存放的路径, 它必须要存在且可写. + \item \op{-all}\par + 如果没有指定 \op{-clean} 选项, 那么创建一个 \tl 安装过的所有软件包的备份, 这会消耗大量的存储空间与时间, 如果指定了 \op{-clean} 选项, 所有的备份将被删除. + \item \op{-clean[=N]}\par + 删除备份目录 \key{backupdir} 中的旧备份, 而不创建备份. 可选整数参数 \texttt{N} 会临时覆盖 TLPDB 中的 \key{autobackup} 的值, 如果使用这个选项, 那么必须要指定 \op{-all} 或者一列软件包. + \item \op{-dry-run}\par + 在终端显示将要执行的操作, 而不进行备份. +\end{description} + diff --git a/body/examples.tex b/body/examples.tex new file mode 100644 index 0000000..04eb535 --- /dev/null +++ b/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} + + diff --git a/body/mirrors.tex b/body/mirrors.tex new file mode 100644 index 0000000..e82ec8b --- /dev/null +++ b/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} \ No newline at end of file diff --git a/body/options.tex b/body/options.tex new file mode 100644 index 0000000..68f73d6 --- /dev/null +++ b/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} \ No newline at end of file diff --git a/body/preface.tex b/body/preface.tex new file mode 100644 index 0000000..96c2bdd --- /dev/null +++ b/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} \ No newline at end of file diff --git a/body/syntex.tex b/body/syntex.tex new file mode 100644 index 0000000..cf5592d --- /dev/null +++ b/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{} 框起来的为必选参数, 如 \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} diff --git a/fig/collection.png b/fig/collection.png new file mode 100644 index 0000000..3a926bd Binary files /dev/null and b/fig/collection.png differ diff --git a/fig/scheme.png b/fig/scheme.png new file mode 100644 index 0000000..a6b8c2c Binary files /dev/null and b/fig/scheme.png differ diff --git a/tlmgr-intro-zh-cn.sty b/tlmgr-intro-zh-cn.sty new file mode 100644 index 0000000..8f754eb --- /dev/null +++ b/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 \ No newline at end of file diff --git a/tlmgr-intro-zh-cn.tex b/tlmgr-intro-zh-cn.tex new file mode 100644 index 0000000..00ff14d --- /dev/null +++ b/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://www.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}