businesscard-qrcode/README.md

Businesscard with QR-Code
=========================

What happens when you hand someone a business card? Either they type everything manually, or the card gets forgotten. This class generates a print-ready business card with a QR code that embeds a full [vcard], so contact data can be imported directly with a scanner [app].

Compared to templates that place many cards on A4, this project focuses on professional printing workflows: one card per PDF page, exact dimensions, and crop marks.

[![Example: John Doe from Hongkong](screenshots/john-doe-hongkong.png)](examples/john-doe-hongkong.tex)
[![Example: Businesscard of Peter Muster from Zürich](screenshots/peter-muster-example-company-zuerich.png)](examples/peter-muster-example-company-zuerich.tex)
[![Example: Nearly Real Example Of My Card](screenshots/example.png)](examples/example.tex)


Features
========

- full contact payload in QR code (vCard 4.0)
- privacy control per field via optional `[hide]` (in QR only, not printed)
- configurable layout: alignment, icon placement, text/QR order, spacing, card dimensions
- professional print output with crop marks and exact paper/content size
- visual customization: logos, QR-center logo, background image/color, text color, QR color
- social/contact integrations ([jabber], [matrix], [gitea], [github], [git], [facebook], [twitter], [youtube], [wikipedia], [nextcloud federation id])
- PGP key URL and fingerprint support
- multi-page PDFs (e.g. front/back variants) with `\newcard`


Quick Start
===========

```latex
\documentclass{businesscard-qrcode}

\type{home}
\givennames{An}
\familynames{Example}
\street{Einbahnstrasse\ 84}
\city{Irgendwo}
\zip{1001}
\country{Switzerland}
\homepage{example.com}
\email{name@example.com}

\begin{document}
  \drawcard
\end{document}
```

Compile with:

```bash
xelatex -interaction=nonstopmode your-card.tex
```


Installation
============

Copy `businesscard-qrcode/businesscard-qrcode.cls` to your LaTeX class path. Simplest way on Linux:

```bash
mkdir -p ~/texmf/tex/latex/businesscard-qrcode
cp businesscard-qrcode/businesscard-qrcode.cls ~/texmf/tex/latex/businesscard-qrcode/
ln -s ~/texmf/tex/latex ~/texmf/tex/xelatex
```


Compilation Notes
=================

- Use **`xelatex`** (UTF-8 support, e.g. umlauts, CJK).
- Do **not** load `inputenc` with this class.
- vCard line endings default to CRLF (`crlf` option) for better iOS import compatibility.

### Building with latexmk / IDEs

Editors such as VS Code LaTeX Workshop usually call `latexmk` from the workspace root. This repository ships project-local `.latexmkrc` files (root and `examples/`) that extend `TEXINPUTS` so TeX prefers the local class file from this checkout.

If you invoke `xelatex` manually without `latexmk`, set:

```bash
TEXINPUTS=/path/to/businesscard-qrcode:
```

(or run from the repository root).


Document Structure
==================

```latex
\documentclass[<layout-options>]{businesscard-qrcode}

<data-definitions>

\begin{document}
  \drawcard
\end{document}
```


Escaping Spaces in Data
=======================

Spaces inside macro arguments must be escaped as `\ `, otherwise TeX may collapse them before QR/vCard generation.

```latex
\company{Example\ Company\ Ltd.}
\city{New\ York}
\phone{+41\ 44\ 123\ 45\ 67}
```


Layout Options
==============

You can set layout options in four ways:

1. `\documentclass[...]` (global defaults)
2. `\cardsetup{key=value,...}` (runtime/global from that point)
3. `\drawcard[key=value,...]` (runtime, convenient per page/card)
4. command-style setters `\set...{...}` (one setter per option)

Note: direct commands like `\paperwidth{...}` or `\color{...}` would clash with core LaTeX commands/lengths, therefore the command API uses `\set...{...}` names.

```latex
\documentclass[textwidth=0.7,qrwidth=0.25,www,nofill,iconright,rightalign,hint,icon,textfirst]{businesscard-qrcode}
```

```latex
% runtime/global
\cardsetup{textfirst,noicon,qrwidth=0.35}

% per card/page
\drawcard[noqr,noheader,layout=centered]

% command-style
\setqrwidth{0.35}
\seticon{false}
\setlayout{centered}
```

### Paper and Geometry

- `paperwidth=`: physical paper width, default `89mm`
- `paperheight=`: physical paper height, default `59mm`
- `contentwidth=`: inner content width, default `85mm`
- `contentheight=`: inner content height, default `55mm`
- `padding=`: inner padding, default `2mm`
- `cutdist=`: crop-mark distance, default `2`
- `cutlen=`: crop-mark length, default `1`

### Typography and Layout

- `fontsize=`: one of `8pt,9pt,10pt,11pt,12pt,14pt,17pt,20pt`, default `8pt`
- `textwidth=`: relative text block width, default `0.50`
- `qrwidth=`: relative QR block width, default `0.40`
- `qrfirst` / `textfirst`: QR left/right order, default `qrfirst`
- `header` / `noheader`: show/hide top name block + separator line, default `header`
- `qr` / `noqr`: show/hide QR block, default `qr`
- `layout=`: `standard` (default) or `centered`
- `headeremphasis=`: `person` (default), `company`, or `balanced`
- `rightalign` / `leftalign`: text alignment, default `rightalign`
- `iconleft` / `iconright`: icon side, default `iconleft`
- `fill` / `nofill`: fill space between icon and text, default `fill`

### Address, Links, and Formatting

- `address` / `noaddress`: include address in print + vCard, default `address`
- `hint` / `nohint`: show small protocol hints, default `hint`
- `icon` / `noicon`: show icons, default `icon`
- `https` / `www`: hint URL style, default `https`
- `lang=`: wikipedia language prefix, default `de`
- `countryformat=`: `auto` (default), `inline`, or `below`
- `crlf` / `nocrlf`: vCard newline style, default `crlf`

### Colors and QR Tuning

- `color=`: global text color, default `black`
- `qrcolor=`: QR module color, default `black`
- `qreclevel=`: `L`, `M`, `Q`, `H`, default `H`
- `qrlogoscale=`: QR-center logo size fraction, default `0.25`
- `qrlogoborder=`: QR-center logo padding fraction, default `0.02`
- `qrbgopacity=`: QR white background opacity, default `1.0`

### Logo and Background

- `logoheight=`: default logo height near name (with unit). Auto-default: `4em` if company exists, else `2em`
- `bgscale=`: background image scale, default `1.0`
- `bgopacity=`: background image opacity, default `1.0`

Standard Layout Blueprint (Normalfall)
======================================

The diagram below shows the default `layout=standard` with `header=true` and `qr=true`
(`qrfirst` variant: QR on the left, text on the right):

![Standard layout blueprint](screenshots/layout-standard.svg)

What Influences What (Standard Layout)
--------------------------------------

- `paperwidth/paperheight/contentwidth/contentheight/padding`: define the outer geometry of the whole card.
- `header/noheader`: enables/disables the complete top block (name/logo/company line + separator line).
- `headeremphasis=person|company|balanced`: controls relative visual weight in the header (`person`: name larger, `company`: company line larger, `balanced`: same size).
- `logo` + `logoheight`: affects header composition and reserved vertical space.
- `company[height=...]` / `companylogo[height=...]`: affects second header line and reserved space.
- `textwidth` and `qrwidth`: define horizontal split of body columns.
- `qr/noqr`: removes the QR column; text then uses full body width.
- `qrfirst/textfirst`: swaps left/right order of QR and text columns.
- `icon/noicon`, `hint/nohint`, `iconleft/iconright`, `fill/nofill`: only affect formatting inside text lines.
- address field presence/visibility: controls whether address block (and map-pin icon) is rendered.
- `pgpfingerprint`: adds an extra footer line and reserves additional vertical space.
- `background`/`bgscale`/`bgopacity`: visual background only, no content reflow.
- `qrlogo`/`qreclevel`/`qrlogoscale`/`qrlogoborder`: QR internals only, no column reflow.


Data Definitions
================

Define data via commands like:

```latex
\email{name@example.com}
```

All data commands support optional `[hide]` (or `[hide=true]`): value remains in QR/vCard but is hidden in printed text.

```latex
\email[hide]{secret@example.com}
```


Recognized Commands
===================

### Name and Identity

- `\type`: `home` or `work` (used in ADR/TEL/EMAIL vCard typing)
- `\honoricprefix`: name prefix/title
- `\givennames`: given names
- `\additionalnames`: additional/middle names
- `\familynames`: family names
- `\honoricsuffix`: name suffix
- `\title`: position/job title (also contributes to displayed/vCard full name)
- `\role`: role/function
- `\company[logo=...,height=...,hide]`: company text with optional inline logo configuration

### Address

- `\pobox`
- `\extaddr`
- `\street`
- `\city`
- `\region`
- `\zip`
- `\country`

### Contact

- `\phone`
- `\email`
- `\jabber`
- `\matrixorg`
- `\cloud`

### Web and Social

- `\homepage`
- `\world`
- `\link`
- `\wordpress`
- `\drupal`
- `\joomla`
- `\wikipedia`
- `\git`
- `\gitea`
- `\github`
- `\facebook`
- `\twitter`
- `\youtube`
- `\google`

### Crypto

- `\pgpurl`
- `\pgpfingerprint`

### Visual Content

- `\logo[height=...]{content}`: logo near name (file path or TeX content)
- `\qrlogo[scale=...,opacity=...]{content}`: logo in QR center (file path or TeX content)
- `\background[scale=...,opacity=...]{file-or-color}`: background image or color
- `\centercontent{...}`: custom content used by `layout=centered`
- `\companylogo[height=...]{content}`: backward-compatible company logo helper

### Multi-Page and State Control

- `\clearfield{<name>}`: remove one field (printed + QR/vCard)
- `\clearcard`: remove all card fields plus card-scoped visuals (`\title`, logo, QR logo, background)
- `\clear{<name>}`: alias of `\clearfield{<name>}` (when no other package already defines `\clear`)
- `\newcard`: alias of `\newpage` + `\clearcard`
- empty structured entries are omitted automatically: if no personal-name parts remain, `N`/`FN` are not emitted; if no address parts remain, `ADR` is not emitted and the address icon/text block is hidden
- `\cardsetup{key=value,...}`: set layout options at runtime
- `\drawcard[key=value,...]`: draw a card and optionally adjust layout options inline
- `\setoption{key}{value}`: generic runtime setter

### Command-Style Setters for Layout Options

- geometry: `\setpaperwidth`, `\setpaperheight`, `\setcontentwidth`, `\setcontentheight`, `\setpadding`, `\setcutdist`, `\setcutlen`
- layout/typography: `\setfontsize`, `\settextwidth`, `\setqrwidth`, `\setqreclevel`, `\setqrlogoscale`, `\setqrlogoborder`, `\setlogoheight`, `\setlayout`, `\setheaderemphasis`
- booleans (`true`/`false`): `\setcrlf`, `\setaddress`, `\sethint`, `\seticon`, `\setrightalign`, `\seticonleft`, `\setfill`, `\setqrfirst`, `\setheader`, `\setqr`, `\sethttps`
- colors/language/format: `\setlang`, `\setcardcolor`, `\setqrcolor`, `\setcountryformat`, `\setbgscale`, `\setbgopacity`, `\setqrbgopacity`
- convenience toggles: `\noheader`, `\withheader`, `\noqr`, `\withqr`, `\standardlayout`, `\centeredlayout`

### Document Title Interop

- `\title{...}` is repurposed by this class for card position/title content
- `\carddocumenttitle{...}` calls the original LaTeX document-title command if needed


Second Page (Front/Back)
========================

Use one source file for front/back variants:

```latex
\begin{document}
  % Page 1
  \type{home}
  \givennames{John}
  \familynames{Doe}
  \email{name@example.com}
  \drawcard

  % Page 2
  \newcard
  \type{work}
  \company{My\ Company\ LTD}
  \title{CEO}
  \email{doe@mycompany.ltd}
  \drawcard
\end{document}
```

Alternative: centered back side without QR and without header:

```latex
\newcard
\centercontent{{\Large\bfseries My\ Company\ LTD}\par\vspace{0.8em}hello@mycompany.ltd\par mycompany.ltd}
\drawcard[layout=centered,noqr,noheader]
```

Complete working example: [centered-backside-example.tex](examples/centered-backside-example.tex)

Equivalent using setter commands:

```latex
\newcard
\setlayout{centered}
\setqr{false}
\setheader{false}
\centercontent{{\Large\bfseries My\ Company\ LTD}\par\vspace{0.8em}hello@mycompany.ltd\par mycompany.ltd}
\drawcard
```

Header emphasis example:

```latex
\cardsetup{headeremphasis=company}
% or:
\setheaderemphasis{company}
% optional short alias:
\headeremphasis{balanced}
```

If you want to keep most data and only remove selected fields:

```latex
\newpage
\clear{givennames}
\clear{familynames}
\drawcard
```

See [john-doe-hongkong.tex](examples/john-doe-hongkong.tex) for a full two-page example.


Logo and Background Examples
============================

### Logo next to name

```latex
\documentclass{businesscard-qrcode}
\logo{logo.png}
```

### Logo in QR center

```latex
\documentclass[qreclevel=H,qrlogoscale=0.25]{businesscard-qrcode}
\qrlogo[scale=0.25]{logo.png}
```

Important for QR-center logos:

- prefer `qreclevel=H`
- test scan quality with multiple apps/devices
- reduce `qrlogoscale` if decoding becomes unreliable

### Large logo next to name

```latex
\documentclass[logoheight=6em]{businesscard-qrcode}
\logo{logo.png}
```

### Background color

```latex
\documentclass{businesscard-qrcode}
\background{yellow!20}
```

### Background image

```latex
\documentclass[bgscale=1.5,bgopacity=0.3,qrbgopacity=1.0]{businesscard-qrcode}
\background{photo.png}
```


Print the Card
==============

The default print format is `89mm × 59mm` with `2mm` border/cut distance (inner card: `85mm × 55mm`).

Example for `10cm × 5cm` card with `2mm` cut:

```latex
\documentclass[paperheight=5.4cm,paperwidth=10.4cm,
               contentheight=5cm,contentwidth=10cm,
               cutdist=2]{businesscard-qrcode}
```

![example with special paper size](screenshots/special-papersize.png)

Before printing, validate QR readability (phone app + command line, e.g. `zbarimg businesscard.pdf`).


Need More
=========

If you are missing a feature or configuration option, consult [project] and open a [ticket]. Contributions are welcome ([lgpl]).


[examples]: examples "more examples"
[vcard]: https://tools.ietf.org/html/rfc6350 "RFC 6350, vCard Format Specification Version 4.0"
[app]: https://f-droid.org/de/packages/com.google.zxing.client.android/ "Barcode Scanner"
[onlineprinters]: https://de.onlineprinters.ch/k/standardvisitenkarten "onlineprinters.ch"
[mschlenker]: https://gist.github.com/mschlenker/f60e0f15ff1edfc4881c "visitenkarten-qr.tex"
[texstudio_d30266.tex]: examples/texstudio_d30266.tex "simple example source file"
[texstudio_d30266.pdf]: examples/texstudio_d30266.pdf "simple example resulting pdf"
[example.tex]: examples/example.tex "larger example source file"
[example.pdf]: examples/example.pdf "larger example resulting pdf"
[jabber]: https://en.wikipedia.org/wiki/Jabber.org "the Jabber / XMPP instant messaging standard"
[matrix]: https://matrix.org "the matrix instant messaging standard"
[riot]: https://riot.im "matrix compatible instant messaging tool for all platforms"
[gitea]: https://gitea.io "github-like project repository, a gogs clone"
[gogs]: https://gitea.io "github-like project repository"
[github]: https://github.com "a project repository"
[git]: https://git-scm.com "a distributed version control system"
[facebook]: https://facebook.com "a social website"
[twitter]: https://twitter.com "a social website"
[google+]: https://plus.google.com "a social website"
[youtube]: https://youtube.com "a video website"
[wikipedia]: https://wikipedia.org "the online encyclopedia"
[pgp]: https://en.wikipedia.org/wiki/Pretty_Good_Privacy "pretty good privacy — encryption standard"
[nextcloud federation id]: https://nextcloud.com/federation "share your cloud across others"
[I]: https://marc.wäckerlin.ch "Marc Wäckerlin"
[ticket]: https://mrw.sh/templates/businesscard-qrcode/issues "open issues and tickets for my LaTeX-templates project"
[author]: https://marc.wäckerlin.ch "Marc Wäckerlin"
[project]: https://mrw.sh/templates/businesscard-qrcode "the main project page"
[lgpl]: https://www.gnu.org/licenses/lgpl-3.0 "Library GNU Public License"