1.0.2: converter searches no subfolders, safer filters, forms, links and watermark

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>
This commit is contained in:
Marc WäckerlinandClaude Opus 5.5 committed 2026-11-14 12:14:55 +01:00
1 parent adc58e19d7
commit d7aac52ac7
28 files changed
+3918 -137

No files matched your search

+102 -2
View File
@@ -160,6 +160,8 @@ Company packages define concrete colours and assign them to semantic roles. Temp
| `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.
@@ -187,7 +189,14 @@ The identity can reference an image file or a drawing command:
\businessidentity{icon code = \companydrawing}
```
Image filenames omit the extension. The suite checks PDF, EPS, PNG and JPEG in that order. Convert SVG logos before the build.
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`.
@@ -331,7 +340,8 @@ Use standard LaTeX table environments with the shared table commands:
```
- `\businesstablehead{...}` formats a header cell.
- `\businessrowrule` draws the separator between rows.
- `\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:
@@ -343,6 +353,80 @@ The annual figures:
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
@@ -449,6 +533,13 @@ Load it from a presentation with `\usetheme{nordwind}`:
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 |
@@ -472,6 +563,15 @@ Business Suite adds:
| `--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