Communitygithub.com

scribus-sla

使用真实的 Scribus 引擎创建、填充、编辑和导出 Scribus .sla 文件,确保输出与桌面应用程序一致(PDF、可填充 PDF、PDF/X、PNG/JPG、SVG、EPS、PS)。适用于任何 .sla 或 Scribus 任务。

scribus-sla 是什么?

该技能通过安装真正的 Scribus 桌面应用程序(默认版本 1.6.3)以及一个轻量的 `sla` 命令行工具,为您提供处理 Scribus 文档的完整能力。它解决了手动编写复杂 `.sla` 文件或使用非真实渲染引擎导致输出不一致的痛点。所有导出操作都经过严格的像素级对比验证,确保与桌面版 Scribus 生成的 PDF 完全一致。 该技能支持多种平台,包括 Linux 环境,并且能够处理缺失字体和图像问题,以确保导出成功。它提供了丰富的命令,包括检查文档(`sla inspect`)、导出为各种格式(`sla export`)、填充模板占位符(`sla fill`)、运行脚本创建新文档(`sla run`)以及比较 PDF 文件(`sla compare`)。此外,它还支持字体管理(安装用户字体或从 Google Fonts 获取)。 该技能的核心规则是保持输出与桌面应用程序相同:缺失字体或图像会阻止导出以防止布局错误;图像链接相对于 `.sla` 文件;导出使用文档保存的 PDF 设置(除非用户覆盖);可填充 PDF 直接支持(嵌入字段字体)。填充模板功能允许替换文本占位符、替换文本框内容以及重新链接图片。创建新文档时,需要编写 Scribus 脚本(scripter)并由 `sla run` 执行,同时提供了完整的示例脚本作为起点。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/JessNco/scribus-sla/tree/HEAD

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Scribus .sla 文件,使用真实 Scribus 处理

绝不要手动渲染或近似一个 Scribus 文档,也绝不要手写整个 .sla 文件。 本技能会安装真实的 Scribus(默认版本 1.6.3)以及一个围绕它的小型 sla 命令。 通过此方式导出的文件已经与从 Scribus 1.6.3 桌面应用程序导出的 PDF 进行了对比: 11 个文档(纯文本、包含图片以及可填充表单)实现了像素级匹配。

1. 安装(每个会话一次,首次 2-4 分钟)

[ -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
  • 其他 Scribus 版本:bash /opt/sla/kit/scripts/setup.sh 1.6.5(还有 1.6.1、native)。 匹配用户运行的版本;引擎保存的文件会携带该引擎的版本号。
  • 需要 root 权限、apt 以及 github.com 和 archive.ubuntu.com 的网络访问权限。完成时会输出以 [sla-setup] ready: 开头的行。如果它警告回退到了另一个版本,请告知用户。
  • 引擎只能访问 /home、/tmp、/mnt、/root 下的文件。请在此工作。

2. 命令

sla inspect FILE.sla -v            # 页面、字体(已安装?)、图片(找到?)、命名项、{{占位符}}、表单字段
sla export FILE.sla                # 在 .sla 旁边生成 PDF,使用文档自身保存的 PDF 设置
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      # 打印 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          # 在 Scribus 中打开并保存:证明文件可加载,并对其进行规范化
sla run SCRIPT.py [args]           # 运行 Scribus Python(scripter)脚本;这是创建新文档的方式
sla compare A.pdf B.pdf --out DIR  # 像素比较,使用相同的渲染器和 DPI 处理两者;写入差异图像
sla fonts --grep sans              # 获取 Scribus 使用的精确字体名称
sla fonts --add FILE_OR_DIR        # 安装用户字体文件
sla fonts --google "Comic Relief"  # 通过 Google Fonts 获取开放许可的字体家族

sla <command> -h 列出所有选项。

3. 使输出与桌面应用程序完全相同的规则

  1. 缺失字体或图像会阻止导出。 Scribus 会静默替换缺失字体,导致布局偏移。sla export 会拒绝执行并指出缺失内容。安装字体(sla fonts --add/--google)或修复图像路径。只有在用户接受的情况下才传递 --allow-missing。 字体名称必须完全匹配,例如 Latin Modern Sans 10 Bold、DejaVu Sans Book。
  2. 图像链接相对于 .sla 文件。 保持文档及其资源与用户电脑上的相对布局一致,否则图像框将导出为空。
  3. 导出使用文档保存的 PDF 设置(压缩、PDF 版本、字体)。仅在请求时覆盖:--lossless、--outline-fonts、--pdf-version、--pdf-option KEY=VALUE。
  4. 可填充 PDF 直接可用。 对于包含表单字段的文档,工具会完整嵌入字段字体,如同桌面导出对话框所做的那样。(纯脚本导出会在这些文档上崩溃;不要使用轮廓字体来绕过。)
  5. 查看结果。 在任何创建/填充/编辑后:sla export FILE.sla -f png --dpi 72 -d /tmp/preview 并查看 PNG。当存在参考 PDF 时,运行 sla compare 并期望在 0.0000% 差异时显示 MATCH。
  6. 格式说明。 PNG/JPG 来自 Scribus 自身的“另存为图像”(使用 --raster-via pdf 改为从 PDF 栅格化;尺寸可能相差一个像素)。SVG 和 PS 从导出的 PDF 转换而来(SVG 中的文本变为轮廓)。EPS 是 Scribus 自身的,每页一个文件。

4. 填充模板

  • 在模板文本中放入 {{name}};--set name=value 会替换所有出现的位置。占位符 必须位于一个格式运行内(一次性输入,整体使用相同的字体和字号)。
  • --text ITEM=value 替换名为 ITEM 的文本框的全部文本,保留其第一个格式运行的 格式;\n 开始新段落。名称是 sla inspect -v 显示的项目名称 (Scribus:属性 > 名称)。
  • --image ITEM_OR_OLD_FILENAME=new.png 重新链接图片并将其适配到其框架中。添加 --keep-image-scale 可保留旧的缩放比例。
  • --data file.json 接受 {"placeholders": {}, "text": {}, "images": {}}。--strict 会在某个键未匹配任何内容时报错。
  • 结果会由 Scribus 重新保存,因此是一个真正的 Scribus 文件。

5. 创建新文档

编写一个 scripter 脚本并用 sla run 运行它。一个完整且经过测试的示例已安装在 /opt/sla/kit/examples/new_document.py(页面设置、颜色、样式、文本、形状、线条、图片、 保存)。复制它并调整。要点:

  • 将脚本包装在 try: ... finally: os._exit(0) 中,否则 Scribus 永远不会退出。
  • 首先定义颜色和样式;命名每个对象(createText(x, y, w, h, "name"))。
  • \r 在 setText 中分隔段落。单位取决于 newDocument 给出的设置(使用磅值)。
  • setScaleImageToFrame(True, True, name) 将图片适配到其框架,保持比例。
  • 使用 saveDocAs(path) 保存,然后 sla inspect 并预览它(规则 5)。
  • 要匹配现有的内部样式,首先 sla inspect -v 用户的一个文档,并重用其页面大小、字体、颜色和线宽。

6. 编辑现有文档

优先使用 scripter 脚本(openDoc,按名称更改对象,saveDocAs)。对 XML 进行小的属性编辑 也可以;之后运行 sla resave 并预览。有用的 XML 事实(Scribus 1.6):

  • 根元素 SCRIBUSUTF8NEW,一个 DOCUMENT。对象是 PAGEOBJECT(页面)、MASTEROBJECT (主版页面)、FRAMEOBJECT(内联对象)。PTYPE:2 图片、4 文本、5 线条、6 形状、7 折线、12 组。
  • 页面堆叠在一个画布上:对象的 XPOS/YPOS 包括其页面的 PAGEXPOS/PAGEYPOS。
  • 文本存在于 StoryText 中:ITEXT CH="..." 文本运行,para 段落,trail 尾部。字体是 FONT="..." 属性。
  • 图片:PFILE(相对于 .sla 的路径)。SCALETYPE="0" 适配到框架(Scribus 在加载时重新计算 缩放比例),SCALETYPE="1" 使用 LOCALSCX/LOCALSCY/LOCALX/LOCALY 自由缩放; RATIO="1" 保持比例。
  • 文本框的 path/copath 包含其形状:同时修改它们以及 WIDTH/HEIGHT (或者使用 scripter 脚本中的 sizeObject 调整大小,它会为您完成)。
  • 表单字段:带有 ANNOTATION="1" 的文本框,ANTYPE 3 文本、4 复选框、5 组合框、6 列表框。
  • 不要覆盖用户的原始文件;除非要求,否则写入一个新文件。

7. 如果出现故障

  • "Scribus exited ... crashed":运行 sla inspect,修复缺失字体/图片,尝试 sla resave 查看 文件是否能加载,然后逐页导出(--pages N)以找到问题对象。
  • 引擎构建失败:bash /opt/sla/kit/scripts/setup.sh native 会安装发行版提供的 Scribus(测试中导出结果也与参考文件匹配;保存的文件会携带该版本)。
  • 用户文档所需的字体并非开放许可(例如 Arial、Calibri):向用户索要字体文件。

相关技能