Marc Wäckerlin
327 lines
20 KiB
Markdown
327 lines
20 KiB
Markdown
Businesscard with QR-Code
|
||
=========================
|
||
|
||
What happens, if you give your visiting card to someone? Either he manually types the text into his computer or mobilefone, or it will end up in a box and be forgotten. Nowadays data is required electronically, not on paper. Here is the solution: A visiting card with QR-Code that contains a full [vcard], so that it can be scanned with an [app] on the mobilefone and therefore automatically imported into the electronic contacts. This also works well, when you are offline and bluetooth transfer fails. So here is the highly configurable businescard or visitingcards with full [vcard] as QR-Code, ready to send to online printers. You can specify the exact size of the paper and the content within the paper, inluding generation of crop marks.
|
||
|
||
Other available visitingcard templates, such as [mschlenker] distribute the cards on an A4 paper. But if you want a professional printer, such as [onlineprinters], then you need to be able to generate a PDF with exactly one card, an exactly defined border and crop marks.
|
||
|
||
[](examples/john-doe-hongkong.tex)
|
||
[](examples/peter-muster-example-company-zuerich.tex)
|
||
[](examples/example.tex)
|
||
|
||
|
||
Features
|
||
========
|
||
|
||
- all information is in the QR-Code
|
||
- full privacy control: input is optional, specify only what you need, you decide what information to share, e.g. I print three cards, with phone and address, without address and only with electronical contacts, no phone nor address
|
||
- optional icons, optional small hint texts
|
||
- several alignments
|
||
- freely defined size of paper and content
|
||
- supports honoric titles, full names, address with post office box and extended information
|
||
- supports telefone, email, [jabber] and [matrix] chat
|
||
- supports several urls for your hompages
|
||
- supports [gitea], [github], [git]
|
||
- supports [facebook], [twitter], [google+], [youtube], [wikipedia]
|
||
- supports [pgp] key url and fingerprint
|
||
- supports [nextcloud federation id]
|
||
|
||
|
||
Usage
|
||
=====
|
||
|
||
Installation
|
||
------------
|
||
|
||
Copy `businesscard-qrcode/businesscard-qrcode.cls` to your LaTeX class path. Simplest way for installation on Linux:
|
||
|
||
```bash
|
||
mkdir ~/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
|
||
------------
|
||
|
||
**Important:** You must use **`xelatex`** for compilation, because `xelatex` properly supports UTF-8 (e.g. needed for german umlauts or chinese characters). The package `inputenc` messes up with package `qrcode`.
|
||
|
||
Note for iOS: vCard content inside the QR now uses CRLF line endings (per spec) to improve import robustness on iOS without changing the vCard version (still 4.0 by default). Also the QR error correction level can be configured.
|
||
|
||
|
||
Document Structure
|
||
------------------
|
||
|
||
```latex
|
||
\documentclass[<layout-options>]{businesscard-qrcode}
|
||
|
||
<data-definitions>
|
||
|
||
\begin{document}
|
||
\drawcard
|
||
\end{document}
|
||
```
|
||
|
||
where `<layout-options>` and `<data-definitions>` are explained below.
|
||
|
||
Escaping Spaces in Data
|
||
-----------------------
|
||
|
||
Whitespace inside `\tag{...}` parameters is ignored by TeX when the data is later passed to the QR encoder. To keep literal spaces in the resulting vCard you *must* escape every space with `\ ` inside each data macro:
|
||
|
||
```latex
|
||
\company{Example\ Company\ Ltd.}
|
||
\city{New\ York}
|
||
\phone{+41\ 44\ 123\ 45\ 67}
|
||
```
|
||
|
||
All examples in this repository follow that convention—when you add your own data, please do the same.
|
||
|
||
|
||
Layout Options
|
||
--------------
|
||
|
||
Layout options are set as options to the `\documentclass`, e.g.:
|
||
|
||
\documentclass[textwidth=0.7,qrwidth=0.25,www,nofill,iconright,rightalign,hint,icon,textfirst]{businesscard-qrcode}
|
||
|
||
### Available Options:
|
||
|
||
- `paperwidth=`: width of the physical paper where the card is printed on (incl. border), default: `89mm`
|
||
- `paperheight=`: height of the physical paper where the card is printed on (incl. border), default: `59mm`
|
||
- `contentwidth=`: width of the card's content without the border that is cut, default: `85mm`
|
||
- `contentheight=`: height of the card's content without the border that is cut, default: `55mm`
|
||
- `fontsize=`: any fontsize allowed in `extarticle`, that are `8pt`, `9pt`, `10pt`, `11pt`, `12pt`, `14pt`, `17pt` and `20pt`, default: `8pt`
|
||
- `padding=`: padding within the card's content, default: `2mm`
|
||
- `cutdist=`: distance in `mm` where the cut marks are set, default: `2`
|
||
- `cutlen=`: length of the cut marks in `mm`, default: `1`
|
||
- `textwidth=`: relative width of the text block `1` means full width, so `qrwidth` plus `textwidth` should be smaller than `1` the remainig space is left empty between the text and QR-Code, default: `0.55` (that's 55% of the available space)
|
||
- `qrwidth=`: relative width of the QR-Code `1` means full width, so `qrwidth` plus `textwidth` should be smaller than `1` the remainig space is left empty between the text and QR-Code, default: `0.40` (that's 40% of the available space)
|
||
- `lang=`: language of the wikipedia page, will be prepended before `wikipedia.org`, e.g. `de.wikipedia.org`, default: `de`
|
||
- `address`or `noaddress`: disable rendering of the address in text and QR-Code, default: address
|
||
- `hint` or `nohint`: show the little text hints, default: `hint`
|
||
- `icon` or `noicon`: show the icons, default: `icon`
|
||
- `rightalign` or `leftalign`: align text left or right, default: `rightalign`
|
||
- `iconleft` or `iconright`: show icon left or right of the text, default: `iconleft`
|
||
- `fill` or `nofill`: fill empty space between icon and text, default: `fill`
|
||
- `qrfirst` or `textfirst`: switch position of QR-Code and text block, default: `qrfirst`
|
||
- `https` or `www`: should links in the hints be prefixed with `https://` or `www.`, default: `https`
|
||
- `countryformat=`: how to format the country in address. Values: `auto` (default: inline with mdash if <4 chars and city/zip exists), `inline` (always inline with mdash), `below` (always separate line)
|
||
- `qreclevel=`: QR error correction level `L` (~7%), `M` (~15%), `Q` (~25%), or `H` (~30%), default: `H`. Use `H` when embedding logo in QR code.
|
||
- `qrlogoscale=`: logo size in QR code as fraction of QR width (1.0 = 100%), default: `0.25` (25% width). Recommended values: Level H: 0.25-0.3, Level Q: 0.2, Level M: 0.15, Level L: 0.1. Higher values may reduce scannability. Can be overridden locally with `\qrlogo[scale=...]{file}`.
|
||
- `qrlogoborder=`: transparent padding around logo in QR code as fraction of QR width (1.0 = 100%), default: `0.02` (2%). Adds space between logo and QR modules.
|
||
- `logoheight=`: logo height next to name with unit (e.g., `4em`, `6em`), default: `4em` if company is set, `2em` otherwise. Can be overridden locally with `\logo[height=...]{file}`.
|
||
- `bgscale=`: background image scale factor (1.0 = 100% of card height), default: `1.0`. Use values like `1.5` or `2.0` for zoomed/cropped backgrounds. Only affects images, not colors. Can be overridden locally with `\background[scale=...]{file}`.
|
||
- `bgopacity=`: background image opacity/transparency (1.0 = 100% visible, 0.0 = invisible), default: `1.0`. Use lower values like `0.2` or `0.3` to fade the background so text remains readable. Only affects images, not colors. Can be overridden locally with `\background[opacity=...]{file}`.
|
||
- `qrbgopacity=`: QR code background opacity (1.0 = solid white, 0.0 = transparent), default: `1.0`. White background behind QR code ensures scannability over background images. Use `0.0` for no background or lower values like `0.8` for semi-transparent. Can be overridden locally with `\qrlogo[opacity=...]{file}`.
|
||
- `color=`: global text color for the entire document, default: `black`. Accepts any color name understood by `xcolor` (including mixes such as `blue!60!black`). Useful when printing on darker backgrounds to ensure legibility without redefining every style manually.
|
||
- `qrcolor=`: QR module color, default: `black`. Set this (e.g., `qrcolor=darkred`) to recolor the QR code independently from the main text color while keeping sufficient contrast with the background.
|
||
|
||
|
||
Data Definitions
|
||
----------------
|
||
|
||
Your data is entered with commands in the document, e.g.:
|
||
|
||
\email{name@example.com}
|
||
|
||
**Important:** Spaces *must* be escaped by a backslash `\` in all data definitions, otherwise the QR payload will silently drop them. Always write `\company{Example\ Company\ Ltd.}` or `\phone{+41\ 52\ 123\ 45\ 67}`.
|
||
|
||
All data commands accept an optional `[hide]` (or `[hide=true]`) argument. When `hide` is set the value is stored in the QR/vCard only and omitted from the human readable text. Example: `\email[hide]{secret@example.com}` keeps the address available for scanners but off the printed card.
|
||
|
||
See this example:
|
||
|
||
\givennames{Juan\ Pablo}
|
||
\familynames{Martínez\ Escudero}
|
||
\company{Example\ Company\ Ltd.}
|
||
\street{Im\ Stutz\ 123}
|
||
\pobox{Postfach\ 4567}
|
||
\phone{+41\ 52\ 123\ 45\ 67}
|
||
\pgpurl{https://pgp.mit.edu/pks/lookup?op=get\&search=0xF62315D04D4C0C62}
|
||
|
||
### Recognized Commands:
|
||
|
||
- `\type`: either `home` or `work` for personal or business cards
|
||
- `\givennames`: your first name and eventual middle names
|
||
- `\familynames`: your family names
|
||
- `\honoricprefix`: honorix name prefixes, e.g. academic titles
|
||
- `\honoricsuffix`: honoric name suffixes
|
||
- `\company[logo=...,height=...,hide]`: company name — always rendered on a second line underneath the personal name. `logo=` may contain either a filename or arbitrary TeX content (e.g. a custom macro); when present, it is shown first, followed by the textual company/title/role string (if visible). `height` (default `1.5em`) controls the logo's size **and** the reserved vertical space for that second line, so adapting the height keeps the layout balanced. Even when `hide` is set, the company still appears in the QR/vCard, and the logo remains visible.
|
||
- `\pobox`: post office box
|
||
- `\extaddr`: address extension, e.g. name of a building or floor number
|
||
- `\street`: street and number of the address
|
||
- `\city`: name of the address location
|
||
- `\region`: region of the address
|
||
- `\zip`: zip code of the address
|
||
- `\country`: full name of country of the address in the language of the card (short codes like `CH`, `USA`, `D` are automatically placed inline with mdash before city/zip, longer names on separate line)
|
||
- `\phone`: your phone number, the phone is marked as mobile, so to be used for voice and text (SMS)
|
||
- `\email`: your email address
|
||
- `\jabber`: your [jabber] or xmpp chat address
|
||
- `\matrixorg`: your [matrix] chat addres, hint: use [riot] messenger for [matrix]
|
||
- `\cloud`: your [nextcloud federation id] — the url is prepended automatically
|
||
- `\homepage`: url to a web site with «home» icon — without `https://` not `www` (unless it is required), this is prepended automatically
|
||
- `\world`: url to a web site with «world» icon — without `https://` not `www` (unless it is required), this is prepended automatically
|
||
- `\link`: url to a web site with «link» icon — without `https://` not `www` (unless it is required), this is prepended automatically
|
||
- `\wordpress`: url to a web site with «wordpress» icon — without `https://` not `www` (unless it is required), this is prepended automatically
|
||
- `\drupal`: url to a web site with «» icon — without `https://` not `www` (unless it is required), this is prepended automatically
|
||
- `\joomla`: url to a web site with «joomla» icon — without `https://` not `www` (unless it is required), this is prepended automatically
|
||
- `\wikipedia`: if you or your company have a [wikipedia] entry, specify documentclass option `lang` for the language of you entry and use this definition for the name of your page — the url is prepended automatically
|
||
- `\git`: the url of your [git] repository — without `https://` not `www` (unless it is required), this is prepended automatically
|
||
- `\gitea`: the url of your [gitea] project page, you can use this tag also for other project management sites, such as [gogs] — without `https://` not `www` (unless it is required), this is prepended automatically
|
||
- `\github`: your account name on [github] — only the name of the account, the url is prepended automatically
|
||
- `\facebook`: your account name on [facebook] or the name of your page — only the name of the account or page, the url is prepended automatically
|
||
- `\twitter`: your account name on [twitter] — only the name of the account, the url is prepended automatically
|
||
- `\youtube`: your account name on [youtube] — only the name of the account, the url is prepended automatically
|
||
- `\google`: your account name on [google+] — only the name of the account, the url is prepended automatically
|
||
- `\pgpurl`: the full url to your pgp public key (only added to the QR-Code, not shown in the text)
|
||
- `\pgpfingerprint`: the fingerprint of your pgp public key
|
||
- `\logo[height=...]{content}`: supply either a path to an image file (PNG, JPG, PDF, …) or arbitrary LaTeX content (e.g., `\Pacta`). When a readable file exists it is loaded via `\includegraphics`; otherwise the content is typeset as provided. Optional `height` parameter (e.g., `height=6em`) overrides the global `logoheight` option.
|
||
- `\qrlogo[scale=...,opacity=...]{content}`: behaves like `\logo`, but places the content in the center of the QR code. Pass an image path or LaTeX markup. Optional parameters: `scale` (fraction like `0.3` for 30% of QR width) overrides `qrlogoscale`, `opacity` (0.0-1.0) overrides `qrbgopacity`. Remember that every logo lowers the QR-code's error-correction margin—keep the scale conservative and always test the code with multiple devices (smartphones plus command-line tools such as `zbarimg`).
|
||
- `\companylogo[height=...]{content}`: backwards-compatible helper that still allows arbitrary content below the name. Prefer the new `\company[logo=...]{...}` syntax, but this command remains available.
|
||
- `\background[scale=...,opacity=...]{file/color}`: path to background image file or color name (e.g., `yellow!20`, `blue!10`). If file exists, it's used as image; otherwise treated as color. Optional parameters: `scale` (factor like `1.5`) overrides `bgscale`, `opacity` (0.0-1.0) overrides `bgopacity`.
|
||
|
||
|
||
Print the Card
|
||
==============
|
||
|
||
The card is designed for professional printing service, such as [onlineprinters]. Please *check* the card and the *QR-Code* well before you pay money for printing! Scan the QR with at least one smartphone app **and** a decoder such as `zbarimg businesscard.pdf` on Linux to make sure the payload survives background images, logos in the QR code, etc.
|
||
|
||
Choose a format, default is `89mm×59mm` with 2mm boder, so the card content is `85mm×55mm`. But the card can be adapted to any other printing format. To print cards of size `10cm×5cm` with `2mm` cut, you specify, [e.g.](examples/special-papersize.tex):
|
||
|
||
\documentclass[paperheight=5.4cm,paperwidth=10.4cm,
|
||
contentheight=5cm,contentwidth=10cm,
|
||
cutdist=2]
|
||
{businesscard-qrcode}
|
||
|
||
|
||
|
||
|
||
Usage Example
|
||
=============
|
||
|
||
Include the documentclass, define your data and add the document environment:
|
||
|
||
```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}
|
||
```
|
||
|
||
Save it as file [texstudio_d30266.tex] and compile it to get [texstudio_d30266.pdf]:
|
||
|
||
xelatex -synctex=1 -interaction=nonstopmode texstudio_d30266.tex
|
||
|
||
|
||
|
||
See [examples] for more examples.
|
||
|
||
### Building with latexmk / IDEs
|
||
|
||
Editors such as VS Code’s LaTeX Workshop usually call `latexmk` from the
|
||
workspace root. The repository now ships a project-local `.latexmkrc`
|
||
(and `examples/.latexmkrc`) that extend `TEXINPUTS` so TeX always prefers
|
||
the class file from this checkout over anything installed under
|
||
`~/texmf`. Leave those files in place when compiling from your IDE.
|
||
If you invoke `xelatex` manually without `latexmk`, set
|
||
`TEXINPUTS=/path/to/businesscard-qrcode:` (or run the command from the
|
||
repository root) to achieve the same effect.
|
||
|
||
Logo (optional)
|
||
===============
|
||
|
||
You can add an optional logo that appears next to the name or in the center of the QR code. The logo is dynamically scaled to match the name line height (when next to name) or to 25% of the QR code width (when in QR).
|
||
|
||
```latex
|
||
\logo{path/to/logo.png}
|
||
```
|
||
|
||
### Logo Placement Options:
|
||
|
||
**Default (logo next to name):**
|
||
```latex
|
||
\documentclass{businesscard-qrcode}
|
||
\logo{logo.png}
|
||
```
|
||
|
||
**Logo in QR code center:**
|
||
```latex
|
||
\documentclass[logoinqr,qreclevel=H,qrlogoscale=0.25]{businesscard-qrcode}
|
||
\logo{logo.png}
|
||
```
|
||
|
||
**Important:** When using `logoinqr=true`:
|
||
- Always use `qreclevel=H` (highest error correction ~30%) for reliable scanning
|
||
- Test QR code scannability with multiple apps before printing
|
||
- Default `qrlogoscale=0.25` (25% width = 6.25% area) is recommended for Level H
|
||
- If scanning fails, reduce to `qrlogoscale=0.2` or `qrlogoscale=0.15`
|
||
- PNG transparency is preserved - use images with transparent backgrounds for best results
|
||
|
||
**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}
|
||
```
|
||
Note: Use `bgopacity` to fade the background (e.g., `0.2` or `0.3`) so text remains readable. The QR code has a white background by default (`qrbgopacity=1.0`) to ensure scannability.
|
||
|
||
|
||
Need More
|
||
=========
|
||
|
||
If you are missing a feature or a configuration option, consult the [project] page. Just open a [ticket] and the [author] will care about it. Or extend it, it's [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"
|