文档中的 SVG

12 版本之前的状况

从 2010 年左右开始，我们一直在努力用图形元素丰富 PostgreSQL 文档。大多数贡献者建议使用 SVG 作为此类图形的源语言，因为它具有许多优点。

• 它是标准化的（当前版本 1.1；2.0 正在开发中）并且被广泛使用。
• 它得到大多数浏览器和许多其他查看器的支持。
• 它可以渲染到不同物理尺寸的设备上 - 顾名思义。
• 它可在广泛的操作系统上使用。但是，尽管标准化了，但对于精心设计的特性，实现方式在许多情况下会导致不同的渲染结果。
• 有很多工具可以以舒适的方式生成 SVG。这些工具采用两种不同的策略

• 在 WYSIWYG 编辑器中编辑 SVG（Inkscape、svgedit、LibreOffice Draw、Google Docs Drawing，等等）
• 从其他语言生成 SVG（Markdeep、Graphviz、ditaa、Xfig、AsciiToSvg、blockdiag，等等）

• SVG 已集成到 DocBook 中。

测试表明，在从 SGML 更改为 XML 格式后（版本 11），将 SVG 文件集成到生成 PG 文档的工具链中变得很容易。

尽管我们专注于一种 **单一** 语言 - 即 SVG -，但我们尚未就生成它的工具以及如何长期处理它达成共识。WYSIWYG 编辑器存在的问题是

• 生成的 SVG 非常冗长，不可读，并且是特定于工具的。
• 它们倾向于将“高级”SVG 特性集成在一起，导致可移植性受损。

从其他语言生成 SVG 的问题在于，这些语言远没有 SVG 强大。在某些情况下，它们甚至只支持一种特殊用例。

我们对最终 SVG 的要求是

• 简短、紧凑、易于阅读
• 可进行差异比较
• 符合 SVG 1.1
• 限制在大多数查看器和平台上可移植的特性
• 通过遵循样式指南（字体、颜色、大小，等等）确保所有图形的同质性

每个图形两个文件

当前的 SVG 工具库包含大量的产品，但在我们的社区中没有明确的偏好。并且，在未来几年内，新的产品可能会取代旧产品。我们漫长的讨论表明，我们很可能在可预见的未来无法就所有作者使用的一种单一工具达成一致。因此，我们避免推荐任何特定产品。每个人都可以使用自己选择的工具 - 但必须提供一个满足上述要求的干净的 SVG 文件，以及原始的特定于工具的文件。SVG 文件在生成我们的文档时充当源文件，特定于工具的文件充当图形未来修改的基础。这两个文件都位于 doc/src/sgml/images 目录下的存储库中。

显然，从其他语言生成 SVG 的工具会生成上面提到的两种文件。从 12 版本 beta 1 开始，文档中包含两个示例，一个是使用 *ditaa* 生成的 (https://github.com/stathissideris/ditaa)，另一个是使用 *Graphvis* 生成的 (https://graphviz.cpp.org.cn/)。

但一些 WYSIWYG 编辑器也能够从“高级/特定于工具的”SVG 文件生成简单的 SVG，而不会丢失其强大的附加功能。例如：Inkscape 默认情况下会生成 *Inkscape SVG* 格式的 SVG 文件。在这种格式下，会发生所有列出的缺点。但可以将图形序列化为 *优化 SVG* 格式（不要与 Inkscape 的 *纯 SVG* 格式混淆）。如果以某种方式对 Inkscape 进行参数化，*优化 SVG* 就能满足我们的大部分要求。在这种情况下，连接器或组等复杂的概念将丢失。但是 - 如前所述 - 作者有机会存储两个文件，一个是用于未来工作的大型 *Inkscape SVG* 格式文件，另一个是用于生成文档的小型 *优化 SVG* 格式文件。作者不会丢失任何信息或功能，并且文档可以从简单易读的文件中生成，该文件以与大型文件相同的方式渲染。

在 WYSIWYG 编辑器中创建 SVG 的一般提示

• 使用网格。这将导致位置使用简单的整数。
• 对 viewbox 和 viewport 使用相同的值（= 宽度/高度）。这有助于理解纯 SVG 文件。viewbox 可以通过后续过程（如 fop）轻松缩放，以一致的方式调整所有尺寸。
• 首选的测量维度是 pt。仅使用无小数的数字（整数）。如果您混合使用 pt 和 em，则字符在 HTML 和 PDF 中的渲染大小将有所不同。
• 所有文档都应包含一个边框（带圆角和灰色背景的矩形），作为文档的纯文本、表格和图形之间的清晰分隔符。不要对该矩形使用 0/0 位置或 100% 大小，因为这会导致某些渲染系统中左右和/或上下线条不可见。

完成工作后，生成小型 SVG 文件，该文件是 PG 文档的源代码。使用 XML 或文本编辑器控制此文件。可以通过手动进行一些校正 - 但不建议这样做。

• 按照逻辑顺序重新排列 SVG 元素是一种好习惯。WYSIWYG 工具创建的顺序遵循您在交互式工作期间插入元素的顺序。但要注意：顺序决定 z 方向（如果后面的元素渲染到相同的 x/y 位置，则会隐藏前面的元素）。
• 在 rect 中，有时会存在 rx="0" 或 ry="0" 属性来定义圆角的半径。0 是默认值，您可以安全地删除这些属性。
• 在 style 属性中，有时会存在 stroke-width:1pt 字符串。它们没有效果，因为 1pt 是默认值，您可以安全地删除它们。

最后但并非最不重要的一点是，**验证 SVG 兼容性**，例如：validator.w3.org

我们有一些关于在 SVG 中使用颜色的提示。

如何将 SVG 文件集成到文档中

1. 将 SVG 文件存储在存储库的 doc/src/sgml/images 目录中。
2. 从传统的 SGML（xml）文件引用 SVG 文件

 <para>
  <figure id="gin-internals-figure">
   <title>GIN Internals</title>
   <indexterm><primary>... some text ...</primary></indexterm>
   <mediaobject>
    <imageobject>
     <imagedata fileref="images/gin.svg" format="SVG" width="100%"/>
    </imageobject>
    <!--  or:
    <imageobject role="html">
     <imagedata fileref="images/gin.svg" format="SVG" align="center"/>
    </imageobject>
    <imageobject role="fo">
     <imagedata fileref="images/gin.svg" format="SVG"  scale="70"/>
    </imageobject>
    -->
   </mediaobject>
  </figure>
 </para>

在 role="html" 模式下，Docbook 会根据 imagedata 元素的 align 属性将图形渲染为块（前后换行）或内联（以下文本包围图形的“自由”侧）。如果您不使用任何对齐方式（这会导致左对齐）或 align="center"，图形将显示为块，其他值会导致内联渲染。

如果图形前面和后面有文本，则大型图形应居中。如果表格位于图形之前或之后，则图形应与表格以相同的方式左对齐。

已知问题

• 手册页是从 sgml/ref/ 目录下的文件创建的。如果此类文件包含 SVG 图形，则生成的手册页看起来有点丑。请避免这种情况，并且仅将 SVG 包含到 sgml/ 目录下的文件中。