Scribus .sla files, done with real Scribus
Never hand-render or approximate a Scribus document, and never write a whole .sla by hand.
This skill installs the real Scribus (default 1.6.3) and a small sla command around it.
Exports made this way were checked against PDFs exported from the Scribus 1.6.3 desktop
app: 11 documents (plain, with images, and fillable forms) matched pixel for pixel.
1. Install (once per session, 2-4 minutes the first time)
[ -d /opt/sla/kit/.git ] || git clone --depth 1 https://github.com/JessNco/scribus-sla /opt/sla/kit
bash /opt/sla/kit/scripts/setup.sh
- Another Scribus version:
bash /opt/sla/kit/scripts/setup.sh 1.6.5(also1.6.1,native). Match the version the user runs; a file saved by the engine carries the engine's version. - Needs root,
apt, and network access togithub.comandarchive.ubuntu.com. Finishes with a line starting[sla-setup] ready:. If it warns that it fell back to another version, tell the user. - The engine can only see files under
/home,/tmp,/mnt,/root. Work there.
2. Commands
sla inspect FILE.sla -v # pages, fonts (installed?), images (found?), named items, {{placeholders}}, form fields
sla export FILE.sla # PDF next to the .sla, using the document's own saved PDF settings
sla export FILE.sla -f pdf,png,svg,eps,ps,jpg --dpi 300 -d OUTDIR --pages 1,3-5
sla export FILE.sla --pdf-version x4 --crop-marks --bleed 8.5 # print PDF (x1a, x3, x4; --cmyk; --profile)
sla fill TEMPLATE.sla OUT.sla --set name=Value --text frame_name="New text" --image frame_name=new.png
sla resave IN.sla OUT.sla # open in Scribus and save: proves the file loads, normalises it
sla run SCRIPT.py [args] # run a Scribus Python (scripter) script; this is how new documents are made
sla compare A.pdf B.pdf --out DIR # pixel comparison, same renderer and DPI for both; writes diff images
sla fonts --grep sans # exact font names as Scribus spells them
sla fonts --add FILE_OR_DIR # install the user's font files
sla fonts --google "Comic Relief" # open-licensed families from Google Fonts
sla <command> -h lists every option.
3. Rules that keep the output identical to the desktop app
- Missing fonts or images stop the export. Scribus substitutes a missing font silently and
the layout shifts.
sla exportrefuses and names what is missing. Install the font (sla fonts --add/--google) or fix the image path. Only pass--allow-missingif the user accepts it. Font names must match exactly, e.g.Latin Modern Sans 10 Bold,DejaVu Sans Book. - Image links are relative to the
.slafile. Keep a document and its assets in the same relative layout as on the user's computer, or the frames export empty. - Export uses the document's saved PDF settings (compression, PDF version, fonts). Override
only on request:
--lossless,--outline-fonts,--pdf-version,--pdf-option KEY=VALUE. - Fillable PDFs just work. For documents with form fields the tool embeds the field font in full, as the desktop export dialog does. (Plain scripted export crashes on these; do not work around it with outlined fonts.)
- Look at the result. After any create/fill/edit:
sla export FILE.sla -f png --dpi 72 -d /tmp/previewand view the PNG. When a reference PDF exists, runsla compareand expectMATCHat 0.0000%. - Format notes. PNG/JPG come from Scribus's own "Save as Image" (use
--raster-via pdfto rasterise the PDF instead; sizes can differ by one pixel). SVG and PS are converted from the exported PDF (text becomes outlines in SVG). EPS is Scribus's own, one file per page.
4. Filling a template
- Put
{{name}}in the template text;--set name=valuereplaces it everywhere. A placeholder must sit in one formatting run (type it in one go, same font and size throughout). --text ITEM=valuereplaces the whole text of the frame named ITEM, keeping its first run's formatting;\nstarts a new paragraph. Names are the item names shown bysla inspect -v(Scribus: Properties > Name).--image ITEM_OR_OLD_FILENAME=new.pngrelinks a picture and fits it to its frame. Add--keep-image-scaleto keep the old scale instead.--data file.jsontakes{"placeholders": {}, "text": {}, "images": {}}.--strictfails if a key matched nothing.- The result is re-saved by Scribus, so it is a genuine Scribus file.
5. Creating a new document
Write a scripter script and run it with sla run. A complete, tested example is installed at
/opt/sla/kit/examples/new_document.py (page setup, colours, styles, text, shapes, lines, image,
save). Copy it and adapt. Essentials:
- Wrap the script in
try: ... finally: os._exit(0)or Scribus never quits. - Define colours and styles first; name every object (
createText(x, y, w, h, "name")). \rseparates paragraphs insetText. Units are whatevernewDocumentwas given (use points).setScaleImageToFrame(True, True, name)fits a picture to its frame, keeping proportions.- Save with
saveDocAs(path), thensla inspectand preview it (rule 5). - To match an existing house style,
sla inspect -vone of the user's documents first and reuse its page size, fonts, colours and line weights.
6. Editing an existing document
Prefer a scripter script (openDoc, change objects by name, saveDocAs). Small attribute edits
in the XML are fine; run sla resave afterwards and preview. Useful XML facts (Scribus 1.6):
- Root
SCRIBUSUTF8NEW, oneDOCUMENT. Objects arePAGEOBJECT(pages),MASTEROBJECT(master pages),FRAMEOBJECT(inline).PTYPE: 2 image, 4 text, 5 line, 6 shape, 7 polyline, 12 group. - Pages are stacked on one canvas: an object's
XPOS/YPOSinclude its page'sPAGEXPOS/PAGEYPOS. - Text lives in
StoryText:ITEXT CH="..."runs,para,trail. Fonts areFONT="..."attributes. - Images:
PFILE(path relative to the .sla).SCALETYPE="0"fit to frame (Scribus recomputes the scale on load),SCALETYPE="1"free scaling usingLOCALSCX/LOCALSCY/LOCALX/LOCALY;RATIO="1"keeps proportions. - A text frame's
path/copathhold its shape: change them together withWIDTH/HEIGHT(or resize in a scripter script withsizeObject, which does it for you). - Form fields: a text frame with
ANNOTATION="1",ANTYPE3 text, 4 check box, 5 combo, 6 list. - Do not save over the user's original; write a new file unless asked.
7. If something fails
- "Scribus exited ... crashed": run
sla inspect, fix missing fonts/images, trysla resaveto see whether the file loads at all, then export page by page (--pages N) to find the object. - Engine build failed:
bash /opt/sla/kit/scripts/setup.sh nativeinstalls the distribution's Scribus instead (exports matched the references too in testing; saved files carry that version). - Fonts the user's document needs that are not open-licensed (e.g. Arial, Calibri): ask the user for the font files.