diff --git a/.agents/modules/convert/README.md b/.agents/modules/convert/README.md new file mode 100644 index 0000000..730894b --- /dev/null +++ b/.agents/modules/convert/README.md @@ -0,0 +1,82 @@ +# `convert` module + +*Read this in: **English** | [Polski](README.pl.md)* + +Opt-in. Install with "install the convert module"; remove with "uninstall +the convert module". Nothing in here is active until installed. + +## What it does + +The KB writes Markdown. The people you send things to want a Word file or a +PDF that looks like the rest of your company's documents. This module turns +any Markdown file in the KB into **`.docx`, `.odt`, PDF or HTML** through +[pandoc](https://pandoc.org), in a **house style**, so nobody picks fonts, +sizes or margins by hand. + +| Skill | Does | +|---|---| +| `ckb-convert` | Converts a file in a named style; creates a style from a few settings or from your company's Word template; changes, checks and lists styles. | + +Say "give me the status report as a Word file" or "convert this answer to +PDF". The first time, it asks once how the house style should look. + +## Styles + +A style is a Word file, `templates/styles/.docx`. pandoc takes fonts, +sizes, colours, spacing, page size, margins, header and footer from it and +ignores its text. You get one in one of three ways: + +- **Describe it**: "make a house style with Georgia 11pt, navy headings, A4". +- **Bring your own**: "use Company.dotx as the house style". The agent copies + it in and tells you which styles pandoc needs that your template lacks. +- **Edit it by hand** in Word or LibreOffice: change the *styles* (Normal, + Body Text, Title, Heading 1–6, Table), not the text, and save as `.docx`. + +Several styles can live side by side ("convert it in the board style"). +`.css` styles HTML, and an optional `.odt` styles ODT directly. + +PDF and ODT are made from the styled `.docx` with LibreOffice, so all formats +look the same. Without LibreOffice, PDF falls back to a pandoc PDF engine and +won't follow the Word style. You'll be told when that happens. + +## What changes on the way + +The Markdown file is never changed and is always kept. In the converted +copy: + +- frontmatter becomes the title, author (without the e-mail) and date, and the + first `# Heading` becomes the title when there's none; +- `` left over from a template are dropped; +- `[[Wikilinks]]` and links to KB paths become plain text, because they'd be + dead in a Word file (say "keep the links" to keep them); web links stay; +- code blocks, tables, task lists and images come through as they are. + +## Settings + +In `ckb.yaml`, under the module's entry. Change them by asking ("make PDF +the default", "always add a table of contents"): + +```yaml +config: + style: house # templates/styles/house.docx + format: docx # docx | odt | pdf | html + out_dir: outputs/documents/ # a file already in outputs/ converts beside itself + toc: false + number_sections: false + keep_links: false +``` + +## Requirements + +- **pandoc**, for every conversion. The install doesn't need it, so a + teammate without it can still clone the KB; they're told how to get it the + first time they convert. +- **LibreOffice**, optional, for PDF and ODT in the house style. +- Python 3.8+ like every other KB script. Nothing is installed without asking. + +## Good to know + +- **Fonts aren't embedded** in a `.docx`. Choose fonts your readers have. +- **Uninstalling keeps your styles**: `templates/styles/` stays. +- **Macro templates** (`.docm`, `.dotm`) are refused; save a copy as `.docx` + or `.dotx` first. diff --git a/.agents/modules/convert/README.pl.md b/.agents/modules/convert/README.pl.md new file mode 100644 index 0000000..d924684 --- /dev/null +++ b/.agents/modules/convert/README.pl.md @@ -0,0 +1,86 @@ +# Moduł `convert` + +*Przeczytaj w: [English](README.md) | **Polski*** + +Opcjonalny. Instalacja: „install the convert module”, usunięcie: „uninstall +the convert module”. Dopóki nie jest zainstalowany, nic z tego folderu nie +działa. + +## Co robi + +Baza pisze w Markdownie. Ludzie, do których coś wysyłasz, chcą pliku Worda +albo PDF-a, który wygląda jak reszta dokumentów w firmie. Ten moduł zamienia +dowolny plik Markdown z bazy na **`.docx`, `.odt`, PDF lub HTML** przez +[pandoc](https://pandoc.org), w **stylu firmowym**, więc nikt nie dobiera +ręcznie czcionek, rozmiarów ani marginesów. + +| Skill | Co robi | +|---|---| +| `ckb-convert` | Konwertuje plik w wybranym stylu; tworzy styl z kilku ustawień albo z firmowego szablonu Worda; zmienia, sprawdza i wypisuje style. | + +Powiedz „give me the status report as a Word file” albo „convert this answer +to PDF”. Za pierwszym razem padnie jedno pytanie o to, jak ma wyglądać styl +firmowy. + +## Style + +Styl to plik Worda, `templates/styles/.docx`. pandoc bierze z niego +czcionki, rozmiary, kolory, odstępy, format strony, marginesy, nagłówek i +stopkę, a jego treść pomija. Styl można zdobyć na trzy sposoby: + +- **Opisać go**: „make a house style with Georgia 11pt, navy headings, A4”. +- **Przynieść własny**: „use Company.dotx as the house style”. Agent go + skopiuje i powie, których stylów potrzebnych pandocowi brakuje w szablonie. +- **Poprawić ręcznie** w Wordzie lub LibreOffice: zmieniać *style* (Normal, + Body Text, Title, Heading 1–6, Table), nie treść, i zapisać jako `.docx`. + +Stylów może być kilka („convert it in the board style”). `.css` +ustala wygląd HTML, a opcjonalny `.odt` wygląd ODT. + +PDF i ODT powstają ze sformatowanego `.docx` przez LibreOffice, więc +wszystkie formaty wyglądają tak samo. Bez LibreOffice PDF robi silnik PDF +pandoca i styl Worda nie jest stosowany. Agent o tym powie. + +## Co się zmienia po drodze + +Plik Markdown nigdy się nie zmienia i zawsze zostaje. W skonwertowanej +kopii: + +- frontmatter staje się tytułem, autorem (bez adresu e-mail) i datą, a + pierwszy nagłówek `#` staje się tytułem, gdy frontmatter go nie ma; +- komentarze `` pozostałe z szablonu znikają; +- `[[Wikilinki]]` i linki do ścieżek w bazie stają się zwykłym tekstem, bo w + pliku Worda byłyby martwe („keep the links” je zostawia); linki do stron + WWW zostają; +- bloki kodu, tabele, listy zadań i obrazy przechodzą bez zmian. + +## Ustawienia + +W `ckb.yaml`, we wpisie modułu. Zmienia się je prośbą („make PDF the +default”, „always add a table of contents”): + +```yaml +config: + style: house # templates/styles/house.docx + format: docx # docx | odt | pdf | html + out_dir: outputs/documents/ # plik już leżący w outputs/ trafia obok siebie + toc: false + number_sections: false + keep_links: false +``` + +## Wymagania + +- **pandoc** do każdej konwersji. Instalacja modułu go nie wymaga, więc + osoba z zespołu bez pandoca nadal może sklonować bazę; przy pierwszej + konwersji dowie się, jak go zainstalować. +- **LibreOffice**, opcjonalnie, do PDF i ODT w stylu firmowym. +- Python 3.8+, jak każdy skrypt bazy. Nic nie jest instalowane bez pytania. + +## Warto wiedzieć + +- **Czcionki nie są osadzane** w `.docx`. Wybieraj czcionki, które mają + czytelnicy. +- **Odinstalowanie zostawia style**: `templates/styles/` zostaje. +- **Szablony z makrami** (`.docm`, `.dotm`) są odrzucane; najpierw zapisz + kopię jako `.docx` lub `.dotx`. diff --git a/.agents/modules/convert/fragments/agents-routing.md b/.agents/modules/convert/fragments/agents-routing.md new file mode 100644 index 0000000..f1519cb --- /dev/null +++ b/.agents/modules/convert/fragments/agents-routing.md @@ -0,0 +1,16 @@ +## MODULE: convert + +Markdown in this KB becomes Word, ODT, PDF or HTML through pandoc, in a house +style: `templates/styles/.docx`. Settings are under the `convert` +entry of `kb_modules:` in `ckb.yaml`. + +- A request for a document as `.docx`, `.odt`, `.pdf` or `.html` ("as a Word + file", "send me a PDF") goes through `ckb-convert`, after the Markdown is + final (after `ckb-voice`, when that module is installed). The Markdown is + always kept beside the converted file. +- Styles are the user's files: create or change one only on request, and + never edit a style the user supplied (`--from`) unless asked. + +| User intent | Skill | +|---|---| +| Convert Markdown to Word/ODT/PDF/HTML, or create, change, check or list a house style | `ckb-convert` | diff --git a/.agents/modules/convert/fragments/gitignore.snippet b/.agents/modules/convert/fragments/gitignore.snippet new file mode 100644 index 0000000..2a8d190 --- /dev/null +++ b/.agents/modules/convert/fragments/gitignore.snippet @@ -0,0 +1 @@ +# convert module: nothing extra to ignore (styles in templates/styles/ are tracked). diff --git a/.agents/modules/convert/module.yaml b/.agents/modules/convert/module.yaml new file mode 100644 index 0000000..312e975 --- /dev/null +++ b/.agents/modules/convert/module.yaml @@ -0,0 +1,56 @@ +# Cascade KB module manifest — read by `ckb-module` on install/uninstall. +# See docs/decisions/0021-convert-module.md. +name: convert +title: Document conversion with house styles +version: 1.0.0 +requires_kb_schema: "1.7" +summary: > + Turns any Markdown file in the KB (a document from a template, a kept + answer, a report, a wiki page) into Word, OpenDocument, PDF or HTML through + pandoc, in a named house style kept in templates/styles/, so nobody has to + pick fonts, sizes or margins by hand. + +skills: + - ckb-convert + +# Created on install, never removed on uninstall: it holds the user's styles. +scaffold: + - path: templates/styles/ + from: scaffold/styles-README.md + as: templates/styles/README.md + note: House styles, one NAME.docx per style (NAME.odt and NAME.css optional). + +agents_fragment: fragments/agents-routing.md +gitignore_fragment: fragments/gitignore.snippet + +# Written under this module's `config:` in ckb.yaml on install; ckb-convert +# owns them afterwards ("make PDF the default", "use the board style"). +default_config: + style: house # templates/styles/