LaTeX/LaTeX 文档的协作编写
 |
此页面需要关注。您可以帮助改进它，请求项目帮助，或查看当前进度。 |
注意：此 Wikibook 的部分内容（关于 subversion 的部分）基于 科学 LaTeX 文档的协作编写工具 文章，该文章由 Arne Henningsen 撰写，并发表在 2007 年第 3 期《PracTeX 期刊》上（http://www.tug.org/pracjourn/）。
文档的协作编写需要作者之间进行强大的同步。本 Wikibooks 描述了组织 LaTeX 文档协作准备的各种可能方法。
- 首先介绍了几种不基于版本控制系统的方法。
- 然后讨论了几个适合协作的 latex 样式文件。
- 接下来介绍了一种基于版本控制系统Subversion（https://subversion.org.cn/）的解决方案。本 Wikibooks 描述了如何将Subversion与其他几个软件工具和 LaTeX 软件包结合使用，以组织 LaTeX 文档的协作准备。
- 另一种方法是使用 mercurial https://www.mercurial-scm.org/ 和 bitbucket https://bitbucket.org/
- 您可以使用“安装”章节中列出的在线解决方案之一。它们中的大多数都具有协作功能。
- 另一种协作选择是 dropbox。它提供 2 GB 的免费存储空间和版本控制系统。工作方式类似于 SVN，但更加自动化，因此对于 LaTeX 初学者特别有用。但是，Dropbox 不是真正的版本控制系统，因此不允许您将文章回滚到以前的版本。基于 Web 的编辑器 LaTeX Base 支持同步到 Dropbox。
- 您可以使用构建在版本控制系统之上的在线协作工具，例如 Authorea 或 ShareLatex。Authorea 执行本文档中描述的大多数操作，但在后台执行（它构建在 Git 之上）。它允许作者通过具有数学符号、图形、d3.js 图表、IPython 笔记本、数据和表格的 GUI 输入 LaTeX 或 Markdown。所有内容都呈现为 HTML5。Authorea 还具有评论系统和基于文章的聊天功能，以方便协作和审查。
- 由于 LaTeX 系统使用纯文本，因此您可以使用同步协作编辑器，例如 Gobby。在 Gobby 中，您可以与任何人实时协作编写文档。强烈建议您使用 utf8 编码（尤其是在有多个操作系统上的用户进行协作时）和稳定的网络（通常是有线网络）。
- 实例（例如 此示例中的维基媒体上的 etherpad）的 EtherPad。要编译，请使用以下命令：
wget -O filename.tex "https://etherpad.wikimedia.org/ep/pad/export/xxxx/latest?format=txt" && (latex filename.tex)
其中“xxxx”应替换为便笺本编号（类似于“z7rSrfrYcH”）。
- 使用带有 LaTeX 和 Dropbox 的专用 Linux 服务器，可以结合使用 Google 文档和 一些脚本，以便从 Google 文档的更新中自动生成 Dropbox 上的 PDF 文件。
- 您可以使用 分布式版本控制系统，例如 Fossil、Mercurial 或 Git。对于寻求控制和高级功能（如分支和合并）的用户来说，这是最终解决方案。与基于 Web 的解决方案相比，学习曲线会更陡峭。
- Syncthing 是跨机器同步文件的另一种开源替代方案
工具 latexdiff 和 changebar 可以可视化生成的文档中两个 LaTeX 文件的差异。这使得更容易查看某些更改的影响或与不熟悉 LaTeX 的人讨论更改。Changebar 带有一个脚本 chbar.sh，该脚本在边距中插入一个条形，指示已更改的部分。Latexdiff 支持不同的可视化样式。默认情况下，丢弃的文本标记为红色，添加的文本标记为蓝色。它还支持类似于 Changebar 的模式，该模式在边距中添加一个条形。Latexdiff 带有一个脚本 latexrevise，可用于接受或拒绝更改。它还具有一个包装器脚本以支持版本控制系统，例如讨论的 Subversion。
有关如何在终端中使用 Latexdiff 的示例。
latexdiff old.tex new.tex > diff.tex # Files old.tex and new.tex are compared and the file visualizing the changes is written to diff.tex pdflatex diff.tex # Create a PDF showing the changes
如果您使用 mercurial，则语法如下：latexdiff-vc --hg test.tex -r revnumber
其中 revnumber 是相关更改集的（本地）revnumber。
重要建议
有时 latexdiff 会遇到问题（生成的 latex 代码无法编译）。如果存在与数学公式相关的重大更改，则可能会发生这种情况。为了解决此问题，latexdiff 提供了选项 --math-markup
--math-markup=3对数学公式的更改非常敏感。--math-markup=0忽略数学公式的更改。有关详细信息，请参阅文档。
程序 DiffPDF 可用于直观地比较两个现有的 PDF 文件。还有一个基于 DiffPDF 的命令行工具 comparepdf。
通常情况下，对于协作来说，建议采用模块化的方法，因为它最大程度地降低了编辑冲突的风险。详情请参阅 https://wikibooks.cn/w/index.php?title=LaTeX/Modular_Documents&stable=0，建议使用子文件，但这并不是唯一的解决方案。
todonotes.sty 允许您插入待办事项，可以是边注或内联，并在文档开头添加一个（支持超链接的）待办事项列表。与 fixme.sty 相比，这个包的特别之处在于边注待办事项会用一条线指向相关的文本。此功能在 Libreoffice、MS Office 等中很常见，详情请参阅手册 https://ctan.org/pkg/todonotes?lang=en。
以下是一个示例
\documentclass{article}
\usepackage[colorinlistoftodos, textwidth=3cm, shadow]{todonotes}
\newcounter{ubcomment}
\newcommand{\ubcomment}[2][]{%
\refstepcounter{ubcomment}%
{%
\todo[linecolor=black,backgroundcolor={green!40!},size=\footnotesize]{%
\textbf{Fixme: UB [\uppercase{#1}\theubcomment]:}~#2}%
}}
\newcommand{\ubcommentinline}[2][]{%
\refstepcounter{ubcomment}%
{%
\todo[linecolor=black,inline,backgroundcolor={green!40!},size=\footnotesize]{%
\textbf{Fixme: UB [\uppercase{#1}\theubcomment]:}~#2}%
}}
\newcommand{\ubcommentmultiline}[2]{%
\refstepcounter{ubcomment}%
{%
\todo[linecolor=black,inline,caption={\textbf{{Fixme: UB}
[\theubcomment] #1}} ,backgroundcolor={green!40!},size=\footnotesize]{%
\textbf{Fixme: UB [\theubcomment]:}~#2}%
}}
% add support for todo in equations
\usepackage{marginnote}
\makeatletter
\renewcommand{\@todonotes@drawMarginNoteWithLine}{%
\begin{tikzpicture}[remember picture, overlay, baseline=-0.75ex]%
\node [coordinate] (inText) {};%
\end{tikzpicture}%
\marginnote[{% Draw note in left margin
\@todonotes@drawMarginNote%
\@todonotes@drawLineToLeftMargin%
}]{% Draw note in right margin
\@todonotes@drawMarginNote%
\@todonotes@drawLineToRightMargin%
}%
}
\makeatother
\begin{document}
\listoftodos
This is one example \ubcomment{Comment 1}
Now more text and an inline comment: \ubcommentinline{This is an
inline comment}.
Now even more text and a comment with an enumerate list.
\ubcommentmultiline{Third comment}{
this is not true because
\begin{enumerate}
\item Reason 1
\item Reason 2
\end{enumerate}
}
Finally a comment inside a math environment.
\begin{equation}
\label{eq:todo-example:1}
\int f dx =0 \ubcomment{are you sure this integral is zero???}
\end{equation}
\end{document}
请注意：您需要使用 pdflatex（xelatex 也适用）并运行多次，即三次或四次。
这个包 https://ctan.org/pkg/rcsinfo?lang=en（以及 rcs-multi https://ctan.org/pkg/rcs-multi）会以类似的方式自动插入当前版本、日期和文件的拥有者，前提是该文件受与RCS语法兼容的版本控制系统的控制，例如 CVS、Subversion 和 Mercurial。（请参阅下方如何设置 Mercurial）。以下是一个示例
\documentclass[12pt]{article}
\usepackage[scrpage2]{rcsinfo}
\makeatletter \def\@rcsInfoFancyInfo{{\footnotesize%
\emph{ \fcolorbox{black}{green}{Rev: \rcsInfoRevision,}
\fcolorbox{black}{yellow}{\rcsInfoOwner,} \rcsInfoLongDate,
\rcsInfoTime}}} \makeatother
\rcsInfo $Id: main.tex,v [Hg:291] 2018/08/08 16:36:51 oub Exp oub $
\begin{document}
This is a test.
\end{document}
无论是否协作，版本控制系统对于单作者文档也很有用，因为它允许跟踪更改并根据需要恢复旧版本。最古老且仍在使用的版本控制系统是 RCS，但它面向单个文件，并且不基于服务器模型。CVS 基于 RCS，但适用于多个文件，也包含服务器模型。在某种程度上，它被 Subversion 取代（见下文）。另一种方法是由所谓的分布式版本控制系统采用的，其中最流行的是 Git 和 Mercurial（见下文）。
系统应该允许多个用户对系统进行读写访问，类似于“服务器”
重点不是用新版本覆盖文件或文件，而是系统应该以某种形式保存不同的版本。原因是
- 可以通过运行适当的 diff 程序来比较更改，
for example latexdiff, on different version of the file.
- 允许在必要时恢复旧版本。
顺序协作是指一个用户工作，而其他用户什么也不做，获取更改，然后下一个用户开始。
让我们考虑一个非顺序协作。（为了说明问题，示例使用了一个文件，原则上，不同文件在目录中也会出现相同的问题，但不太直观。）
- 用户 1 想要修改文件 1 中的第 1 节，需要 2 周时间
this modification the results is file1-modified-by-user1
- 在此期间，用户 2 修改了文件 1 中的第 2 节，导致
file1-modified-by-user2
- 用户 3 修改了文件 1 中的第 3 节，导致文件 1-modified-by-user3
版本系统必须能够毫无问题地“合并”这三个更改。
根据定义，编辑冲突是指发生在文件同一行的编辑。系统应检测到这种情况，并提供建议和解决方法。
协作编写文档需要作者之间进行大量的协调。这种协调可以通过多种不同的方式组织，最佳方式取决于具体情况。
作者之间交换文档的方法有很多。一种可能性是通过交换电子邮件来编写文档。这种方法的优点是普通用户通常不必安装和学习任何额外的软件，因为几乎所有作者都有电子邮件帐户。此外，修改文档的作者可以轻松地附加文档并通过电子邮件解释更改。不幸的是，当两个或多个作者同时处理同一文档时，就会出现问题。那么，作者如何同步这些文件？除了这个困难之外，如果涉及多个文件，基于电子邮件的方法很容易变得繁琐。另一种方法是使用分布式或基于服务器的版本控制系统。在详细介绍之前，下一小节将概述此方法的基本要求。
第二种可能性是在大多数部门都可用的公共文件服务器上提供文档。可以通过锁定当前正在编辑的文件来消除覆盖彼此修改的风险。但是，通常只能从部门内部访问文件服务器。因此，不在大楼内的作者无法使用此方法更新/提交他们的更改。在这种情况下，他们将不得不使用其他方法来解决此问题。那么，作者如何访问这些文件？
第三种可能性是使用版本控制系统。可以在 维基百科上找到版本控制系统的完整列表。版本控制系统会跟踪项目中所有文件的更改。如果许多作者同时修改文档，版本控制系统会尝试自动合并所有修改。但是，如果多个作者修改了同一行，则无法自动合并修改，用户必须通过手动决定保留哪些更改来解决冲突。作者还可以注释他们的修改，以便合作者能够轻松理解此文件的工作流程。由于版本控制系统通常通过互联网通信（例如，通过 TCP/IP 连接），因此可以从具有互联网连接的不同计算机上使用它们。限制性防火墙策略可能会阻止版本控制系统连接到互联网。在这种情况下，需要请求网络管理员打开相应的端口。互联网仅用于同步文件。因此，不需要永久的互联网连接。版本控制系统的唯一缺点可能是需要安装和配置。
此外，即使单个用户正在处理项目，版本控制系统也很有用。首先，用户可以跟踪（并可能撤销）所有先前的修改。其次，这是一种在其他计算机（例如，版本控制服务器）上备份文件的便捷方法。第三，这允许用户轻松地在不同的计算机（例如，办公室、笔记本电脑、家庭）之间切换。
作为流行的版本控制系统 CVS 的继任者，Subversion (SVN) 应运而生。SVN 采用客户端-服务器模型，其中中央服务器托管项目存储库，用户可以本地复制和修改该存储库。存储库的功能类似于图书馆，允许用户检出当前项目，进行更改，然后检入。服务器会记录用户检入的所有更改（通常带有总结用户所做更改的消息），以便其他用户可以轻松地将这些更改应用到自己的本地文件。
每个用户都有一个远程存储库的本地工作副本。例如，用户可以将存储库中的更改更新到其工作副本，将自己工作副本中的更改提交到存储库，或者（重新）查看工作副本和存储库之间的差异。
要设置 SVN 版本控制系统，必须在具有永久互联网访问权限的（单个）计算机上安装 SVN 服务器软件。（如果这台计算机没有静态 IP 地址，可以使用像 DynDNS 这样的服务来通过静态主机名访问服务器。）它可以在许多 Unix、现代 MS Windows 和 Mac OS X 平台上运行。
用户不必安装 SVN 服务器软件，但需要安装 SVN "客户端"软件。这是访问服务器上存储库的唯一方式。除了基本的 SVN 命令行客户端之外，还有几个图形用户界面工具 (GUI) 和插件可用于访问 SVN 服务器（参见 http://subversion.tigris.org/links.html）。此外，互联网上还有很多关于 SVN 的优秀手册免费提供（例如 https://svnbook.subversion.org.cn）。
在我们部门，我们在 GNU-Linux 系统上运行 SVN 服务器，因为大多数 Linux 发行版都包含它。从这个意义上说，安装、配置和维护 SVN 是一项非常简单的任务。
大多数 MS Windows 用户通过 TortoiseSVN 客户端访问 SVN 服务器，因为它为普通用户提供了最常用的界面。Linux 用户通常使用命令行中的 SVN 实用程序，或者使用 eSvn（一个 GUI 前端）以及 KDiff3 来显示复杂的差异。
在我们的Subversion服务器上，我们有一个用于通用texmf树的存储库。其结构符合TeX 目录结构指南（TDS，http://www.tug.org/tds/tds.html，参见图 1）。此存储库提供 LaTeX 类、LaTeX 样式和 BibTeX 样式，这些样式在用户的 LaTeX 发行版中不可用，例如，因为它们是在我们部门内部购买或开发的。所有用户都有此存储库的工作副本，并且已配置 LaTeX 以将其用作其个人texmf树。例如，teTeX (http://www.tug.org/tetex/) 用户可以编辑其 TeX 配置文件（例如/etc/texmf/web2c/texmf.cnf) 并设置变量TEXMFHOME到通用工作副本的路径texmf树（例如通过TEXMFHOME = $HOME/texmf)；MiKTeX (http://www.miktex.org/) 用户可以在 MiKTeX 选项的“根”选项卡中添加通用工作副本的路径texmf树。
如果添加了新的类或样式文件（但如果修改了这些文件则不会），则用户必须在可以使用这些类和样式之前更新其“文件名数据库”（FNDB）。例如，teTeX 用户必须执行texhash；MiKTeX 用户必须单击 MiKTeX 选项的“常规”选项卡中的“刷新 FNDB”按钮。
此外，存储库包含说明我们部门特定 LaTeX 软件解决方案的手册（例如本文档）。
Subversion服务器为我们部门的每个项目托管一个单独的存储库。尽管分支、合并和标记对于编写文本文档不如编写软件源代码重要，但我们的存储库布局遵循“Subversion 手册”的建议（https://svnbook.subversion.org.cn）。从这个意义上说，每个存储库都有三个目录/trunk, /branches，以及/tags.
最重要的目录是/trunk。如果单个文本文档属于该项目，则此文本文档的所有文件和子目录都在/trunk中。如果项目产生两个或多个不同的文本文档，/trunk包含每个文本文档的子目录。文本文档的略微不同的版本（分支）（例如，用于在会议上展示）可以在/trunk的附加子目录中或/branches的新子目录中准备。当文本文档提交到期刊或会议时，我们在目录/tags中创建一个标记，以便以后可以轻松识别文档的提交版本。此功能已被证明非常有用。创建分支和标记时，务必始终为此类操作使用Subversion客户端（而不是本地文件系统的工具），因为这可以节省服务器上的磁盘空间，并保留有关这些文档相同历史记录的信息。
通常会出现以下问题：哪些文件应该放在版本控制之下。通常，用户直接修改且编译文档所必需的所有文件都应包含在版本控制系统中。通常，这些是 LaTeX 源代码（*.tex）文件（主文档和一些子文档）以及插入文档中的所有图片（*.eps, *.jpg, *.png，以及*.pdf文件）。所有 LaTeX 类（*.cls）、LaTeX 样式（*.sty）、BibTeX 数据库（*.bib）和 BibTeX 样式（*.bst）通常应托管在通用存储库中texmf树，但如果某些（外部）合著者无法访问通用texmf树，则可以将其包含在相应的存储库中。另一方面，在编译过程中自动创建或修改的所有文件（例如*.aut, *.aux, *.bbl, *.bix, *.blg, *.dvi, *.glo, *.gls, *.idx, *.ilg, *.ind, *.ist, *.lof, *.log, *.lot, *.nav, *.nlo, *.out, *.pdf, *.ps, *.snm，以及*.toc文件）或由（LaTeX 或 BibTeX）编辑器（例如*.bak, *.bib~, *.kilepr, *.prj, *.sav, *.tcp, *.tmp, *.tps，以及*.tex~文件）通常不应该放在版本控制之下，因为这些文件对于编译不是必需的，并且通常不包含其他信息。此外，这些文件会定期修改，因此冲突的可能性非常大。
版本控制系统的一个很棒的功能是，所有作者都可以通过查看文件任意版本之间的差异来轻松跟踪项目的流程。作者主要关注源代码的“有效”修改，这些修改会更改编译后的文档，而不是对编译后的文档没有影响的“无效”修改（例如，换行符的位置）。用于比较文本文档的软件工具（“diff 工具”）通常无法区分“有效”和“无效”修改；它们会突出显示这两种类型的修改。这大大增加了查找和审查“有效”修改的工作量。因此，应避免“无效”修改。
从这个意义上说，不无缘无故地更改换行符的位置非常重要。因此，用户 LaTeX 编辑器的自动换行应关闭，并且应手动添加换行符。否则，如果在段落开头添加或删除一个单词，则该段落的所有换行符都可能会更改，因此大多数 diff 工具会将整个段落标记为已修改，因为它们逐行比较文件。diff 工具wdiff (http://www.gnu.org/software/wdiff/) 和dwdiff (http://os.ghalkes.nl/dwdiff.html) 不受换行符位置的影响，因为它们逐词比较文档。但是，它们的输出不太清晰，因此修改更难以跟踪。此外，这些工具不能直接与Subversion命令行开关--diff-cmd一起使用，而必须使用一个小的包装脚本 (http://textsnippets.com/posts/show/1033)。
一个合理的约定是在每个句子后添加换行符，并在新行中开始每个新句子。请注意，这除了版本控制之外还有另一个优势：如果您想在 LaTeX 代码中查找您在编译的（DVI、PS 或 PDF）文件中或打印输出上看到的句子，您可以轻松识别该句子的前几个单词，并在编辑器窗口的左边界上筛选这些单词。
此外，我们将长句子拆分为几行，以便每行最多约 80 个字符，因为在长行中搜索（小）差异相当不方便。（注意：例如，LaTeX 编辑器Kile (http://kile.sourceforge.net/) 在配置为添加标记第 80 列的垂直线时可以帮助用户完成此任务。）我们发现引入句子逻辑断点处的额外换行符非常有用，例如，在关系从句之前或句子的新部分开始之前。符合这些指南格式的示例 LaTeX 代码是 Arne Henningsen 编写的文章用于科学 LaTeX 文档协作写作的工具的源代码，该文章发表在The PracTeX Journal 2007 年第 3 期（http://www.tug.org/pracjourn/2007-3/henningsen/）中（包括源代码）。
如果作者使用不同的操作系统，他们的 LaTeX 编辑器可能会以不同的换行符（行尾字符）(w:Newline）保存文件。为了避免这种“无效”修改，所有用户可以商定一个特定的换行符，并配置他们的编辑器使用此换行符。另一种方法是添加 Subversion 属性“svn:eol-style”并将其设置为“native”。在这种情况下，Subversion 会自动将该文件的所有换行符转换为作者操作系统本机的换行符(https://svnbook.subversion.org.cn/en/1.4/svn.advanced.props.file-portability.html#svn.advanced.props.special.eol-style)。
减少“无效”修改的数量还有另一个重要原因：如果多个作者同时处理同一个文件，那么同一行被两个或多个作者同时修改的概率会随着修改行数的增加而增加。因此，“无效”修改会不必要地增加冲突的风险（参见文档交换部分）。
此外，版本控制系统允许使用一种非常有效的质量保证措施：所有作者都应该在将自己的修改提交到代码库之前对其进行严格审查（参见图 2）。用户工作副本和代码库之间的差异可以通过单个Subversion命令或图形Subversion客户端中的一两下点击轻松检查。此外，作者应在将修改提交到代码库之前验证其代码是否可以完美编译。否则，当其他作者想要编译文档时，他们将不得不为这些错误买单。然而，这条指令不仅适用于版本控制系统，也适用于所有其他在作者之间交换文档的方式。
Subversion 具有一个名为“关键字替换”的功能，该功能将有关文件的动态版本信息（例如修订号或最后作者）包含到文件本身的内容中（例如，参见https://svnbook.subversion.org.cn，第 3 章）。有时，不仅将这些信息作为 LaTeX 源代码中的注释包含在内，而且还将其包含在（编译后的）DVI、PS 或 PDF 文档中也很有用。这可以通过 LaTeX 包svn(http://www.ctan.org/tex-archive/macros/latex/contrib/svn/)、svninfo(http://www.ctan.org/tex-archive/macros/latex/contrib/svninfo/)或（优选）svn-multi(http://www.ctan.org/tex-archive/macros/latex/contrib/svn-multi/)来实现。
使用版本控制系统协作编写 LaTeX 文档的最重要指令总结在下框中。
使用 LaTeX 与版本控制系统的指令
- 避免“无效”修改。
- 没有充分理由不要更改换行符。
- 关闭 LaTeX 编辑器的自动换行功能。
- 在新行中开始每个新句子。
- 将长句子分成几行，以便每行最多约 80 个字符。
- 仅将用户直接修改的文件置于版本控制之下。
- 在将修改提交到代码库之前，验证代码是否可以完美编译。
- 在将修改提交到代码库之前，使用Subversion的 diff 功能严格审查修改。
- 在将修改提交到代码库时添加有意义且描述性的注释。
- 使用Subversion客户端复制、移动或重命名受版本控制的文件和文件夹。
如果用户愿意放弃 SVN 的内置diff实用程序并使用其工作站上的本地diff工具，他们可以使用更适合文本文档的工具。随 SVN 附带的diff工具的设计考虑了源代码。因此，它被构建为对短行文件更有用。其他工具，例如Compare It!允许方便地比较每个行可以跨越数百个字符的文本文件（例如，当每行表示一个段落时）。当使用允许方便查看长行文件的diff工具时，用户可以编写 TeX 文件而无需严格的换行策略。
如以下链接所述：https://en.wikipedia.org/wiki/Distributed_version_control：在软件开发中，分布式版本控制（也称为分布式修订控制）是一种版本控制形式，其中完整的代码库（包括其完整历史记录）会镜像到每个开发人员的计算机上。这允许自动管理分支和合并，提高大多数操作的速度（除了推送和拉取），提高离线工作的能力，并且不依赖于单个位置进行备份。
软件开发作者 Joel Spolsky 将 DVCS 描述为“可能是过去十年软件开发技术中最大的进步”。
目前最流行的 DVCS 是
- Git https://git.js.cn/ 和
- Mercurial https://www.mercurial-scm.org/
尽管 Git 更流行，并且可能更适合非常大型的软件项目，但 Mercurial 有一些特性使其特别适合基于 LaTeX 的科学协作。
- 除了变更集哈希之外，它还有一个本地修订号，这使得处理不同的变更集更容易。
- 它具有关键字扩展功能，因此适合使用 rcs-multi.sty 和其他在文档页脚或标题中添加版本号的 LaTeX 样式。
- 除了书签之外，它还有命名分支，如果需要多个分支，则命名分支更直观。
- 它在所有已知操作系统上都能完美运行。
- GUI https://www.mercurial-scm.org/wiki/TortoiseHg 提供了一个直观的界面。
以下说明介绍了如何设置 Mercurial。Git 的设置非常相似，几乎相同，例如，参见 Git/Mercurial Rosetta Stone：https://github.com/sympy/sympy/wiki/Git-hg-rosetta-stone
有关在不同操作系统中安装 Mercurial 的信息，请参见：https://www.mercurial-scm.org/downloads
Mercurial 编写并附带了各种所谓的扩展，这些扩展必须在全局 .hgrc 配置文件中单独启用。
以下是一个示例
# example config (see "hg help config" for more info)
[ui]
username = Joe Doe <[email protected]>
[extensions]
churn =
# Read the documentation of how to set up the notify extension, this
# extension is not needed if you use the bitbucket notify system
# notify =
strip =
share =
progress =
eol =
hgk =
hgext.bookmarks =
interhg =
rebase =
shelve =
purge =
record =
color =
keyword =
hgext.fetch=
histedit =
# Advanced extensions
# evolve =
# hggit =
# Minimal setting for keyword expansion.
[keyword]
**.tex =
[keywordmaps]
Author = {author|user}
Date = {date|utcdate}
Header = {root}/{file},v {node|short} {date|utcdate} {author|user}
Id = {file|basename},v {rev} {date|utcdate} {author|user} Exp {author|user}
# Other options
# Id = {file|basename},v {rev}{latesttag}.{latesttagdistance} {date|utcdate} {author|user} Exp {author|user}
# the problem with this is that adding a tag increases the rev number so that
# in the latex document the string is always v4.2 or 5.2 but never v4.1.
# Id = {file|basename},v {latesttag}.{latesttagdistance}[Hg:{rev}] {date|utcdate} {author|user} Exp {author|user}
# simplified version
# Id = {file|basename},v |Brch:{branches}|{latesttag}[Hg:{rev}] {date|utcdate} {author|user} Exp {author|user}
RCSFile = {file|basename},v
RCSfile = {file|basename},v
Revision = {node|short}
Source = {root}/{file},v
[hostfingerprints]
bitbucket.org.fingerprints=sha256:ae:ca:bf:83:41:14:55:8d:ea:70:ae:06:7d:ad:c0:44:77:6f:81:1a:c9:1e:d3:ab:f5:38:98:2b:07:4b:d4:70
[color]
custom.rev = red
custom.decorate = yellow
custom.date = green
custom.author = blue bold
[eol]
native = LF
如前所述，建议使用模块化方法与 LaTeX 协作，使用 subfile 包。典型的 LaTeX 模板目录可能如下所示
-rw-r--r-- 1 oub oub 254K Aug 7 21:15 bibfile.bib -rw-r--r-- 1 oub oub 637 Aug 14 09:21 main.tex -rw-rw-r-- 1 oub oub 576 Aug 14 09:21 sec1-main-result.tex -rw-rw-r-- 1 oub oub 576 Aug 14 09:21 sec2-proof.tex
因此，在该目录中，必须执行以下操作（使用 Linux/macOS，MS Windows 类似）
hg init
hg addremove
hg commit -m "第一次提交"
可以选择添加一个 .hgignore 文件，对于 LaTeX，它可能如下所示
syntax: glob
*.aux
*.toc
*.mw
*.backup
*.brf
*.tdo
*.bbl
*.blg
*.bib
*.el
*.log
*.dvi
*.nav
*.pdf
*.glo
*.idx
*.ilg
*.ind
*.nlo
*.nls
*.out
*.synctex.gz
hg addremove
hg commit -m "添加 .hgignore"
因此，目录将如下所示
drwxrwxr-x 11 oub oub 4.0K Aug 14 09:15 .. -rw-r--r-- 1 oub oub 254K Aug 7 21:15 bibfile.bib drwxr-xr-x 4 oub oub 4.0K Aug 14 09:34 .hg -rw-r--r-- 1 oub oub 215 Aug 14 09:31 .hgignore -rw-r--r-- 1 oub oub 630 Aug 14 09:34 main.tex -rw-rw-r-- 1 oub oub 568 Aug 14 09:34 sec1-main-result.tex -rw-rw-r-- 1 oub oub 562 Aug 14 09:34 sec2-proof.tex
现在，您可以设置一个空的 Bitbucket 代码库并邀请协作者。
我建议使用托管的 Mercurial 代码库，例如 Bitbucket。对于学术用户，Bitbucket 提供了更慷慨的使用方式（例如，对协作者数量没有限制）。因此，建议的方法是所有协作者都开通 Bitbucket 帐户。
- 然后，其中一位作者将担任维护者，创建代码库并将模板作为第一个版本推送。Bitbucket 网站提供了很好的解释，但请参见下面的详细信息。
- 他与其他协作者共享代码库。
- 建议所有协作者都设置 Bitbucket 通知系统。
- 协作者克隆代码库：例如 hg clone https://bitbucket.org/user/project1。
- 协作者编辑文件，提交，例如
hg commit -m "添加引言" - 然后他们推送
hg push - 其他协作者会收到推送通知并拉取：
hg pull -u
但是，截至 2020 年 8 月 1 日，Mercurial 已停止通过 Mercurial 进行访问。有两个替代方案
- 1 保留 Mercurial 但使用 hg-git 插件。即使对于命名分支，这也是可能的，但需要一些调整。
- 切换到 Helix，此服务提供的资源略少，但仍提供免费代码库（每个帐户 1 GB 免费空间 + 5 个协作者）。(https://info.perforce.com/try-perforce-helix-teamhub-free)
此内容复制自 Bitbucket 网站。
- 步骤 1：切换到您的代码库目录
cd /path/to/your/repo
- 步骤 2：将您现有的仓库连接到 Bitbucket
hg push https://[email protected]/user/test
- 步骤 3：使用其新 URL 更新仓库 .hgrc 文件的默认字段
[paths] default = https://[email protected]/user/test
简而言之，大多数协作者（维护者除外）需要学习的命令是：
- hg clone https://bitbucket.org/user/project1
- hg commit -m "提交信息"
- hg push
- hg pull -u
建议在 push 之前**始终**执行 pull 操作。
然后可能会发生两种情况。
- 一种是没有任何变化，上游没有更改。
在这种情况下
hg log -G
看起来像
@ changeset: 1:cd6ae8660e6f
| tag: tip
| user: Joe Doe <[email protected]>
| date: Thu Aug 09 22:17:47 2018 +0200
| summary: My second commit
|
o changeset: 0:cb0b44f99bd2
- 上游存在您已拉取的更改，在这种情况下，您现在有一个新的 head，您应该将其合并。
所以在第二种情况下
hg log -G
看起来像
o changeset: 2:05548327a272
| tag: tip
| parent: 0:cb0b44f99bd2
| user: John Smith <[email protected]>
| date: Thu Aug 09 22:17:22 2018 +0200
| summary: My second commit
|
| @ changeset: 1:cd6ae8660e6f
|/ user: Joe Doe <[email protected]>
| date: Thu Aug 09 22:17:47 2018 +0200
| summary: My second commit
|
o changeset: 0:cb0b44f99bd2
所以您应该合并
hg merge -r 2 并获得
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
(branch merge, don't forget to commit)
所以 hg log -G
给出
@ changeset: 3:df2f1f46a80c
|\ tag: tip
| | parent: 1:cd6ae8660e6f
| | parent: 2:05548327a272
| | user: Joe Doe <[email protected]>
| | date: Thu Aug 09 22:20:44 2018 +0200
| | summary: Merged successfully
| |
| o changeset: 2:05548327a272
| | parent: 0:cb0b44f99bd2
| | user: John Smith <[email protected]>
| | date: Thu Aug 09 22:17:22 2018 +0200
| | summary: My second commit
| |
o | changeset: 1:cd6ae8660e6f
|/ user: Joe Doe <[email protected]>
| date: Thu Aug 09 22:17:47 2018 +0200
| summary: My second commit
|
o changeset: 0:cb0b44f99bd2
冲突更改集的合并应留给维护者处理。
有几种可用的选项
- Overleaf（以及现在是 Overleaf 一部分的 ShareLaTeX）是一个基于 Web 的实时协作编辑器
- BlueLatex 是一个用 Scala 编写的基于 Web 的实时协作编辑器
- Cocalc（以前称为 SageMathCloud）有一个协作 LaTeX 编辑器
- Authorea 是一个基于 Web 的实时协作编辑器
- Papeera 是一个基于 Web 的实时协作编辑器
这种方法的优点是不需要额外的软件，缺点是不能轻松使用自己喜欢的 LaTeX 编辑器。因此，几乎所有这些服务都允许通过 Git 访问（为此需要安装 Git 或 Mercurial + hg-git 插件）。
几年前，这些服务几乎都是免费的；现在，只有非常基本的功能是免费的，下表对此进行了更详细的说明。
| 名称 | 协作者 | 文档 | 通过 Git（或 Mercurial）访问 |
| Authorea | 无限制 | 仅限 3 个文档免费 | 是 |
| Overleaf | 仅限一位作者 | 无限制 | 是 |
| Papeeria | 无限制 | 无限制 | 仅限公共仓库 |
| 在免费版本中 |
撰写科学文章、报告和书籍需要引用所有相关来源。BibTeX 是一个用于引用参考文献和创建参考文献的优秀工具（Markey 2005，Fenn 2006）。许多不同的 BibTeX 样式可以在 CTAN (http://www.ctan.org) 和 LaTeX 参考文献样式数据库 (http://jo.irisson.free.fr/bstdatabase/) 上找到。如果找不到合适的 BibTeX 样式，可以使用 custombib/makebst (http://www.ctan.org/tex-archive/macros/latex/contrib/custom-bib/) 方便地组装大多数所需的样式。此外，BibTeX 样式文件可以手动创建或修改；但是此操作需要了解 BibTeX 样式文件中使用的（未命名）后缀栈语言（Patashnik 1988）。
在我们系，我们有一个通用的 BibTeX 格式的参考文献数据库（.bib 文件）。它位于我们的公共texmf树中（参见“在 Subversion 中托管 LaTeX 文件”部分）的子目录/bibtex/bib/（参见图 1）。因此，所有用户只需使用文件名（无需完整路径）即可指定此参考文献——无论用户公共texmf树的工作副本位于何处。
所有用户都使用图形化 BibTeX 编辑器 JabRef (http://www.jabref.org) 编辑我们的参考文献数据库。由于 JabRef 是用 Java 编写的，因此它可以在所有主要操作系统上运行。由于不同版本的 JabRef 通常以略微不同的方式保存文件（例如，在不同位置引入换行符），因此所有用户都应使用相同（例如，最新稳定）版本的 JabRef。否则，不同版本的.bib文件之间将存在许多差异，这些差异仅仅源于使用不同版本的 JabRef。因此，很难找到比较文档之间的真实差异。此外，冲突的可能性会大大提高（参见“Subversion 真正发挥了作用”部分）。由于 JabRef 使用作者操作系统中的本地换行符保存 BibTeX 数据库，因此建议添加 Subversion 属性“svn:eol-style”并将其设置为“native”（参见“Subversion 真正发挥了作用”部分）。
JabRef 非常灵活，可以在许多细节方面进行配置。我们对 JabRef 的默认配置进行以下更改以简化我们的工作。首先，我们指定 BibTeX 键的默认模式，以便 JabRef 可以自动以我们所需的格式生成键。这可以通过选择选项→首选项→键模式并在字段中修改所需的模式默认模式。例如，我们使用[auth:lower][shortyear]以获取第一个作者姓氏的小写形式和出版年份的后两位数字（参见图 3）。
其次，我们添加 BibTeX 字段位置以获取有关出版物以硬拷贝形式（例如，书籍或文章副本）提供的地址信息。此字段可以包含拥有硬拷贝的用户姓名及其位置或图书馆的名称和书架号。可以通过选择 JabRef 中的选项→设置通用字段并在以位置（使用分号（;）作为分隔符）通用（参见图 4）。
第三，我们将所有出版物的 PDF 文件放在文件服务器中的特定子目录中，在该目录中我们使用 BibTeX 键作为文件名。我们通过选择 JabRef 中的选项→首选项→外部程序并在字段中添加此子目录的路径来告知 JabRef 此子目录主要 PDF 目录（参见图 5）。如果出版物的 PDF 文件可用，则用户可以按 JabRef 的自动按钮（位于 JabRef 的Pdf字段左侧）来自动添加 PDF 文件的文件名。现在，所有可以访问文件服务器的用户只需点击 JabRef 的 PDF 图标即可打开出版物的 PDF 文件。
如果我们将项目的 LaTeX 源代码发送到期刊、出版商或其他无法访问我们的公共texmf树的人员，我们不会包含整个参考文献数据库，而是使用 Perl 脚本 aux2bib (http://www.ctan.org/tex-archive/biblio/bibtex/utils/bibtools/aux2bib) 提取相关的条目。
本维基教科书描述了一种有效组织 LaTeX 文档协作准备的可能方法。提出的解决方案基于 Subversion 版本控制系统以及其他一些软件工具和 LaTeX 包。但是，仍然有一些问题可以改进。
首先，我们计划所有用户都安装相同的 LaTeX 发行版。由于 TeX Live 发行版 (http://www.tug.org/texlive/) 同时适用于 Unix 和 MS Windows 操作系统，因此我们将来可能会建议用户切换到此 LaTeX 发行版。（目前，我们的用户有不同的 LaTeX 发行版，它们提供不同的 LaTeX 包选择和某些包的不同版本。我们通过在我们的公共texmf树上提供一些包来解决此问题。）
其次，我们考虑简化通用参考文献数据库的解决方案。目前，它基于版本控制系统 Subversion、图形化 BibTeX 编辑器 JabRef 和用于数据库中出版物 PDF 文件的文件服务器。对于不经常使用这些工具的用户和不熟悉这些工具的用户来说，使用三种不同的工具来完成一项任务是相当具有挑战性的。此外，文件服务器只能由本地用户访问。因此，我们考虑实现一个集成的服务器解决方案，如 WIKINDX (http://wikindx.sourceforge.net/)、Aigaion (http://www.aigaion.nl/) 或 refBASE (http://refbase.sourceforge.net/)。使用此解决方案只需要一台有互联网连接的计算机和一个 Web 浏览器，这使得不经常使用数据库的用户更容易使用。此外，存储的 PDF 文件不仅可以在系内访问，而且可以在全球范围内访问。（根据存储的 PDF 文件的版权，对服务器的访问——或者至少对 PDF 文件的访问——必须限制在系内成员。）我们系内甚至非 LaTeX 用户也可能受益于基于服务器的解决方案，因为它应该更容易在（其他）文字处理软件包中使用此参考文献数据库，因为这些服务器不仅以 BibTeX 格式提供数据，还以其他格式提供数据。
欢迎所有读者通过添加更多提示或想法或提供更多 LaTeX 文档协作写作问题的解决方案来为本维基教科书做出贡献。
Arne Henningsen 感谢 Francisco Reinaldo 和 Géraldine Henningsen 的评论和建议，这些建议帮助他改进和阐明了本文，感谢 Karsten Heymann 在 LaTeX、BibTeX 和 Subversion 方面的许多提示和建议，以及 Christian Henning 及其同事支持他在他们部门建立 LaTeX 和 Subversion 的意愿。
- Fenn，Jürgen (2006)：使用 BibTeX 管理引用和参考文献。PracTEX 杂志，第 4 期。 http://www.tug.org/pracjourn/2006-4/fenn/。
- Markey，Nicolas (2005)：驯服 BeaST。BibTeX 的 B 到 X。 http://www.ctan.org/tex-archive/info/bibtex/tamethebeast/ttb_en.pdf。版本 1.3。
- Oren Patashnik。BibTeX 样式设计。 http://www.ctan.org/tex-archive/info/biblio/bibtex/contrib/doc/btxhak.pdf。