Smile for the Camera: a new cybercrime short story ebook.

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:

  1. 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.

  2. Fred decides to use package foo, which is available on his MiKTeX distribution, but Mabel doesn't have foo on her TeX Live distribution.

  3. 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.

  4. 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.

  5. 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.

  6. Prof Important Person has decided he's also going to contribute to the document but insists on using his favourite word processor.

  7. 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.
The more co-authors on the document, the more likely these problems will occur. The last case is an issue that may also need addressing for a single-authored document. This chapter describes ways of circumventing these problems, but the most convenient solution may not necessarily be the most appropriate solution if you have to take into account factors such as security or available resources or recalcitrant co-authors.

Here are some possible solutions to the above problems:

  1. 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).

  2. 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.

  3. Fred and Mabel both update their TeX distributions before they start working on the document or they use an online LaTeX editor.

  4. 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.

  5. Use LaTeX commands to markup the changes (§13.1 Change Markup) or use version control.

  6. 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

  7. Use a version control system.

Possible factors that may affect your choice:

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.)

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:

This book is also available as A4 PDF or 12.8cm x 9.6cm PDF or paperback (ISBN 978-1-909440-07-4).

© 2015 Dickimaw Books. "Dickimaw", "Dickimaw Books" and the Dickimaw parrot logo are trademarks. The Dickimaw parrot was painted by Magdalene Pritchett.

Terms of Use Privacy Policy Cookies Site Map FAQs