How to deal with cls and sty files, relative paths and different platforms in a multi-user git repository?

Question

To inlcude our self-written class we are currently using relative paths (\documentclass{../ourclass}), which triggers a warning (wrong class provided) and is rather ugly. The solution to this problem is discussed in these questions, for example:

But none of these questions discusses versioned multi-user/platform git repositories. The ideal situation would be that a new member or a member that got a new computer just checks out the repository and can build the documents as long as he has an up-to-date standard TeX distribution. So that the repository is fully self-containing and no tweaking of local PATH or texmf stuff is needed for each and every member/computer/operating system - all project-specific configuration should be defined within the git repository.

What are good approaches to such a situation? How to keep the user or per-computer configuration to a minimum and store all build configuration in a central repository?

Based on the answer given so far, I feel like some additional clarity requirements need to be added to the bounty qualification: — rpspringuel, Dec 17 '16 at 19:09

score 4 · Answer 1 · edited Jun 10 '20 at 12:32

I assume that you have one Git repository which contains your custom class, but that not every document generated with the class is to be included in the same (or any other) repository, but might exist just as a local copy.

(1) Submitting your class to CTAN

If the class source does not contain any sensitive information, you could upload your class to CTAN. After some time, it will be available in TeXLive/MikTeX distributions and every user that has an up-to-date TeXLive/MikTeX installation can use \documentclass{ourclass}. This is particularly useful if the class has reached a certain maturity and is expected to need only low maintenance.

(2) Cloning the Git repository multiple times

Usually, class files/folders do not exceed a few hundred kilobytes in size, already including vector image files, custom bibliography styles, etc. So every team member could, after creating a new project folder, call a git clone within the specific project folder. Via copies of local repositories and the --reference option of git clone, network usage could be optimised. Maybe you could supply scripts to your team members that automate and optimise intial cloning and subsequent pulling.

(3) Project folder structure

(1) and (2) would work without relative paths, which is what you requested. However, changing the folder structure on your team's computers might also be worth considering, e.g.

/home/.../git/                                (or C:\Users\...\git\)
             .../customclass/class.cls
             .../project-1
             .../project-2
                 ...

Then, keep the practise of \documentclass{../customclass/class}. This would require to ignore the warnings. If I may add a personal opinion: I did not fully understand why ignoring this specific warning should be problematic.

As I understood the question, all documents to be built with the class also reside in the repository. At least, that's my use case and why I'm interested in an answer. As such, option 2 isn't of much use. Option 1 is an idea, but as my class file is still in its experimental phase and it can take several days for a CTAN change to propogate to the end users, it's not very practical for the rapid development currently in progress. — rpspringuel, Dec 17 '16 at 14:54
Option 3 is approximately what I'm doing right now, but I have collaborators who are relative novices with LaTeX and any warnings tend to scare them. I'm hoping for a solution which eliminates the warning so that as to make learning LaTeX smoother for them. — rpspringuel, Dec 17 '16 at 14:58
While not an ideal answer, I think this is the best of the bunch (most detailed and large number of possibilities covered) and thus deserving of the bounty. — rpspringuel, Dec 22 '16 at 19:57
Maybe a fourth possibility would be symbolic links. I quickly checked \documentclass{symbolic-link}on both Windows and Linux systems and it works just fine. I grasped hear-say that Linux symlinks also work on Mac OS X. The command to create a symbolic link on Windows is mklink, which is a rather new addition to Win. The idea would be to place both Windows and Linux-compatible symlinks in the repositories, linking to the one class file. However I failed to inject these symlinks into a Git repository (one Git server I tried simply rejected symlinks) — Felix Emanuel, Jan 02 '17 at 21:11

score 2 · Answer 2 · answered Dec 19 '16 at 15:24

If the class/style files should be used by various documents on the user-PC's then you can't imho avoid some installation in some texmf-structure.

So your user could clone the repository into some existing texmf tree (e.g. texmflocal or texmfhome in a texlive system, or UserData in miktex (where you need to update the FNDB afterward). Or the git repository could create a new texmf-tree and then user will have to make this texmf-tree known to the tex system: In miktex this can be done with a GUI or with a batch file which calls initexmf --register-root, in texlive there is no built-in solution and one would have to change the texmf.cnf, or add a local texmf.cnf file and change the TEXMFCNF environment variable to point to it (but it should be possible to do this with a script too).

score 1 · Answer 3 · edited Apr 13 '17 at 12:34

1

If you're using a build system, such as Makefile, latexmk, you could set the environment variable TEXINPUTS — it is the path that TeX searches for files during compilation.

So setting TEXINPUTS=.//:../relative/path/to/class//:, either in a Makefile, shell script, or otherwise, would allow you to use files in that directory as if they were in the current directory — without throwing warnings. See egreg's answer to Definition of the TEXINPUTS variable.

edited Apr 13 '17 at 12:34

Community

1

answered Dec 17 '16 at 15:13

Michal Sudwoj

326

Unfortunately some of my collaborators are command-line adverse and use a GUI IDE (mostly TeXShop or TeXworks). As far as I can tell, this suggestion won't work for them. – rpspringuel Dec 17 '16 at 19:09

How to deal with cls and sty files, relative paths and different platforms in a multi-user git repository?

3 Answers3

(1) Submitting your class to CTAN

(2) Cloning the Git repository multiple times

(3) Project folder structure