README

类似于邮件合并的Scribus扩展，用于从外部数据（电子表格、数据库等）自动生成Scribus和pdf文档。

Scribus Generator：使用数据创建美丽文档.

开源高质量pdf模板和邮件合并替代方案。您的想象力是创建美丽年鉴、个性化婚礼邀请函、游戏卡牌套装、俱乐部花名册、艺术或工作作品集等的极限。更多示例和模板。

什么是Scribus Generator？

Scribus 拥有一套广泛的页面布局功能和功能。其中一个缺失的功能是动态用数据替换文本。这种功能你可能已经熟悉，它是你首选办公应用中的典型 邮件合并 功能。

Scribus Generator 提供了这种功能。它允许你

• 动态替换文本和图像
• 动态更改对象颜色、位置、文本字体或大小
• 为每个数据条目生成单独的PDF（或Scribus）文件，或从所有数据生成单个文件
• 通过友好的用户界面直接在Scribus中工作，或从命令行工作
• 使用任何可以导出CSV的任何数据源（Excel、OpenOffice、MySQL、记事本、...）
• 等等...

一般来说，Scribus Generator 用数据替换文本以自动生成文件（例如SLA、PDF）。它最初由 Ekkehard Will 编写，并由 Berteh 进一步扩展。

一个简短的 如何使用 视频介绍了这个Scribus Generator。前6分钟为基本概述，最后12分钟为一些更高级的功能。

如何安装Scribus Generator？

对于较新的Scribus（1.5.6+、1.6.x等）：下载最新的ScribusGenerator版本。包括MacOS用户GUI等一些新增功能。

对于旧版Scribus 1.4.x到1.5.5：下载较旧的ScribusGenerator存档脚本。它不再受支持，但与较旧的（基于Python2）系统兼容。

在本地机器上的任何位置解压缩脚本，到一个用户可以写入的文件夹中。然后可以通过在对话框中选择脚本（ScribusGenerator.py）来启动 Scribus Generator：「Scribus → 脚本 → 执行脚本」，或从 命令行。

如何使用Scribus Generator

创建你的Scribus "模板"文件

像创建其他文件一样创建和设计您的Scribus文件。在您需要用数据替换文本的位置，只需添加%VAR_名称%，其中名称是您的数据文件中的列。查看我们的示例画廊，看看其他人做了什么。任何现有的Scribus文件都可以用作模板。

您可以将变量放置在文本框架中的任何位置。将所有格式和样式应用于您希望应用于最终文本的变量。

如果您希望为每个数据条目生成一页（或许多页），那么您就完成了，恭喜！如果您希望在一页上显示多个数据条目，只需在除第一个条目外的每个条目前添加文本%SG_NEXT-RECORD%：ScribusGenerator将在检测到此标记后自动加载新的数据记录。

创建您的（csv）数据文件

Scribus Generator期望一个CSV文件（逗号分隔值），这可以使用标准电子表格编辑器（如LibreOffice、Excel或GoogleDoc）轻松创建：输入数据，并保存/导出为CSV。只需确保您的CSV文件以UTF-8编码，以便拥有完整的字符集（重音符号、盲文、数学、西里尔字母、符号等）。

确保列的名称与您在设计的Scribus模板文件中引用的变量（%VAR_名称%）的名称相同非常重要。

我们建议以UTF-8编码保存，以启用完整的重音字符集、中文、西里尔字母、数学符号、箭头、盲文、符号等。许多更多只需复制粘贴您缺少键盘组合的字符。

使用OpenOffice或LibreOffice Calc以UTF-8编码导出格式良好的CSV文件就像小菜一碟，而使用Excel则不那么容易。如果您使用Microsoft的Excel，您可能会对这个免费插件感兴趣，它提供了良好的导出/导入功能：http://www.csvio.net/

CSV文件可以轻松地从许多现有的数据源生成（包括企业级ETL平台、大多数数据库如MySQL、PostgreSQL、SQLite3等），请参阅我们的维基页面了解如何使用其他数据源

运行生成器脚本 - 设置（Linux和Windows）

通过菜单运行脚本：脚本 > 执行脚本并启动ScribusGenerator.py。

在脚本对话框中，您可以配置Scribus Generator的输入和输出设置。

可以通过编辑logging.conf文件来设置更多（更技术性）的选项，以根据您的系统自动记录Scribus Generators的操作。例如，您可能希望将日志文件的存储位置（默认为scribusGenerator.log）移动到不需要管理员权限的目录（例如Windows中的C:\tmp\scribusGenerator.log），或者用您的默认系统记录器（Linux中的SysLogHandler，Windows中的NTEventLogHandler）替换文件记录。所有设置（以及更多）在Python日志文档中有描述。

运行生成器脚本 - 设置（MacOS）

通过菜单运行适当的脚本：脚本 > 执行脚本并启动ScribusGeneratorMac.py。

脚本的Mac版本使用Scribus插件API，该API支持一个非常有限的GUI，因此您将不得不在一系列对话框中输入和确认您的设置。

此对话框仅告知您Scribus Generator正在运行，并告诉您将呈现一系列对话框来收集所需的输入信息。请按照非常详细的ScribusGeneratorMac指南进行逐步操作。非常感谢kmcreative为ScribusGenerator增添的这个很好的功能。

Mac用户还可以使用Scribus Generator的命令行版本，从终端窗口运行。

动态图像

图像引用也可以使用Scribus Generator进行动态修改。请参阅屏幕录像视频 @6:10。

Scribus支持的所有图像都可以使用。但是，为了与ScribusGenerator一起使用，它们必须位于一个包含所有图像的单个文件夹中。此文件夹可以位于您的PC上的任何位置。在此文件夹中复制任何图像，并将其重命名为%VAR_pic%（以及您需要用于图片的任何其他变量名，例如%VAR_pic2%, %VAR_photo%）。

在Scribus文件中添加图像框架（例如，「Scribus → 插入 → 插入图像框架」）并打开获取图像的对话框（例如，在选定的框架上右键单击图像框架→ 获取图像...）。选择所需的“占位符”图片。

图像文件可以像前面描述的任何其他变量一样定义。只需确保在Scribus模板文件中有与变量名对应的列名即可。只需确保在文件名或CSV数据中处理文件扩展名，而不是两者都处理。

在ScribusGenerator中，将矢量图像（SVG、PDF或其他）作为图像框架导入是有效的，就像PNG或JPG图像一样；只需确保您的（相对或绝对）SVG文件路径与生成器的输出目录匹配，因为这是Scribus在将SLA转换为PDF格式时查找的位置。

Scribus有时会以非常低的分辨率渲染包含的图像，因此您应该检查源材料的分辨率（dpi）或大小。如果您想快速批量导出多分辨率SVG对象，您可能会对Inkscape的对象导出脚本感兴趣。

很遗憾，ScribusGenerator无法包含动态矢量文件（PDF或SVG），因为Scribus导入它们的方式（从菜单文件 > 导入 > 向量）是将它们即时转换为Scribus对象。这对于在Scribus中直接编辑非常好，但不适用于通过引用包含外部文件。

动态颜色

颜色可以像文本一样动态替换。请参阅屏幕录像视频 @8:31，或简单地进行以下操作：

1. 编辑Scribus文件中的颜色（编辑 > 颜色）并将您想替换的颜色重命名为变量名（通常将FromSVG# whatever替换为现在众所周知的格式%VAR_name%）。
2. 定义您要在最终文档中使用的颜色，并使用它们的Scribus名称作为颜色数据字段中的值。

结合Scribus中直接包含的众多知名调色板使用，可以使您的文档设计丰富多彩、引人入胜！

动态链接

可以通过2个步骤在几乎所有Scribus对象中插入可点击的（网页）链接

1. 右键单击 > PDF选项，激活是PDF注释
2. 右键单击 > PDF选项 > 注释属性，选择类型外部网页链接并输入目标URL，您显然也可以使用变量进行替换，如下所示。

合并输出 - 单个文档

您可以选择合并所有数据行生成一个文件，而不是为每行数据生成一个（sla或pdf）文件。只需根据需要选择选项，就可以在单个Scribus（和/或pdf）文件中得到下面的结果。如果您的文档布局有多个页面（双面或折叠小册子），对于Scribus Generator能够合并模板中相同页数（或其倍数）的文件非常重要。例如，对于三折文档，您的源sla应该有3、6或9页（或3的任何倍数）。

单页上的多个记录

Scribus Generator 允许您在单个文档中显示多个数据条目。非常适合生成自己的清单、团队图表、游戏卡、名人墙海报等。

只需在文档中（除了第一条记录之外）每次数据条目前放置文本 %SG_NEXT-RECORD%，按照我们的 示例文档。请注意，此占位符区分大小写，且必须是 大写。Scribus Generator将在检测到 %SG_NEXT-RECORD% 时自动加载下一条记录，并在到达模板末尾时停止。

一个完整的示例，基于 Dungeon World 生成怪物游戏卡，可在 MonsterCards 目录中找到，由 Dustin Andrews 创建。

高级布局、组和图层

Scribus Generator 脚本根据Scribus中的 级别 优先级排序项目。因此，对于高级布局（组、图层等），我们建议在将项目分组之前，将主要项目放在第一级，与 %SG_NEXT-RECORD% 占位符一起，以便它能够正常工作（假设您在第二个项目及其之后的开始处调用下一条记录）。

NEXT-RECORD 语法更改

请注意，Scribus Generator v2.8（从2019年1月开始）根据 "Next Record" 功能 的建议，更改了语法，以更简单易懂的名称命名，详见 建议 #118。

请手动更新较旧的模板，将 %VAR_NEXT-RECORD% 更改为 %SG_NEXT-RECORD%，或一次性调用，例如

python ./ConvertVAR_NEXT-RECORDToSG28.py ~/ScribusProjects/*/*.sla

动态输出文件位置

Scribus Generator 允许您轻松自定义生成文档的名称（和位置）。在数据中添加您希望输出的文件名，并在“输出文件名”字段中使用相应的变量（或多个变量的组合）。请注意，该文件名始终相对于输出目录，且 没有扩展名。

可以在文件输出选项的任何位置使用专用变量 %VAR_COUNT%，它将被替换为相关数据条目在数据文件中的位置。通过设置 OUTPUTCOUNT_FILL，强制该计数数字具有特定的长度（仅在 Scribus 1.5.6+ 版本 中）。

请参阅我们的 示例数据集 和相关的 示例模板 中 parent 和 outfile 值的组合。

更多高级用法

“Scribus 生成器”允许技术熟练的用户进一步自定义生成的文档，几乎可以更改任何对象的任何属性，例如线条的填充或轮廓颜色、某些文本的颜色、线条粗细、对象位置等。请参阅屏幕录像 @13:13。

例如，要动态更改对象的字体，请向其添加一个属性（“在对象上右键单击 → 属性 → 添加”）。必须将参数属性设置为SGAttribute，其名称为您想更改的对象属性（在本例中为FONT），其值为您想要的动态值（通常是某些%VAR_name%）。然后，您的数据（CSV）文件应包含要在给定变量的列中使用的字体名称，例如“Arial Regular”或“Courier New Bold”。

要更改子元素（例如文本框中的特定文本行）的属性，您可以使用RelationshipTo字段来定义哪些子元素应该接收新的属性。使用*来修改所有直接子元素，或使用任何其他简化的XPATH表达式来修改子集。

SGAttributes的示例

请注意，ScribusGenerator不会创建属性，而只是查看更新其值。因此，您可能需要稍微旋转对象（只需在旋转框中放入除0以外的任何值，它将被替换），以确保在保存文件时Scribus确实使用了ROT属性。

SGAttribute语法的更改

自ScribusGenerator v2.7（2018年4月发布）以来，SGAttributes的语法略有更改，以支持Scribus 1.5.3。如果您为旧版本的脚本编写了模板，请根据上述文档更新您的模板。

这可以通过使用经典的Scribus编辑器窗口来完成，只需将Parameter的值移动到RelationshipTo，并将Parameter设置为SGAttribute。

如果您有许多这样的文件或属性，建议使用脚本自动进行此更新。从命令行运行它，它会自动备份您的旧文件

python ./ConvertSGAttributesToSG27.py *.sla

从命令行运行Scribus生成器

可以从命令行运行Scribus生成器，而且速度很快！非常适合自动化工作流程或与其他工具集成。

请注意，只有SLA生成从命令行工作。目前，PDF生成不支持从ScribusGenerator命令行进行。

从脚本帮助中找到所有所需信息：./ScribusGeneratorCLI.py --help

positional arguments:
  infiles               SLA file(s) to use as template(s) for the generation,
                        wildcards are supported

optional arguments:
  -h, --help            show this help message and exit
  -c DATAFILE, --dataFile DATAFILE
                        CSV/JSON file containing the data to substitute in each
                        template during generation. Default is scribus source
                        file(s) name with "csv" extension instead of "sla". If
                        csv file is not found, generation from this particular
                        template is skipped.
  -d CSVDELIMITER, --csvDelimiter CSVDELIMITER
                        CSV field delimiter character. Default is comma: ","
  -n OUTNAME, --outName OUTNAME
                        name of the generated files, with no extension.
                        Default is a simple incremental index. Using SG variables
                        is allowed to define the name of generated documents.
                        Use %VAR_COUNT% as a unique counter defined automatically
                        from the data entry position.
  -o OUTDIR, --outDir OUTDIR
                        directory were generated files are stored. Default is
                        the directory of the scribus source file. outputDir
                        will be created if it does not exist.
  -m, --merge, --single
                        generate a single output (SLA) file that combines all
                        data rows, for each source file.
  -from FIRSTROW, --firstrow FIRSTROW
                        Starting row of data to merge (not counting the header
                        row), first row by default.
  -to LASTROW, --lastrow LASTROW
                        Last row of data to merge (not counting the header
                        row), last row by default.
  -s, --save            Save current generator settings in (each) Scribus
                        input file(s).
  -l, --load            Load generator settings from (each) Scribus input
                        file(s). Overloads all default values, not provided
                        command line arguments.

requirements
    This program requires Python 3.0+

examples:

  ScribusGeneratorCLI.py my-template.sla
    generates Scribus (SLA) files for each line of 'my-template.csv'
    by substituting the provides values into 'my-template.sla' to the 
    current directory.

  ScribusGeneratorCLI.py --outDir "/home/user/tmp" example/Business_Card.sla
    generates Scribus files for each line of example/Business_Card.csv
    in the "/home/user/tmp" subdirectory.

  ScribusGeneratorCLI.py --outName "card-%VAR_COUNT%-%VAR_email%"  */*.sla
    generates Scribus files for each sla file in any subdirectory
    that has a csv file with a similar name in the same directory.
    Generated files will have a name constructed from the entry position
    and "email" field, and are stored in their respective sla file directory.

  ScribusGeneratorCLI.py --single -c translations.csv -n doc_  lang/*.sla
    generates a single Scribus file for each sla file in the lang/ subdirectory
    using all rows of the translations.csv data file.
    Generated files will have a name constructed from the "doc_" prefix
    and the input sla file name.

 more information: https://github.com/berteh/ScribusGenerator/

更多详情

清洁输出

Scribus生成器将删除生成的文档中的未使用变量，以及包含它们的文本框（如果该文本框除了变量外不包含其他内容）。

如果您想保留这些未使用变量和空文本，请相应地更改ScribusGeneratorBackend.py中的默认设置，将CLEAN_UNUSED_EMPTY_VARS设置为0。

同样，如果这些未使用变量或空文本在简单文本（如单个换行符或像,;-这样的字符）之前，这些列表分隔符将被删除，因此您可以通过简单地将变量附加到以下方式来获得干净的枚举：“%VAR_n1%, %VAR_n2%, %VAR_n3%, %VAR_n4%”，或者使用（单）换行符在更表格化的布局中。

The following will show nicely even if some variable is empty or missing:
%VAR_n1%
%VAR_n2%
%VAR_n3%
%VAR_n4%

如果您想保留这些分隔符，请相应地更改ScribusGeneratorBackend.py中的默认设置，将REMOVE_CLEANED_ELEMENT_PREFIX设置为0。

换行符和tabulations在您的csv数据中会被Scribus的等效符号（换行符和制表符）所替换。要将其移除并将它们转换为普通空格，请将设置KEEP_TAB_LINEBREAK设置为0。

日志和调试

ScribusGenerator将所有操作记录在一个日志文件中，默认情况下该文件位于您的用户（主）目录中。如果您遇到意外的行为，请检查.scribusGenerator.log的内容以了解更多信息。您可以在logging.conf中更改日志设置（有关更多选项，请参阅Python日志配置）。

如果您想报告问题，请友好地复制粘贴您的.scribusGenerator.log中的相关（通常是最后）几行。

变量名

请尽量使用纯字母字符（A-Za-z0-9_）作为变量名，不要使用空格或其他特殊字符（如'&'）。例如，使用%VAR_first_name%和%VAR_zip_code%而不是%VAR_first name%和%VAR_&zip#code%。数据文件（CSV）的列将是first_name和zip_code。

这仅对Scribus文件中的变量名称和数据文件（CSV）的列名称很重要。当然，数据字段（CVS的行）可以包含任何字符。

数据库源

要使用数据库中的数据而不是（手动）电子表格，您只需将相关查询结果导出为CSV文件。以下是一些常见数据库引擎的示例。有关使用外部数据源的更多信息，请参阅我们的wiki 。

Mysql

mysql --delimiter="," -u myuser -p mydb -e "select f1,f2 from mytable" > /tmp/mydata.txt

或

mysql  -u myuser -p  mydatabase -e
"select field1 , field2 FROM mytable INTO OUTFILE
'/tmp/myfilename.csv' FIELDS TERMINATED BY ','
ENCLOSED BY '\"' LINES TERMINATED BY '\n' "

更多信息请参阅https://dev.mysqlserver.cn/doc/refman/5.1/en/select.html

Postgresql

使用\a开关切换未对齐的输出，使用\f ,激活逗号作为分隔符。使用\o myfile.csv将输出发送到文件，然后查询您的数据库。

Sqlite3

您可以在命令行中使用sqlite3 -csv或在sqlite的交互式shell中使用.mode csv。

脚本

在utils文件夹中提供了各种脚本，以方便您使用Scribus Generator。查看相关的README！

已知问题

Mac OSX/macOS故障排除

Mac OSX和macOS上的一些Python安装没有提供正常工作的Tkinter包，这对于常规ScribusGenerator GUI是必需的。您的选择是

• 使用ScribusGeneratorMac脚本，该脚本使用Scribus插件API对话框而不是Tkinter，或者
• 找到一种设置符合TCL/Tk环境的方法，或者
• 简单地使用Scribus Generator命令行界面脚本。

如果您想改进API对话框版本或为Scribus Generator贡献一个在Mac上工作的GUI，请不要犹豫！只需fork，branch，code并发出pull请求以获取您的贡献审查！

支持

请访问wiki以获取更多想法，查看已解决和未解决的问题，然后在线友好地报告一个问题，并将您的日志文件最后几行复制在那里（它是位于您用户（主）目录中的.scribusGenerator.log，以帮助找到这种不良行为的原因，并附上您问题的简要说明。

许可证

MIT许可证
版权
(c) 2011, Ekkehard Will (www.ekkehardwill.de)
(c) 2014-2024, Berteh (https://github.com/berteh/)

以下为对任何获得本软件及其相关文档文件（以下简称“软件”）副本的人的授权，免费许可其以任何方式处理软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本，并允许获得软件的人这样做，前提是遵守以下条件

上述版权声明和本许可声明应包含在软件的所有副本或实质性部分中。

软件按原样提供，不提供任何形式的保证，无论是明示的、暗示的还是其他的，包括但不限于适销性、特定用途的适用性和非侵权性保证。在任何情况下，作者或版权所有者都不对任何索赔、损害或其他责任承担责任，无论这些责任是由于合同、侵权或其他行为而引起的，与软件或使用软件或其他处理软件有关。