13. ⁎Collaborating on Documents
There are a number of issues that can occur when multiple authors collaborate on the same document. For example, suppose Fred and Mabel are co-authors of a document, here are some problems they may encounter:
- If both Fred and Mabel edit their own copies of the source
code, how do they merge their edits? If Fred sends Mabel his updated
source file, it could overwrite her changes. Similarly if Mabel
sends Fred her updated source file, it could overwrite his changes.
- Fred decides to use package foo, which is available on
his MiKTeX distribution, but Mabel doesn't have foo on her
TeX Live distribution.
- Both Fred and Mabel want to use package baz but Mabel
has a newer version and is using commands that aren't available in
the older version that Fred has installed.
- Fred and Mabel are working on a sensitive document. If they
simply email each other the source code it could be intercepted
or if they transfer it on a portable device, such as a memory stick, it
could get stolen.
- Fred is the principle author and is in charge of writing the
first draft. Once he has finished, he sends the document to Mabel
who makes minor corrections, but Fred needs to know what
modifications she has made.
- Prof Important Person has decided he's also going to
contribute to the document but insists on using his favourite word
processor.
- If Fred or Mabel make an inappropriate change to the document, they may want to roll back to an earlier version of the document to undo the modifications.
Here are some possible solutions to the above problems:
- The easiest case is when Fred and Mabel are working on
separate sections or chapters. They can then split up the source
code and use
\input(for sections) or\include(for complete chapters). Then Fred can just edit the files for his sections and Mabel can just edit the files for her sections. This way they won't be editing the same file at the same time.In the other case, where Fred and Mabel are both working on the same sections, then the most convenient solutions are a version control system (§13.2 Version Control) or using an online LaTeX editor (§13.3 Online LaTeX Editors).
- Fred and Mabel agree to only use packages that are available
on both MiKTeX and TeX Live, or Mabel manually installs the
missing package, or they use an online LaTeX editor.
- Fred and Mabel both update their TeX distributions before
they start working on the document or they use an online LaTeX editor.
- In this case, it depends on the level of security needed.
Fred and Mabel may simply be able to use a password-protected version control
system. Alternatively, they may need to store the document source code on a
portable device that's locked in a safe when the document isn't
being edited, and the authors will have to take it in turns to
access the device in a non-networked secure environment.
- Use LaTeX commands to markup the changes
(§13.1 Change Markup) or use version control.
- A non-LaTeX co-author can cause major headaches for
a predominantly LaTeX team of authors. In some cases, gentle
persuasion may help. If arguments about the quality of typesetting,
the logic of document markup, the convenience of cross-referencing
and automatically generated table of contents and similar lists
don't have an effect, it might help to point out the security issues
associated with Word files, such as the automatic hidden inclusion of
personal data and revision information [28].
If persuasion doesn't help, how much of a contribution will they be making to the document? If it's just a matter of a few minor corrections, then it might be possible for them just to mark their changes and for you to then incorporate those changes into the LaTeX source code. The best way of creating a Word document from the LaTeX source is to use tex4ht to create an OpenDocument Format (.odt) file which can then be converted to Word using an application such as LibreOffice. For example, if the LaTeX source is in a file called myDoc.tex then you can create myDoc.odt using:
$ mk4ht oolatex myDoc - Use a version control system.
Possible factors that may affect your choice:
- Security
- There are different levels of document sensitivity,
for example, information about a surprise event (we're organising
Gran's eightieth birthday party, but don't let on); information
about a new product that's patent-pending or about to be released
with a big media splash; examination papers; information about your
country's defence system including launch codes.
Locking up Gran's birthday invitations in a safe within a high-security complex complete with armed guards might be considered overkill. For medium level security, it may be sufficient to have a password-protected version control server located inside your firewall. Servers outside your firewall (including those used by online LaTeX editors) may be sufficient for low to medium security documents, but when you use a third-party system you have to put your trust in their security measures. When considering your options, you need to determine the detriment associated with any security breach. (See also §2.3 Security.)
- Cost
- Some of the solutions aren't free. This may impact your
choice if you have a low budget.
- Operating Systems
- While some solutions are cross-platform,
others might not be. For example, the document build may include
running an application or script that only works on a certain
operating system. In this case, if possible, it may be better to
switch to a cross-platform application (such as one that uses the
Java virtual environment) or scripting language (such as Lua, Perl or Python).
You may not like the cross-platform alternative, but at least all
the authors can build the document.
One or more of the co-authors may have an ancient operating system that doesn't support the latest TeX distributions, or they may not have administrator privileges required to replace an obsolete TeX distribution that was installed a decade earlier. The online LaTeX editors may help with some of these issues, but for security reasons they only allow a limited set of trusted applications (such as makeindex or bibtex) to run.
To a large extent this issue comes back to cost. The operating system may not be upgraded because the hardware is too old. The IT support may be underfunded and lack the resources for system-wide upgrades. In the case of additional applications to help with the document build, a cross-platform alternative may need to be purchased, if available, or a developer hired to create it.
- Recalcitrant Authors
- Compromises have to be made on any
project that involves more than one person. If one or more authors
are determined to use a particular set-up or format or application
that's incompatible with or inaccessible for the rest of the team
then the chances are that the entire project will fail.
The remainder of this chapter is structured as follows:
- §13.1 Change Markup discusses the changes
package to markup changes within the document. This markup can be viewed
in the PDF file or can be suppressed for the final version. The
changes package can be used with LaTeX documents
located on shared folders, under version control, or on an online server.
- §13.2 Version Control discusses how to access
revision information for LaTeX documents under version control.
Documents under version control can be temporarily locked to prevent
conflicting edits, each author can use their favourite text editor
to edit the document, and documents can be rolled back to earlier
versions. However, all authors must make sure they all have
the required class and packages installed.
- §13.3 Online LaTeX Editors discusses online LaTeX editors. Documents on an online LaTeX editor site can be edited by multiple authors, and the authors don't need to worry about installing TeX locally, but they have to use the web interface and may not have access to all LaTeX tools.
This book is also available as A4 PDF or 12.8cm x 9.6cm PDF or paperback (ISBN 978-1-909440-07-4).