Working version

2026-07-02 00:38:01 +02:00
parent 75ab49751f
commit eca60fef9f
7 changed files with 325 additions and 1 deletions
@@ -1,2 +1,120 @@
+# foldable-namecard

-This repo contains a quick and easy style file for creating foldable name cards from a CVS input file.
+A LaTeX package for printing A4 foldable namecards with a name, country, and logo.
+
+## Requirements
+
+### Compiler
+
+**This package requires XeLaTeX.** It will produce a hard error and abort if compiled
+with `pdflatex` or `lualatex`. The package uses `fontspec` and `xeCJK` for advanced font handling, which are only fully supported by XeLaTeX.
+
+Compile with:
+
+```
+xelatex example.tex
+```
+
+### LaTeX Packages
+
+The following packages are required (most are part of a standard TeX Live or MiKTeX installation):
+
+- `geometry` - Page layout
+- `graphicx` - Image handling
+- `keyval` - Key-value options
+- `iftex` - Conditional compilation based on engine
+- `tikz` and `pgf` - Drawing and positioning
+- `xcolor` - Color support
+- `fontspec` - Font configuration (XeTeX)
+- `xeCJK` - CJK character support (for Chinese, Japanese, Korean)
+
+### System Fonts
+
+You must install the following fonts on your system:
+
+| Font | Purpose | Notes |
+|------|---------|-------|
+| **Hind** | Primary font for names and text | Download from [Google Fonts](https://fonts.google.com/specimen/Hind) |
+| **Liberation Sans** or **DejaVu Sans** | Fallback for extended Latin characters (accents, diacritics like ǐ) | Usually pre-installed on Linux/macOS; use one if Hind lacks certain glyphs |
+| **Noto Sans CJK SC** (or system CJK font) | Chinese character support | For rendering Chinese names |
+
+#### Installation Instructions
+
+**macOS:**
+```bash
+# Download Hind from Google Fonts, then:
+cp ~/Downloads/Hind-*.otf ~/Library/Fonts/
+```
+
+**Linux (Ubuntu/Debian):**
+```bash
+# Install system fonts
+sudo apt-get install fonts-hind fonts-dejavu fonts-noto-cjk
+
+# Or manually copy to ~/.fonts/ and run:
+fc-cache -fv
+```
+
+**Windows:**
+```
+# Download Hind from Google Fonts
+# Right-click .otf files → Install
+```
+
+If any font is missing, the package will attempt to use fallbacks or emit a warning.
+
+## Usage
+
+### Single card
+
+```latex
+\documentclass{article}
+\usepackage{foldable-namecard}
+
+\namecardsetup{
+  name=Alex Johnson,
+  country=Sweden,
+  logo=mylogo.png
+}
+
+\begin{document}
+\makefoldablenamecard
+\end{document}
+```
+
+### Batch printing from a CSV file
+
+```latex
+\documentclass{article}
+\usepackage{foldable-namecard}
+
+\namecardsetup{logo=mylogo.png}
+
+\begin{document}
+\makefoldablenamecardsfromfile{names.csv}
+\end{document}
+```
+
+The CSV file must contain one `name,country` pair per line. Blank lines are skipped.
+The package supports international characters including accented Latin letters and Chinese characters.
+
+```
+Alex Johnson,Sweden
+Mina Patel,India
+Sofia Garcia,Spain
+Valgerður Ólafsdóttir,Iceland
+李明 (Lǐ Míng),China
+王芳,中国
+```
+
+## Options (`\namecardsetup`)
+
+| Key            | Default      | Description                              |
+|----------------|--------------|------------------------------------------|
+| `name`         | `Your Name`  | Name printed on the card                 |
+| `country`      | `Country`    | Country printed below the name           |
+| `logo`         | *(none)*     | Path to logo image file                  |
+| `logowidth`    | `2cm`        | Width of the logo                        |
+| `logoheight`   | `10mm`       | Height constraint for the logo           |
+| `debugboxes`   | *(on)*       | Show bounding boxes for layout debugging |
+| `nodebugboxes` | —            | Hide bounding boxes                      |