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