Version-controlled LaTeX documents in LHCb

This is about git-based solutions. svn is being retired on 21 February 2019. The obsolete documentation for svn can be found here.

Table of Contents

Warning

The transition from svn to git-based repositories is ongoing. This page is likely to be updated frequently. If anything is wrong, please let lhcb-editorial-board-chair@cernNOSPAMPLEASE.ch know. laso have a look at Patrick's talk at the 15/1 Tuesday meeting.

Overview

There are three places where documents can be hosted:

overleaf

The commercial wysiwyg LaTeX interface supported by CERN. Any kind of LaTeX document can be put there. The Editorial Board (EB) will actually request you to put your paper on overleaf during the EB process. It's the only solution that does not require any knowledge of git.

lhcb-docs on CERN gitlab

The (partial) replacement of the svn (LHCbDocs) repository. Only documents with an official LHCb ID can be hosted there.

User space on CERN gitlab

For any document.

Overleaf

Overleaf is a commercial wysiwyg LaTeX interface supported by CERN. It recently bought ShareLaTeX and the merger of the two platforms resulted in overleaf v2. You can put any kind of LaTeX document there. The Editorial Board (EB) will request you to put your paper there during the EB process.

• Get an account at overleaf/cern. PK logs in via ORCID id, which works well. Your user name is your e-mail address.
• Create a new project
  • You can either share a project with a defined set of users, or with anyone who has the link. While not ideal (overleaf is working on implementing CERN sign-on), we consider this safe enough. It allows all EB members and reviewers to peek at the paper.
  • Since beginning of 2019, overleaf v2 projects can be directly git-cloned. You will need your overleaf username and password.
  • Do not export a project to dropbox! doing so destroys the history and may overwrite comments from EB members.
• Overleaf can be used to comment directly on the paper.
  • Comments can be added in the source. Click on "Review" to view them. The project owner should tick "track changes" at the top of the comments column and allow them for everyone.
  • Comments can also be made on pdf with the packages described here. See an example. However the two kinds of comments are not the same, unfortunately.
• EB members and reviewers may also fix obvious mistakes directly.
  • Tagged versions can be compared in History & Revisions mode and undone. It is therefore recommended proponents and EB members tag versions frequently.
• Please make sure the draft you send compiles. Overleaf will happily produce a pdf even if there are errors. Watch out for the red flag next to "Recompile".

lhcb-docs group on gitlab

Past, present and future LHCb documents with an assigned LHCb ID will be hosted in lhcb-docs. The transition from svn is ongoing and thus the group is not yet in production. Interested users can ask for a project by contacting lhcb-editorial-board-chair@cernNOSPAMPLEASE.ch. The group contains subgroups matching CDS categories: PAPER, CONF, ANA, INT, PUB, TDR and DP. Eventually directories will be automatically created there when LHCb document IDs are requested from the secretariat, but the infrastructure is not there yet.

In the meantime you can do the following. Suppose you want to create a new note LHCb-ANA-2018-123, or copy an already existing LHCb-ANA-2018-123 project from svn.

• On lhcb-docs, you can create a new project at https://gitlab.cern.ch/lhcb-docs/ANA
• It should be called LHCb-ANA-2018-123 (please make sure the capitalisation is correct, in particular in the project "slug" - gitlab will by default uncapitalise it).
  • Once you are manager you can fix that under Settings -> Advanced -> Expand -> Rename
  • In addition to the EB chair, everyone with "owner" status in this list can make you manager: https://gitlab.cern.ch/groups/lhcb-docs/ANA/-/group_members?sort=access_level_desc
• Then you can follow the instructions to upload your project from you local copy. But DELETE the .svn directory first or you will import the svn internal stuff into git.
• What you presently cannot do is become a manager of this project. This requires action from the EB chair or any software librarian. So just let lhcb-editorial-board-chair@cernNOSPAMPLEASE.ch know when you are ready.

In the above, replace ANA by whatever appropriate for other types of documents. There is no need to copy old documents that are no longer updated. A script will take care of that in early 2019.

Gitlab User space

All LHCb members have a user space at https://gitlab.cern.ch/. Personal documents and drafts of LHCb documents can be hosted there. This replaces the svn LHCbDocs user space.

How do I access old documents on svn?

All svn directories have been zipped and made available online at https://lhcb-notes.web.cern.ch/lhcb-notes/svn-archive/. You may browse files and download zips.

LHCb Template

Presently the template lives on gitlab at this url. It will eventually be mapped on overleaf once it supports gitlab.

-- PatrickSKoppenburg - 2018-12-21