# dfg-crc — Collaborative Research Centre proposal class

Current release: **0.1.0 (2026-08-03)**.

The `dfg-crc` LuaLaTeX class provides the proposal and CV structure for a
German Research Foundation (DFG) Collaborative Research Centre (CRC). It uses
structured metadata to generate project heads, staff and funding tables,
project lists, collaboration plots, Gantt charts, and proposal-wide totals.

This is an independent, unofficial template. It is not published, endorsed,
or maintained by the DFG; applicants remain responsible for checking the
current DFG forms and programme rules.

The supplied proposal template is designed for five calendar years and
supports one or more applicant universities. The project types `research`,
`service`, `mgk`, and `admin` are supported; see the documentation for the
corresponding metadata and generated sections.

It is appreciated when in the colophon of your proposal a reference to this
template and its author is given.

## Requirements

The class requires LuaLaTeX and a LaTeX kernel dated 2022-06-01 or newer.
Biber is required for bibliographies. The default setup uses Noto Serif,
Roboto, and the example images supplied by the `mwe` bundle. A full
[TeX Live](https://tug.org/texlive/) installation is recommended and contains
the class's runtime dependencies.

Repository: <https://gitlab.git.nrw/rpdm/projects-and-services/dfg-crc-template>

Issue tracker:
<https://gitlab.git.nrw/rpdm/projects-and-services/dfg-crc-template/-/issues>

## Installation

TeX Live and MiKTeX installations obtained after the first CTAN release can
install `dfg-crc` through their normal package managers. To install from the
CTAN source archive manually, run:

```
luatex crc-proposal-documentation-and-code.ins
```

This generates `dfg-crc.cls`. Move it into a directory searched by TeX, or
keep it beside the proposal's main `.tex` file. The complete generated example
proposal is maintained in the repository and can be extracted with
`make files`.

## Start the program from the repository

For a first local compile, generate the derived files and then compile the
proposal and CV examples from the `local/` folder.

```
make files
cd local
latexmk -lualatex crc-proposal.tex
latexmk -lualatex crc-cv.tex
```

The class is designed for LuaLaTeX. Use `lualatex` or `latexmk -lualatex`;
do not call `LaTeX` with a capital `L`.

Useful make targets:

> `make files`: extracts `dfg-crc.cls` and the local template files from
the documented source. <br>
> `make update-class TARGET_DIR=/path/to/proposal-worktree`: regenerates and
copies only `dfg-crc.cls` into a separate Git worktree. <br>
> `make test`: compiles the generated template test document. <br>
> `make test-direct-costs`: compiles the focused two-pass regression for DFG
> table 2.1.1. <br>
> `make proposal-example`: compiles the generated local proposal example. <br>
> `make cv-example`: compiles the generated local CV example. <br>
> `make check`: runs the test and compiles both examples. <br>
> `make doc`: builds the implementation and user documentation. <br>
> `make ctan-check`: builds the curated CTAN archive and verifies a clean
installer extraction and minimal LuaLaTeX compile. <br>
> `make ctan-validate`: runs the official online CTAN validator without
submitting the archive.

For a focused project-text build, select the project with `\includeonly` and
use these class options:

```tex
\documentclass[
  fastcompile-project=true,
  fastcompile-project-show-images=false,
  fastcompile-project-show-publications=false,
  english
]{dfg-crc}
```

`fastcompile-project` skips metadata loading, `\addEntry` execution,
calculated project heads, generated tables/lists, Gantt charts, embedded
graphics, and other front-matter work while retaining authored sections,
paragraphs, aims, work packages, labels, and citation commands. Skipped
generated tables and lists retain the same visible placeholder and
log note as ordinary `fastcompile` builds. Set
`fastcompile-project-show-images=true` to render images encountered in the selected
project while retaining the other fast-mode reductions. Set
`fastcompile-project-show-publications=true` when the selected project's publication headings,
explicit `\nocite` entries, and bibliography should be included. Wrap optional
metadata and front matter with `\dfgIfFastCompileProjectF{...}` so those files
are not even read in this mode. With publications disabled, bibliography source
files and stale `.bbl` data are also left unread; inline citations display their
keys as lightweight drafting markers. Compile a document using these options
with its own build command; the template Makefile deliberately operates only on
the generated test and example documents in `local/`.

## Template validation workflow

Run `make check` to regenerate the template files, compile the test document,
and compile both local examples. Run `make all` to perform those checks and
build the complete implementation and user documentation. These targets use
only files maintained or generated by this repository.

GitLab CI runs the same compile-based checks for branches and merge requests.
After a successful default-branch pipeline, GitLab Pages publishes the newest
generated `local/crc-proposal.pdf`. The Pages site is rebuilt from an empty
`public/` directory each time and therefore exposes only the latest dummy
proposal, not an archive of earlier PDFs. CI job artifacts retain the current
logs and example outputs temporarily for diagnosing failed pipelines.

## Updating a separate proposal repository

Edit the maintained `.dtx` source, then install the regenerated class into a
separately controlled proposal worktree:

```
make update-class TARGET_DIR=/path/to/proposal-worktree
```

The target verifies that `TARGET_DIR` is the root of a different Git worktree,
copies only `dfg-crc.cls`, and shows its resulting Git status. It does not store
the destination, inspect its remote, commit, or push. Review and commit the
class update from inside that proposal repository.

## Repository boundary

This repository is intentionally limited to the reusable proposal template.
Project-specific source, synchronization configuration, credentials, remote
identifiers, and private working copies must remain in separately controlled
repositories or local worktrees and must not be added here as submodules.

## Structure of the files and folders

The maintained source is `crc-proposal-documentation-and-code.dtx`.
Generated files such as `local/dfg-crc.cls`, `local/test.tex`,
`local/test-existing-funds-direct-costs.tex`,
`local/test-project-collaboration.tex`, `README.md`, `CHANGELOG.md`, and the
local example files are extracted from that source.
Edit the `.dtx` for template or documentation changes, then regenerate the
derived files with `make files` or by building the documentation.

## Generated project templates

The generated `local/content/03_project.tex` is a small master file that loads
separate, complete project examples. They are intended to be copied and adapted
rather than reduced to a list of headings:

`03_project_A01.tex`: continuing research project (`project-status=C`).

`03_project_A02.tex`: new research project (`project-status=N`).

`03_project_B01.tex`: second continuing research-project example.

`03_project_B02.tex`: ending project (`project-status=E`), including the report
bibliography, the three published-result categories, and the staff roster for
the ending funding period.

`03_project_Q01.tex`: continuing service project.

`03_project_Q02.tex`: continuing Integrated Research Training Group
(`project-type=mgk`), including existing funds, fellowships, and global funds.

`03_project_Q03.tex`: central administrative project with its dedicated
documentation and funding structure.

Every example starts with `\printProjectHead{<id>}`. That command already
generates the general-information heading, project title, project leaders, and
the applicable contract and legal-information blocks from metadata. The source
files therefore begin with the first status-specific authored heading: `Summary`
for active projects and `Project history` for ending projects.

The generated proposal-wide example follows the February 2026 continuation
template, including the ecological-sustainability section, separate
coordinating and co-applicant universities, the current legal-issues wording,
and one rector, chancellor, or president signature per applicant university.

> `bib/`: all bibliography files.  <br>
> `content/`: all files which are part of the actual content of the proposal,
e.g. all project textfiles.  <br>
>  `figures`: folder contains all figures of the projects.  <br>
>  `img`: folder can be used for logo files etc.  <br>
>  `metadata`: if you collect all database entries in specific external
  files, they are placed in this folder (e.g. `dfg-metadata.tex`).  <br>
> `preamble`: all files for the proposal and CV setup, especially
  `dfg-customization.tex` for customized things or re-newed settings.<br>

## Minimal metadata relationship

Most commands resolve data by following ids through the small databases:

```
person.ref-institution-id -> institution.id
institution.ref-affiliation-id -> affiliation.id
project.collaborations -> project.id
```

For example, a person may list one or more institution ids in
`ref-institution-id`. Each institution points to its parent affiliation via
`ref-affiliation-id`. Once this relationship exists, commands such as
`\dfgInstitutionList{<person-id>}` can print the institution and affiliation
data without further manual wiring.  Each institution can also provide an
`abbreviation`; generated table cells use this compact label while descriptive
lists and legends retain the full `name`.

The same relationship is reused by `RequestedFundingStaff`: when a staff row
contains `ref-person-id`, its category and institution are taken from the
person's `position` and `ref-institution-id` fields unless the staff row
explicitly overrides them.

Project collaboration plots follow the comma-separated project ids stored in
each project's `collaborations` field. Relations are undirected, so declaring
the same pair in both project rows is harmless but unnecessary. Ending,
reference-only, and list-excluded project rows remain available elsewhere but
are omitted from these plots.

## Information retrieval command overview

The following commands can be used directly in proposal text and tables. In
the signatures below, square brackets are optional and braces are mandatory.
The complete descriptions and examples are in
`crc-proposal-documentation-and-code.pdf`.

### General database access

Command `\getEntry` with `[database]` `{id}` `{field}` `[id-field]` prints one field from one
  database row.

Starred command `\getEntry*` with `[database]` `{id}`
`{assignments}` `[id-field]` fetches several fields in one lookup and assigns
them without printing. For example, fetch person `MM` with
`\getEntry*[person]{MM}` and pass the third argument
`{\theFirstName=firstname,\theLastName=lastname}`.

Command `\compareEntry` with `[database]` `{id}` `{field}` `{value}` `{true}`
  `{false}` chooses text or
  code according to a field comparison.

### People, institutions, and projects

Commands `\getName` and `\getFullName*` with `{person-id}` print the last name or full name;
  the star adds the academic degree.

Command `\getPI*` with `{person-id-list}` `[text]` prints a linked PI reference; the star includes
  first names.

Command `\getORCiD` with `[database]` `{person-id}` prints a linked, formatted ORCiD from a person row.

Command `\getORCiDvalue` with `[database]` `{person-id}` stores the unformatted ORCiD in
  `\theORCiDValue`.

Command `\dfgInstitutionList` with `[database]` `{person-id}` `[options]` prints institutions and
  parent affiliations assigned to a person.

Command `\getPersonInformation` with `[database]` `{person-id-list}` prints complete formatted
  PI/contact-information blocks.

Command `\getPIsWithRole` with `[database]` `{role}` `[options]` prints formatted current-period people
  carrying a given role.

Command `\getPIProject*` with `{person-id-list}` prints each PI with their assigned projects; the
  star includes first names.

Command `\getProjectPI*` with `{project-id-list}` prints each project with its assigned PIs; the
  star includes first names. By default, the shared first `\getProject` or
  `\getProjectPI` reference to a project within one section includes its PIs;
  later references print only the project. Set
  `projectPIOncePerSection=false` in `\changeSettings` to repeat the PI names.

Command `\getPIofProject` with `[properties]` `{project-id}` `[delimiter]` prints selected PI name
  properties for one project.

Command `\getProject` with `{project-id-list}` `[text]` prints a linked project
  reference. Optional `text` replaces the displayed project number while
  retaining its link target and is best used with a single project. A
  reference-only project is marked and deliberately left unlinked. Multiple
  projects are joined with commas and a final `and` in prose, but use compact
  slash separators inside table cells, for example `A02/B01`. With the
  default `projectPIOncePerSection=true`, this command shares
  `\getProjectPI`'s first-reference PI expansion and per-section state.

Command `\getProjectCount` with `[area]` prints the active, list-considered
project count; omit `area` for all projects. Any explicit or ID-derived
`project-area` value is accepted.

Command `\printPlot{{ProjectCollaboration}{A01}}` prints the default
collaboration heatmap for A01. Add `[layout=arc]` after
`{ProjectCollaboration}` for the compact arc layout. The optional
`project-area` field creates rows dynamically and falls back to the first
character of the project ID. Configure proposal-wide colors with
`collaborationAreaColors` and `collaborationAreaPalette` in `\changeSettings`,
or use the per-plot `area-colors` and `area-palette` options. Gantt charts use
the same dispatcher as `\printPlot{{Gantt}{A01}}`.

Command `\dfgResearchAreasList` with `{code}` prints a DFG research-area code and its description.

Commands `\getAim` and `\getWP` with `[project-id]` `{id-list}`
  cross-references to project aims or work packages; the current project is
  the default.

### Person statistics

Command `\getPositionGenderPhaseAmount` with `[database]` `{position}` `{gender}` `{period}` prints the number
  of people for one position/gender/period tuple.

Command `\getPositionPhaseTotal` with `[database]` `{position}` `{period}` prints the all-gender total for a
  position and funding period.

Command `\getGenderPhaseTotal` with `[database]` `{gender}` `{period}` prints the all-position total for a
  gender and funding period.

Command `\getPositionGenderPhasePercentage` with `[database]` `{position}` `{gender}` `{period}` prints the
  rounded integer percentage within one position.

Command `\getGenderPhasePercentage` with `[database]` `{gender}` `{period}` prints the rounded integer
  percentage across all counted positions.

### Funding and staff totals

The similarly named funding commands have different scopes: names ending in
`RequestedFunding` use the proposal-wide overview by default, while names
ending in `RequestedFunds` use project-level funding rows and require a
project id.

Command `\getCountRequestedStaff` with `[project]` `{year}` `{category}` prints the requested staff
  quantity for a category, optionally restricted to a project.

Command `\getSumRequestedFunding` with `[database]` `{year}` `{type}` prints the proposal-wide total for one
  funding type and one year; `{all}` as the year totals all five years.

Command `\getTotalSumRequestedFunding` with `[database]` `{year}` `{type}` prints the proposal-wide total
  with `{all}` as the type available for a grand total.

Command `\getSumPreviousRequestedFunding` with `[database]` `{year}` `{fields}` prints the previous-period
  total for one year row, or all rows with `{all}` as the year.

Command `\getSumRequestedFunds` with `[database]` `{project}` `{type}` `{sum-fields}` prints the project total
  for one funding type and one or several `sum-yearN` fields.

Command `\getTotalSumRequestedFunds` with `[database]` `{project}` `{sum-fields}` prints the project total
  across all funding types for the supplied `sum-yearN` fields.

Command `\getSumRequestedFundsInstrumentation` with `[project]` `{sum-fields}` prints the instrumentation
  total, proposal-wide or for the optional project.

Command `\getSumRequestedFundingDirectCosts` with `[database]` `{year}` `{group}` prints the direct-cost
  total for `applicant`, `participant`, `other-funds`, or `all`. Its default
  database is the auxiliary-file-backed
  `RequestedAndExistingFundingDirectCostsOverview`, and its displayed result
  is a full euro amount without decimal places.

Command `\getSumExistingFunds` with `[database]` `{project}` `{sum-fields}` prints the existing direct-cost
  funding for a project and the supplied year fields.

Typical calls are:

```tex
\getProjectCount[A]                            % active A projects
\getSumRequestedFunding{all}{staff}            % proposal-wide staff total
\getTotalSumRequestedFunding{all}{all}         % proposal-wide grand total
\getSumRequestedFunds{A02}{staff}{sum-year1}   % A02 staff total, year 1
\getTotalSumRequestedFunds{A02}{sum-year1}     % A02 grand total, year 1
```

Funding entries, including requested instrumentation, use EUR as their input
unit. Their tables state `Figures in EUR` and display whole euro amounts with
thousands separators. The non-aggregated `existingInstrumentation/cost` field
instead uses thousands of EUR and its table states `Figures in thousands`;
one decimal place is retained when supplied. Explicitly fractional
animal-housing rates also retain decimals, while the other monetary columns in
that table remain whole euros.

### Existing direct-cost support in section 2.1.1

Declare institutional and other existing direct-cost support once, next to
the corresponding project table:

```tex
\addEntry[funding]{RequestedAndExistingFundingDirectCosts}{
  ref-project-id     = {B06},
  ref-affiliation-id = {aff1},
  financed-by        = {Faculty core support},
  sum = {
    year1 = {5000},
    year2 = {5000},
    year3 = {5000},
    year4 = {5000},
    year5 = {5000}
  }
}
```

The sums are stored and displayed in euros. Table 2.1.1 therefore prints
`5000` as `5,000`; monetary values are rounded to the nearest euro for display
and never acquire a redundant decimal part. An affiliation listed in
`meta/crc.ref-affiliation-id` contributes to the applicant-university column;
another affiliation contributes to the other-participating-institutions
column; and the special value `other-funds` contributes to Other funds.
`financed-by` is the human-readable funding-source description and does not
select the aggregate column.

The declarations may remain in project files even though section 2.1.1 comes
earlier. They are restored into a separate overview database through the
LaTeX auxiliary files. A normal multipass build such as `latexmk` is therefore
required after adding or changing a row; no duplicate chapter-2 declaration
is needed.

## Open-access markers in bibliography entries

The class loads `biblatex-ext-oa` so bibliography entries can show
open-access markers in final documents. The DOI API integration is only
available with LuaLaTeX. With LuaTeX 1.17.0 or newer, the socket library must
also be enabled on the command line, for example with `lualatex --socket`.
Provide the contact address required by the API in the customization file:

```tex
\changeSettings{
  doiAPIMail = researcher@example.org
}
```

The class enables DOI lookups only when `final=true`, `doiAPIMail` is not
empty, and LuaSocket is available. Otherwise it retains manual open-access
annotations without making network requests.

If the API-based open-access request does not work for a publication, add the
manual fallback annotation to the relevant `.bib` entry:

```
options         = {openaccess=auto},
doi+an:default  = {=openaccess},
```

## Troubleshooting

Use `latexmk -lualatex ...` or `lualatex ...`. The command `LaTeX` asks TeX for
a format named `LaTeX.fmt` and will usually fail.

If you see `Not allowed in LR mode`, check whether vertical material such as
`\vspace`, `\addvspace`, or a paragraph break was inserted inside a table cell
that only accepts horizontal material. Prefer the documented commands and
options instead of adding raw vertical spacing in table cells.

`Unknown database name` means the requested database has not been loaded or the
database name was misspelled. Check the relevant file in `metadata/` and make
sure it is input by the document class.

Missing-key or empty-value warnings mean the row exists, but the requested
field is empty. This is intentional for fields where the template needs to
alert you, such as missing ORCiD values.

If a change has no visible effect, check which `dfg-crc.cls` is being used.
Regenerate the class and local examples with `make files`, then compile the
relevant example again.

## Maintainer release checklist

1. Update `\dfgVersion`, `\dfgVersionDate`, the README release line,
   changelog, and `dfg-crc.pkg` in one commit.
2. Build the documentation and the CTAN archive, then run the portable
   installer and minimal-class smoke test:

   ```
   make ctan-check
   ```

3. Run at least one proposal/CV smoke build from `local/`:

   ```
   cd local
   latexmk -lualatex -g -halt-on-error crc-cv.tex
   ```

4. Before a public release, run the complete template check:

   ```
   make check
   ```

5. Optionally run the official online validator with
   `make ctan-validate`.
6. Review `git status --short`, `git diff --check`, and the archive file
   list before committing and tagging the exact release version.

## Support

The current maintainer is
[Lukas C. Bossert](mailto:bossert@itc.rwth-aachen.de).

## License

This material is subject to the LaTeX Project Public License 1.3c or later.
The work has the LPPL maintenance status *maintained*. See `LICENCE.md` for the
complete notice.
