Organizing Custom Packages And Files With Local Texmf Trees

The Problem of Scattered TeX Files

When creating custom TeX packages, classes, and files for LaTeX, these files often end up scattered across multiple folders on your file system. This can make it difficult to keep track of custom files and manage them effectively. Some of the issues faced when having disorganized TeX files include:

• Not knowing where a particular file is located when you need to use or edit it later.
• Difficulty in sharing the custom files with colleagues or using them on different machines.
• Problems with file paths when trying to include custom packages or classes that are located in obscure folders.
• Clutter in folders that have many various TeX files mixed together.

The TeX directory structure (TEXMF) provides a standardized way to organize TeX files so they are easy to manage and use across different machines and users. Understanding how to setup a local TEXMF tree for your custom files helps avoid many of the issues that arise from having scattered TeX files.

Introducing Local TEXMF Trees

TEXMF stands for "TeX and Metafont". It specifies a directory structure used by both the TeX and Metafont systems to organize all the relevant files needed to run TeX programs and engines. The folders and locations of these files are called the "TEXMF tree".

By default, engines like pdfTeX and XeTeX, as well as macro packages like LaTeX, will look for input files and documentation using the system-wide TEXMF tree. This includes common folders like:

• /usr/local/texlive/texmf-local (Linux/macOS)
• C:\texlive\texmf-local\ (Windows)

However, we can also setup a custom local TEXMF tree to organize personal or custom created TeX content rather than dumping it all into the system folders.

A local TEXMF tree works just like the system one - it replicates the key TEXMF folders inside a top level folder like ~/texmf on Linux/macOS or C:\texmf on Windows. The TeX engines will check here after looking in the system paths. This provides user-level organization and management of custom TeX content all in one place.

Setting Up Your Local TEXMF Tree

Creating a suitable local TEXMF tree involves just a few steps before you can start moving your custom TeX content there.

1. Create the main texmf root folder for the tree.
   
   For example on Linux/macOS:

        mkdir ~/texmf
        

2. Under this, create some key TEXMF sub-folders like:

      mkdir ~/texmf/tex/{latex,plain,context}
      mkdir ~/texmf/fonts/tfm
      mkdir ~/texmf/fonts/type1
      mkdir ~/texmf/fonts/opentype
      ...
      

3. Create further sub-folders depending on what content you will be storing:

       mkdir ~/texmf/tex/latex/local
       mkdir ~/texmf/bibtex/bib/local     
       mkdir ~/texmf/scripts/local
       ...
       

You don't need every single TEXMF folder, just create the sections you'll actually populate later. The folder structure provides both organization and hints to the TeX engines on what they can find there.

Populating Your TEXMF Tree

Once your local TEXMF structure is setup, you can start moving custom files there. Follow these principles when organizing content:

• Put .sty and .cls files for custom LaTeX packages in:

  texmf/tex/latex/local

• Place font files (.otf, .ttf etc) in:

  texmf/fonts/opentype

• Save .bib BibTeX files to:

  texmf/bibtex/bib/local

• Use

  texmf/scripts/local

  for custom scripts.

• Save LaTeX beamer theme files (.sty) in an appropriately named sub-folder under

  texmf/tex/latex/beamer

Use sub-folders like "local" to indicate custom package content separate from main system files. Adjust locations based on the type of content.

Here is an example local texmf tree populated with some custom content:

~/texmf
├── bibtex
│   └── bib
│       └── local
│           └── mybib.bib
├── fonts
│   ├── opentype
│   │   └── myfont.otf
│   └── tfm
│       └── myfont
│           └── *.tfm
├── scripts
│   └── local
│       └── wrapper.sh
└── tex
    └── latex
        ├── beamer
        │   └── themes
        │       └── mytheme
        │           └── mytheme.sty  
        └── local
            └── mypackage.sty

Updating Your TeX System’s File Database

After moving files to your TEXMF tree, the last step is to update your TeX system's package database so it will lookup files in these custom locations.

• On Linux/macOS, run

  sudo texhash

  to do this system-wide.

• On Windows, run

  initexmf --update-fndb

• Alternatively, pass

  --user

  argument to only update user level file lookups.

You only need to run these commands again if you add or remove entire new folders in your local TEXMF tree.

Using Custom Packages from Your TEXMF Tree

With your customized personal TEXMF tree setup, you can now easily access content like custom package files in your documents, without needing to worry about relative file paths or subfolders scattered everywhere.

For example, to use a custom LaTeX package called mypackage.sty, simply do:

\usepackage{mypackage}

Instead of needing messy direct paths like:

  
\usepackage{../../somefolder/mypackage}

The same applies when using custom bibliography files, fonts, or other content stored under your local TEXMF tree.

Customizing Other Aspects of Your TEXMF Tree

Beyond file organization, local TEXMF trees provide further ways to customize your LaTeX authoring workflow.

You can create custom documentation indexes that TeX systems will lookup when using the texdoc tool for package documentation.

mkdir ~/texmf/texdoc
vim ~/texmf/texdoc/mycustomdocs.cnf

Then adding entries like:

 
mypackage myfile.pdf "My Custom Package"

Similarly, you can create custom font map files, cls & sty caching for engines like LuaLaTeX, and other enhancements with some added configuration.

Local TEXMF trees give you one centralized place to consolidate your TeX content and tools exactly how you like it. The folders act both as an organizational system, and a way to customize package and file lookups across TeX distributions regardless of the system or OS.