A document at the root of a checkout of 68377 folders needed 56 minutes, because the converter named the suite, the document folder and the build folder with `//` in TEXINPUTS; it now names them without recursion and the same document converts in 11.5 seconds. A file below the document no longer replaces a package of TeX Live. The security review of the pending changes found four defects, each fixed with a test proven red against the old files and green against the new ones twice: an HTML table read in an empty sandbox, so an iframe opens no address; form labels written through the LaTeX writer, so they are set as text; the form pattern scans a line once instead of quadratically; a kept build folder no longer lays the links of an earlier drawing over a new one. The form tests remove the PDF of an earlier run before each conversion. Also carried: forms out of Markdown, link colours from the company, clickable links in prose, HTML tables and SVG drawings, the watermark, and the further changes of 1.0.1 and 1.0.2 in the CHANGELOG. npm test: 1232 of 1232 checks. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
630 lines
26 KiB
Markdown
630 lines
26 KiB
Markdown
# Business Suite
|
|
|
|
Business Suite provides shared LaTeX templates for reports, letters and Beamer presentations. A single company package defines the corporate identity—colours, fonts, logo and contact details—and all templates use that configuration.
|
|
|
|
The suite contains no company-specific colour values, font names or asset paths. Corporate identities therefore remain private while the reusable templates can be published and tested independently.
|
|
|
|
## Components
|
|
|
|
| Component | Purpose |
|
|
| --- | --- |
|
|
| `business-identity.sty` | Defines colours, fonts, logos and shared commands |
|
|
| `business-suite.sty` | Formats reports and other standard LaTeX documents |
|
|
| `business-brief.cls` | Provides business letters based on `g-brief2` |
|
|
| `business-beamer.sty` | Provides the shared Beamer presentation design |
|
|
| `md2pdf.py` | Converts Markdown to a branded PDF through Pandoc and XeLaTeX |
|
|
|
|
## Requirements
|
|
|
|
- A LaTeX installation with XeLaTeX
|
|
- Pandoc and Python 3 for Markdown conversion
|
|
- Inkscape when a document contains SVG images
|
|
|
|
Company-specific fonts and packages must also be available to XeLaTeX.
|
|
|
|
## Quick Start
|
|
|
|
### Install the Suite
|
|
|
|
Link the suite and converter into the local TeX and executable trees. Symbolic links keep the installation aligned with the working copy.
|
|
|
|
```bash
|
|
mkdir -p ~/texmf/tex/latex ~/bin
|
|
ln -s ~/git/mrw/business-suite/texmf/tex/latex/business-suite \
|
|
~/texmf/tex/latex/business-suite
|
|
ln -s ~/git/mrw/business-suite/bin/md2pdf.py ~/bin/md2pdf.py
|
|
```
|
|
|
|
Install a company identity in the same way:
|
|
|
|
```bash
|
|
ln -s ~/git/nordwind/latex ~/texmf/tex/latex/nordwind
|
|
```
|
|
|
|
For builds that must not depend on the local installation, set `TEXINPUTS` to the source tree. The npm scripts in this repository do this automatically.
|
|
|
|
### Create a Company Identity
|
|
|
|
Each company has one package, such as `nordwind.sty`. It defines the palette, maps colours to semantic roles, configures the fonts and registers the logo before loading the document template.
|
|
|
|
```latex
|
|
\NeedsTeXFormat{LaTeX2e}
|
|
\ProvidesPackage{nordwind}[2026/09/21 Nordwind AG corporate identity]
|
|
|
|
\RequirePackage{business-identity}
|
|
|
|
\definecolor{nordwind-deep}{HTML}{14425C}
|
|
\definecolor{nordwind-sea}{HTML}{3E8EA8}
|
|
|
|
\businesscolours{
|
|
brand = nordwind-deep,
|
|
title = nordwind-deep,
|
|
titlemeta = nordwind-deep!60,
|
|
text = black,
|
|
running-strong = nordwind-deep,
|
|
running-quiet = nordwind-deep!55,
|
|
folio = nordwind-deep!55,
|
|
caption = nordwind-deep!70,
|
|
rowrule = nordwind-deep!25,
|
|
heading-bg = nordwind-deep,
|
|
heading-fg = white,
|
|
border = nordwind-sea,
|
|
thick-border = nordwind-deep,
|
|
black-border = black,
|
|
}
|
|
|
|
\setmainfont{TeX Gyre Pagella}
|
|
\setsansfont{TeX Gyre Heros}
|
|
\setmonofont{TeX Gyre Cursor}[Scale=MatchLowercase]
|
|
|
|
\businessfonts{
|
|
default = rm,
|
|
symbols = DejaVu Sans,
|
|
smallcaps = false,
|
|
}
|
|
|
|
\businessidentity{
|
|
name = Nordwind,
|
|
url = https\://nordwind.example,
|
|
address = https\://nordwind.example,
|
|
lockup = icon+text,
|
|
icon = nordwind-icon,
|
|
}
|
|
|
|
\DeclareOption*{\PassOptionsToPackage{\CurrentOption}{business-suite}}
|
|
\ProcessOptions\relax
|
|
\RequirePackage{business-suite}
|
|
|
|
\endinput
|
|
```
|
|
|
|
### Create a Document
|
|
|
|
Load the company package instead of the generic template:
|
|
|
|
```latex
|
|
\documentclass[a4paper,10pt]{article}
|
|
\usepackage{nordwind}
|
|
|
|
\title{Annual Report}
|
|
\author{Erika Muster}
|
|
\date{\today}
|
|
|
|
\begin{document}
|
|
\maketitle
|
|
|
|
\section{Current Position}
|
|
Dolor sit amet.
|
|
|
|
\end{document}
|
|
```
|
|
|
|
The template automatically applies the corporate logo, page header, footer, title block, heading rules, table widths, image sizing, PDF outline and PDF metadata.
|
|
|
|
### Convert Markdown
|
|
|
|
```bash
|
|
md2pdf.py --identity nordwind report.md
|
|
```
|
|
|
|
The equivalent npm command is:
|
|
|
|
```bash
|
|
npm run md2pdf -- --identity nordwind report.md
|
|
```
|
|
|
|
To provide a company-specific command, add a wrapper to the `PATH`:
|
|
|
|
```sh
|
|
#!/bin/sh
|
|
exec md2pdf.py --identity nordwind "$@"
|
|
```
|
|
|
|
## Corporate Identity
|
|
|
|
### Colour Roles
|
|
|
|
Company packages define concrete colours and assign them to semantic roles. Templates use only these roles.
|
|
|
|
| Role | Usage |
|
|
| --- | --- |
|
|
| `brand` | Logo and primary accents |
|
|
| `text` | Body text |
|
|
| `title` | Document title |
|
|
| `titlemeta` | Author and date |
|
|
| `running-strong` | First line of the running header |
|
|
| `running-quiet` | Second line of the running header |
|
|
| `folio` | Page number |
|
|
| `caption` | Image captions |
|
|
| `rowrule` | Table row separators |
|
|
| `success`, `fail` | Status marks |
|
|
| `heading-bg`, `heading-fg` | Heading bands and presentation bars |
|
|
| `border`, `thick-border`, `black-border` | Document frames |
|
|
| `canvas-top`, `canvas-bottom`, `canvas-text` | Ground of a slide from top to bottom, and the text on it; white and the `text` colour when omitted |
|
|
| `sidebar-top`, `sidebar-bottom` | Sidebar of a deck from top to bottom; the `brand` colour when omitted |
|
|
|
|
A role can reference a palette colour directly or use an `xcolor` mixture such as `nordwind-deep!50!black`. The `success` and `fail` roles default to green and red and do not have to be part of the company palette.
|
|
|
|
### Font Settings
|
|
|
|
The company package loads and configures `fontspec`; `\businessfonts` tells the templates how to use the configured families.
|
|
|
|
| Key | Meaning |
|
|
| --- | --- |
|
|
| `default` | Default document family: `rm` or `sf` |
|
|
| `emphasis` | Face used for emphasis; defaults to bold when omitted |
|
|
| `symbols` | Fallback family for missing symbols |
|
|
| `smallcaps` | Set to `false` if the selected font has no small capitals |
|
|
| `microtype` | Set to `false` to disable microtypography |
|
|
| `protrusion` | Set to `true` to allow punctuation to extend into the margin |
|
|
|
|
The font encoding remains associated with the selected family. This prevents a class that preselects a family using T1 encoding from silently falling back to Computer Modern.
|
|
|
|
### Logo Configuration
|
|
|
|
The identity can reference an image file or a drawing command:
|
|
|
|
```latex
|
|
\businessidentity{logo = company-logo}
|
|
\businessidentity{icon code = \companydrawing}
|
|
```
|
|
|
|
Image filenames omit the extension. The suite checks PDF, EPS, PNG and JPEG in that order. A logo that exists as an SVG gets a PDF of the same name beside it, once and again after every change to the drawing:
|
|
|
|
```bash
|
|
python3 bin/logo.py <directory of the identity>
|
|
python3 bin/logo.py --check <directory of the identity>
|
|
```
|
|
|
|
`--check` names every PDF that is missing or older than its SVG and fails, so a company build can ask it first. A logo that exists as an SVG alone stops the LaTeX build with that command in the error message.
|
|
|
|
A drawing command receives the requested height and must produce a box of exactly that height. TikZ drawings should freeze their bounding box with `\pgfresetboundingbox` and an explicit `\path[use as bounding box]`. The selected logo colour is available as `\businesslogocolour`.
|
|
|
|
The `lockup` setting defines the logo structure:
|
|
|
|
- `banner`: the asset already contains the icon and company name.
|
|
- `icon+text`: the suite places the company name beside the icon.
|
|
|
|
With a `banner` lockup, the tagline appears below the complete banner and aligns with its right edge.
|
|
|
|
### Tagline
|
|
|
|
Add a second line below the company name with `tagline`:
|
|
|
|
```latex
|
|
\businessidentity{
|
|
name = Nordwind,
|
|
tagline = Vernunft und Freiheit,
|
|
}
|
|
```
|
|
|
|
The following optional keys change the default appearance:
|
|
|
|
```latex
|
|
\businessidentity{
|
|
name face = {\bfseries},
|
|
tagline face = {\mdseries},
|
|
tagline color = business-running-quiet,
|
|
}
|
|
```
|
|
|
|
The name is 80% of the requested logo height. The tagline is set to the size at which it is exactly as wide as the name above it, so both lines share one left edge and one right edge whatever the sentence says. The gap between them is 20% of the name size and `taglinegap` changes it.
|
|
|
|
The icon takes the height of the text block beside it and keeps the proportions of its own drawing. A mark with a height of its own matches the text at one type size and at no other.
|
|
|
|
Each measured size has a key that overrides it:
|
|
|
|
| Key | Overrides |
|
|
| --- | --- |
|
|
| `taglinefactor` | the tagline size, as a share of the name instead of its width |
|
|
| `iconheight` | the icon height, instead of the height of the text block |
|
|
| `iconwidth` | the icon width; the height follows from the drawing |
|
|
|
|
Never give both icon sizes at once: two fixed sizes distort the mark. A width also reaches a drawn icon, not only an image file. The suite sets the icon once, measures its width and scales the height by the ratio.
|
|
|
|
Templates request the tagline where sufficient space is available. Logos in running text remain on one line unless `tagline` is explicitly requested.
|
|
|
|
## Shared Commands
|
|
|
|
### Logos
|
|
|
|
```latex
|
|
\logo
|
|
\logo[height=2cm]
|
|
\logo[address]
|
|
\logo[icon]
|
|
\logo[text]
|
|
\logo[nolink]
|
|
\logo[color=business-text]
|
|
\logo[tagline]
|
|
\logo[tagline,address]
|
|
```
|
|
|
|
Use `\businesslogo` where another package owns `\logo`; Beamer, for example, uses `\logo` to set the presentation logo.
|
|
|
|
By default, logos are 1.25 em high in running text and 2 em high in template headers. The company name is 80% of the logo height. Gaps beside the icon and above the address are 10% of the logo height. Each value can be overridden.
|
|
|
|
The address line is scaled to the exact width of the logo or lockup above it. The icon is vertically centred beside the name while the name retains the surrounding text baseline.
|
|
|
|
### Status Marks
|
|
|
|
`\success` and `\fail` render white status symbols on green and red backgrounds. The Unicode characters `✅`, `❌`, `✓`, `✗`, `✔` and `✘` map to the same marks, which allows Markdown sources to use them directly.
|
|
|
|
Other common symbols—including arrows, information signs, warnings, stars and checkboxes—use the active text font when available and the configured symbol family otherwise. Unsupported characters are omitted without adding a gap or log message.
|
|
|
|
### Images
|
|
|
|
Use `\businessgraphic` for template-controlled image sizing:
|
|
|
|
```latex
|
|
\businessgraphic{diagram}
|
|
\businessgraphic[width=4cm]{diagram}
|
|
```
|
|
|
|
Default sizing depends on orientation:
|
|
|
|
- Portrait images use up to the full line width and half the text height.
|
|
- Landscape images use up to the full line width and the free height remaining on the page.
|
|
- Images retain their aspect ratio and are centred.
|
|
- If an image would leave no more than 25% of a page empty, it moves to the next page. Otherwise, it is reduced to fit the current page.
|
|
- Vector graphics may use the full calculated size. Raster images are enlarged by at most a factor of two.
|
|
|
|
| Option | Default | Meaning |
|
|
| --- | ---: | --- |
|
|
| `portraitwidth` | `1` | Maximum share of the line width for portrait images |
|
|
| `portraitheight` | `0.5` | Maximum share of the text height for portrait images |
|
|
| `landscapewidth` | `1` | Maximum share of the line width for landscape images |
|
|
| `landscapeheight` | `1` | Maximum share of the remaining page height |
|
|
| `pictureempty` | `0.25` | Maximum empty page share before an image is reduced |
|
|
| `picturezoom` | `2` | Maximum enlargement factor for raster images |
|
|
|
|
Markdown conversion applies these rules automatically.
|
|
|
|
### Footer Content
|
|
|
|
The outer footer shows the current page and total page count. Add optional content to the inner footer in the preamble:
|
|
|
|
```latex
|
|
\businessfootleft{\includegraphics[height=2em]{product}}
|
|
```
|
|
|
|
The footer may contain a product logo, classification or series name. Its reserved height is measured from the rendered content. Define it before `\begin{document}` because page geometry cannot be recalculated afterwards.
|
|
|
|
### Columns
|
|
|
|
`businesscolumns` creates equal-width columns. Their widths follow from the current line width, and the gap between columns equals one body-text line.
|
|
|
|
```latex
|
|
\begin{businesscolumns}[3]
|
|
\businesscell{First}
|
|
\businesscell{Second}
|
|
\businesscell{Third}
|
|
\end{businesscolumns}
|
|
```
|
|
|
|
Use `\businessuse{<name>}` to include a reusable block from the TeX tree, such as a sender block or terms page.
|
|
|
|
### Tables
|
|
|
|
Use standard LaTeX table environments with the shared table commands:
|
|
|
|
```latex
|
|
\begin{tabular}{lr}
|
|
\toprule
|
|
\businesstablehead{Figure} & \businesstablehead{Value} \\
|
|
\midrule
|
|
Turnover & 4.2 million \\ \businessrowrule
|
|
People & 31 \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
```
|
|
|
|
- `\businesstablehead{...}` formats a header cell.
|
|
- `\businessrowrule` draws the separator between rows in the `rowrule` colour.
|
|
- The other rules of a table are drawn in the `text` colour of the company.
|
|
|
|
Keep an introductory sentence with the following table or list using:
|
|
|
|
```latex
|
|
\businessleadin[2]
|
|
The annual figures:
|
|
\businesstogether
|
|
```
|
|
|
|
The optional argument specifies the number of lines occupied by the introduction. The default is six. The Markdown converter inserts both commands where required.
|
|
|
|
### Watermark
|
|
|
|
A page that is not final carries one word across it:
|
|
|
|
```latex
|
|
\usepackage[draft]{company} % the word DRAFT
|
|
\usepackage[watermark=ENTWURF]{company}
|
|
```
|
|
|
|
or, from the preamble of a single document, letter or deck:
|
|
|
|
```latex
|
|
\businesswatermark{CONFIDENTIAL}
|
|
```
|
|
|
|
The word is set in the `watermark` colour role, `black!8` unless the company sets it, and laid along the diagonal of the paper at the largest size that sheet carries. Short and long words therefore both stay on the page, in every paper size and orientation. The identity provides it, so a letter class and a presentation theme carry it as a document does.
|
|
|
|
### Links
|
|
|
|
A link takes the appearance the company gives it, so that a PDF and the website of that company read alike:
|
|
|
|
```latex
|
|
\businesscolours{link = company-red, link-external = company-red}
|
|
\businesslinks{colour = link, external = link-external, underline = true}
|
|
```
|
|
|
|
- `colour` names the role a link inside the document stands in, `external` the role for an address that leaves it; both default to the `text` role, which leaves a link read and not seen.
|
|
- `underline` draws the line a browser draws by default. It applies to `\href` and `\hyperref`; `\url` keeps its verbatim shape. The line is drawn by `ulem`, which the suite loads only for a company that asks for it: a build environment that sets `underline = true` carries the TeX Live package `texlive-plain-generic`.
|
|
- A PDF carries no state: there is no hover and no visited colour on paper, so a stylesheet's `a:hover` and `a:visited` have no counterpart here.
|
|
- A company that calls neither command keeps links in the colour of the text and without a frame.
|
|
|
|
Links drawn inside an SVG keep their destination: the converter reads the `href` areas of the drawing and lays them over the converted picture as annotations, so a link in a PlantUML diagram reaches its definition in the finished PDF.
|
|
|
|
### Forms
|
|
|
|
A document whose reader has to answer carries form fields: the reader ticks boxes, types entries of any length and saves the filled file. Declare the form in the preamble, then use the three field commands:
|
|
|
|
```latex
|
|
\usepackage{company}
|
|
\businessform
|
|
|
|
\begin{document}
|
|
\businesscheckbox{S1}{\textbf{S1 Scope.} The scope is as described.}
|
|
\businessremark{S1-remarks}{Remarks}{3}
|
|
\businessline{Name}{Name}
|
|
\end{document}
|
|
```
|
|
|
|
- `\businessform` opens the form around the document body. Without it a document carries no form dictionary.
|
|
- `\businesscheckbox[<keys>]{<name>}{<text>}` sets a checkbox with its text beside it; `checked=true` delivers it ticked.
|
|
- `\businessremark{<name>}{<label>}{<lines>}` sets a field of the given height in lines, with its label above it.
|
|
- `\businessline{<name>}{<label>}` sets a field beside its label, for a signature block.
|
|
|
|
Every text field accepts several lines and has no length limit, so an entry longer than the field scrolls. The first argument is the field name in the PDF; it has to be unique within the document.
|
|
|
|
#### Forms in Markdown
|
|
|
|
The converter builds the same fields from two shapes that GitHub, GitLab and Gitea already render, so the source stays readable where it is read:
|
|
|
|
```markdown
|
|
- [ ] **S1 Scope.** The scope is as described.
|
|
|
|
Remarks: ________________________________
|
|
|
|
Name: ________________________________
|
|
```
|
|
|
|
- A task list item becomes a checkbox, named after the identifier in its bold lead-in (`S1`). An item without one is named after its position (`q1`, `q2`). `- [x]` delivers the box ticked.
|
|
- A paragraph consisting of a label, a colon and three or more underscores becomes a text field. Inside a list item it is named after that item (`S1-remarks`) and takes three lines; alone between two headings it takes six; anywhere else it is a single line beside its label.
|
|
- A row of underscores without a label stays what every platform makes of it: a horizontal rule.
|
|
- A document containing neither shape is converted exactly as before.
|
|
|
|
The appearance font of the fields is Helvetica, one of the fourteen standard PDF fonts; the page around them uses the company font.
|
|
|
|
## Document Layout
|
|
|
|
### Header and Footer
|
|
|
|
The first page shows the corporate logo and address. Subsequent pages use two running-header lines and display the current and total page count in the footer.
|
|
|
|
The suite measures the actual header and footer content. It leaves one body-text line between the header and text area and the same distance between the text area and footer. The `headsep` option changes the upper distance; the lower distance is derived from it.
|
|
|
|
### Page Composition
|
|
|
|
The first text line begins at the upper edge of the text block. Paragraph spacing may stretch by up to half a line so that pages end on a consistent baseline. The `pagestretch` option controls this flexibility.
|
|
|
|
Headings remain attached to their following content. Tables and images use the current line width and available page height instead of fixed dimensions from a particular company design.
|
|
|
|
## Business Letters
|
|
|
|
`business-brief.cls` extends `g-brief2` with the corporate identity and shared logo handling. Create a company-specific class:
|
|
|
|
```latex
|
|
\NeedsTeXFormat{LaTeX2e}
|
|
\ProvidesClass{nordwind-brief}[2026/09/21]
|
|
|
|
\DeclareOption*{\PassOptionsToClass{\CurrentOption}{business-brief}}
|
|
\ProcessOptions\relax
|
|
\LoadClass{business-brief}
|
|
\RequirePackage[plain]{nordwind}
|
|
|
|
\RetourAdresse{Nordwind~AG~-~Hafenstrasse~4~-~8000~Zürich}
|
|
\NameZeileA{Nordwind AG}
|
|
\NameZeileB{Hafenstrasse 4}
|
|
\NameZeileC{CH~--~8000 Zürich}
|
|
\InternetZeileA{https\://nordwind.example}
|
|
\InternetZeileB{post\@nordwind.example}
|
|
\BankZeileA{CH00 0000 0000 0000 0000 0}
|
|
\Gruss{Mit freundlichen Grüssen}{2em}
|
|
|
|
\endinput
|
|
```
|
|
|
|
The class preserves the existing `g-brief2` field names. It adds:
|
|
|
|
| Command | Purpose |
|
|
| --- | --- |
|
|
| `\Unterschriftsbild{<file>}{<name>}` | Inserts a printed signature instead of reserving space for a handwritten one |
|
|
| `\businessnowindow` | Removes the envelope window, folding marks and return line, then reduces the address field to the current address height |
|
|
| `\businesslogoheight` | Sets the header logo height, capped at the available 20 mm |
|
|
|
|
The first page places the logo and address above the sender block. Later pages place the page number and date on the left and the logo on the right.
|
|
|
|
Example:
|
|
|
|
```latex
|
|
\documentclass[english]{nordwind-brief}
|
|
|
|
\Datum{\today}
|
|
\Adresse{Ms\\Erika Muster\\Beispielweg 7\\8001 Zurich}
|
|
\Betreff{Our offer for the harbour}
|
|
\Anrede{Dear Ms Muster}
|
|
\Unterschrift{Hans Beispiel\\Managing Director}
|
|
|
|
\begin{document}
|
|
\begin{g-brief}
|
|
We are pleased to send you our offer.
|
|
\end{g-brief}
|
|
\end{document}
|
|
```
|
|
|
|
## Presentations
|
|
|
|
Create a two-line company theme:
|
|
|
|
```latex
|
|
% beamerthemenordwind.sty
|
|
\RequirePackage[plain]{nordwind}
|
|
\RequirePackage{business-beamer}
|
|
```
|
|
|
|
Load it from a presentation with `\usetheme{nordwind}`:
|
|
|
|
```latex
|
|
\documentclass[12pt]{beamer}
|
|
\usetheme{nordwind}
|
|
|
|
\title{The Harbour}
|
|
\author{Hans Beispiel}
|
|
\date{\today}
|
|
|
|
\begin{document}
|
|
\begin{frame}[plain]
|
|
\titlepage
|
|
\end{frame}
|
|
|
|
\section{Current Position}
|
|
|
|
\begin{frame}
|
|
\frametitle{Project Status}
|
|
\begin{itemize}
|
|
\item \success{} Permission granted
|
|
\item \fail{} Funding open
|
|
\end{itemize}
|
|
\end{frame}
|
|
\end{document}
|
|
```
|
|
|
|
The theme uses Beamer's `sidebar` outer theme. Configure it with Beamer's standard `width`, `height`, `left`, `right`, `hideothersubsections` and `hideallsubsections` options.
|
|
|
|
The ground of a slide and the sidebar follow the colour roles of the company. Without `canvas-top` and `canvas-bottom` a slide is white with text in the `text` colour; with them, the ground runs from the first colour at the top to the second at the bottom, and `canvas-text` names the colour of the text on it. `sidebar-top` and `sidebar-bottom` do the same for the sidebar. The ground is drawn as one hundred bands and not as a Beamer shading, which xdvipdfmx writes into the first page only. The roles may also be set in the preamble of a single deck, after `\usetheme`:
|
|
|
|
```latex
|
|
\businesscolours{canvas-top = nordwind-deep, canvas-bottom = nordwind-sea!20,
|
|
canvas-text = white}
|
|
```
|
|
|
|
Business Suite adds:
|
|
|
|
| Option | Effect |
|
|
| --- | --- |
|
|
| `titleprefix` | Adds content before every frame title |
|
|
| `canvas=brand` | Uses the brand colour as the slide background |
|
|
| `nosectionframe` | Disables the opening frame for each section |
|
|
|
|
## Markdown Converter
|
|
|
|
`md2pdf.py` passes the selected identity and document template to Pandoc, then builds the generated LaTeX with XeLaTeX.
|
|
|
|
| Option | Default | Effect |
|
|
| --- | --- | --- |
|
|
| `--identity <name>` | Required | Selects the company identity package |
|
|
| `--out-dir <dir>` | Source directory | Sets the PDF output directory |
|
|
| `--lang <tag>` | `auto` | Controls hyphenation; `auto` detects the language unless the document defines `lang:` |
|
|
| `--paper <name>` | `a4paper` | Sets the paper format |
|
|
| `--fontsize <pt>` | `10pt` | Sets the document font size |
|
|
| `--toc` | Off | Adds a table of contents |
|
|
| `--highlight` | Off | Enables Pandoc syntax highlighting in code blocks |
|
|
| `--keep-tex` | Off | Retains the generated LaTeX and build files |
|
|
|
|
LaTeX searches the package directory of the suite first, then the `TEXINPUTS` the converter was called with, then the document directory and the TeX tree. The converter searches no folder below its own entries, so a document converts in the same time wherever it lies, and a picture in a subfolder is named by its path relative to the document. A company whose identity lies outside the TeX tree names its directory there, and a file beside a document cannot replace that identity. A `//` behind that directory also searches every folder below it, before the TeX tree, for every file LaTeX opens:
|
|
|
|
```sh
|
|
#!/bin/sh
|
|
TEXINPUTS="/path/to/company/latex//:$TEXINPUTS" exec md2pdf.py --identity company "$@"
|
|
```
|
|
|
|
The converter does not read a `latexmkrc` of the document directory and runs XeLaTeX without shell escape, in the probe and in the build, so neither a file beside the document nor a package found there can start a program. It does not restrict which files LaTeX reads or which picture paths a document names: convert only documents of a trusted origin.
|
|
|
|
Use `$E = mc^2$` for inline formulas and `$$...$$` for display formulas. The converter joins multi-line formulas before Pandoc parses them and reports this correction. This avoids Markdown interpreting a line containing only `=` as a level-one heading underline.
|
|
|
|
## Development
|
|
|
|
```bash
|
|
npm run build # Build all examples
|
|
npm test # Run all measurement tests
|
|
npm run clean # Remove generated files
|
|
```
|
|
|
|
The examples in `examples/` use `nordwind.sty`, a fictional company identity built from portable TeX Gyre fonts. The dedicated name avoids collisions with existing TeX Live packages.
|
|
|
|
Additional project documentation:
|
|
|
|
- [Tests](TESTS.md)
|
|
- [Features](FEATURES.md)
|
|
- [Open Tasks](TODO.md)
|
|
|
|
## Design Decisions
|
|
|
|
### No Company Data
|
|
|
|
Reusable templates contain no company-specific colour values, font names or asset paths. Tests scan all template sources and fail when they find such values.
|
|
|
|
### Measure Actual Content
|
|
|
|
The suite calculates logo height, address width, header and footer space, table-column widths and the space required by connected blocks from the rendered content. Fixed values derived from one font, paper format or company identity do not remain correct for another.
|
|
|
|
### Probe Document
|
|
|
|
The Pandoc table filter runs before LaTeX exists and therefore cannot directly inspect `\linewidth`. The converter builds a probe document with the selected company identity, then reads `\linewidth` and the width of a reference line from that document. This prevents table widths from depending on constants copied from another identity.
|
|
|
|
### Single Definition
|
|
|
|
Each company value has one authoritative definition in its identity package. The document, letter and presentation templates consume that package instead of copying its values. Tests therefore verify that templates contain no company-specific values, rather than checking whether duplicated values still match.
|
|
|
|
Shared table commands such as `\businessrowrule` and `\businesstablehead` belong to the identity layer because tables can appear in documents, letters and presentations. Loading an identity with the `plain` option retains these shared commands but omits document geometry and page styles.
|
|
|
|
### Document Language
|
|
|
|
The template does not set the document language. When Babel is loaded, Hyperref obtains the language from Babel. Setting it again would produce an `Option 'pdflang' has already been used` warning. Tests verify the resulting language in the document's XMP metadata.
|
|
|
|
### Native Beamer Sidebar
|
|
|
|
The presentation template uses Beamer's maintained `sidebar` outer theme instead of carrying a private copy.
|
|
|
|
### Letter Address Field
|
|
|
|
Window-envelope letters retain the physical 63 mm address field. With `\businessnowindow`, the field shrinks to the height required by the current recipient address and makes the remaining space available to the letter body.
|
|
|
|
## Licence
|
|
|
|
MIT, see [LICENSE](LICENSE). Use it, change it, sell what you build with it; keep the copyright notice in a copy.
|
|
|
|
Every source file of the suite carries the notice and the SPDX identifier in its first lines. A LaTeX package is installed file by file: what a company copies into its own tree is `business-suite.sty`, and the licence file does not travel with it.
|