开发工具文档【免费下载链接】plantumlGenerate diagrams from textual description项目地址https://gitcode.com/gh_mirrors/pl/plantuml点击查看免费下载PlantUML 除了可以输出 PNG、SVG、EPS 等常见格式外还内置了一套完整的 LaTeXTikZ导出管线允许用户把 UML 图直接生成为.tex源文件再交给 lualatex / xelatex / pdflatex 编译成高质量 PDF无缝嵌入学术论文与出版物。本指南以 tikz 包 为骨架结合LatexEngine、TikzGraphics、LatexTextMetrics等核心类的源码实现讲解 PlantUML 的 LaTeX/TikZ 输出能力、引擎探测与选择逻辑、pragma 配置参数、输出格式差异以及底层工作原理帮助读者在项目中正确配置、使用并排障这一输出格式。一、tikz 包概览PlantUML 的 LaTeX 导出模块在仓库中LaTeX/TikZ 输出功能被集中封装在net.sourceforge.plantuml.tikz包内。该包目录下的文件与职责如下文件职责LatexEngine.java定义 LaTeX 引擎枚举lualatex / xelatex / pdflatex负责探测本机是否安装对应引擎并推荐默认引擎LatexTextMetrics.java通过启动真实的 LaTeX 进程测量文本的宽度、高度与深度保证图中文字布局精确StringBounderTikz.java实现StringBounder接口把文本测量能力接入 PlantUML 布局系统TikzFontDistortion.java处理字体放大系数magnify与畸变distortion参数TikzGraphics.java核心图形输出器把 PlantUML 内部的绘图指令翻译成 TikZ 命令并拼接.tex文件package-info.java包级 Javadoc声明该包用于管理 LaTeXTikZ输出格式包级说明package-info.java明确指出Provides classes used to manage LaTeX (with TikZ) output format即该包的唯一使命就是把 PlantUML 图导出为 LaTeX 配合 TikZ 宏包的输出格式。二、支持的命令行格式--latex 与 --latex-nopreamble在命令行入口 CliFlag.java 中定义了两种 LaTeX 相关格式--latex旧别名-tlatex/-latex生成包含完整 preamble文档头的.tex文件对应FileFormat.LATEX--latex-nopreamble旧别名-tlatex:nopreamble/-latex:nopreamble生成不含 preamble的纯 TikZ 片段方便直接嵌入到用户自己维护的 LaTeX 主文档中对应FileFormat.LATEX_NO_PREAMBLE。此外在 FileFormat.java 中还定义了一个内部用途的LATEX_DETERMINISTIC格式注意其扩展名显示为eps用于测试场景它在生成.tex时会省略 PlantUML 版本注释行从而保证输出的确定性便于 Vega 等测试框架做逐字节对比。典型用法示例# 生成带完整 preamble 的独立 .tex 文件 java -jar plantuml.jar -tlatex diagram.puml # 生成不含 preamble 的 TikZ 片段嵌入自己的主文档 java -jar plantuml.jar -tlatex:nopreamble diagram.puml # 指定输出目录 java -jar plantuml.jar -tlatex -o output/ diagram.puml对应的 Ant 任务在 PlantUmlTask.java 中同样支持formatlatex与formatlatex_nopreamble两种取值因此使用 PlantUML 官方 Ant 任务的项目也可以直接产出这两种格式。三、引擎选择机制LatexEngine 的探测与推荐生成.tex只是第一步真正把它变成 PDF 需要本机安装 LaTeX 发行版。PlantUML 并不会在 Java 侧编译 LaTeX而是把编译工作交给系统命令。引擎的选择逻辑全部集中在 LatexEngine.java 中。3.1 引擎枚举public enum LatexEngine { LUALATEX, XELATEX, PDFLATEX, UNKNOWN_OR_NOT_INSTALLED, NONE; }LUALATEX/XELATEX/PDFLATEX三种可用的具体引擎UNKNOWN_OR_NOT_INSTALLED用户在 pragma 中显式指定了引擎但本机探测不到该命令NONE完全不可用例如测试环境中被强制关闭。3.2 推荐顺序与探测方式getSuggestedEngine(Pragma pragma)的决策逻辑如下若测试标志FORCE_NONE为 true直接返回NONE这是为了在 Vega 测试中不依赖构建机是否安装 LaTeX若用户通过 pragma!pragma texSystem显式指定了引擎lualatex/xelatex/pdflatex则校验该命令是否真实可用可用则返回对应引擎否则返回UNKNOWN_OR_NOT_INSTALLED未指定时按lualatex → xelatex → pdflatex的顺序自动探测前两者具有原生 Unicode 与 fontspec 支持而 pdflatex 没有但 pdflatex 在最小化 TeX 安装中也常常存在所以被保留为最后的兜底方案三者都不可用则返回NONE。探测实现probeInstalled使用ProcessBuilder执行command --version读取并排空进程输出后以退出码是否为 0 判断命令是否存在于 PATH 中并使用ConcurrentHashMap做进程级缓存避免重复探测。从源码可以推断这一机制意味着PlantUML 的 LaTeX 输出强依赖本机 PATH 中存在对应的可执行文件这是该格式最重要的环境前提。四、可配置项texSystem 与 texPreamble 两个 pragmaLaTeX 输出的行为由两条 pragma 控制二者在 PragmaKey.java 中定义分别是TEX_SYSTEM与TEX_PREAMBLE在 PlantUML 源文件中写作startuml !pragma texSystem lualatex !pragma texPreamble \usepackage{fontspec} enduml4.1!pragma texSystem可选值lualatex、xelatex、pdflatex不区分大小写作用强制指定用于排版与文本测量的引擎底层读取LatexEngine.getSuggestedEngine通过pragma.getValue(PragmaKey.TEX_SYSTEM)读取LatexEngine.java注意若指定的引擎未安装返回UNKNOWN_OR_NOT_INSTALLED不会自动回退到其他引擎。4.2!pragma texPreamble作用向生成的.tex文件中注入自定义 preamble 内容如字体包、\usepackage{...}等底层读取TikzGraphics构造函数通过pragma.getValue(PragmaKey.TEX_PREAMBLE)读取并写入生成的文档头TikzGraphics.java同时TikzFontDistortion.updateFromPragma也会读取该值并传给文本测量进程TikzFontDistortion.java确保测量与最终渲染使用同一 preamble。而 pragma 集合到引擎的桥接在 Pragma.java 中public LatexEngine getLatexEngine() { return LatexEngine.getSuggestedEngine(this); }这也解释了为什么TEX_PREAMBLE中的内容既会出现在最终.tex文档头也会被送入文本测量进程两个环节必须保持一致否则布局测量与最终渲染会出现偏差。五、输出结构TikzGraphics 生成的 .tex 文件解剖TikzGraphics.java 是实际输出.tex的引擎。它把 PlantUML 内部的UPath、矩形、椭圆、文本、链接等图形元素逐一翻译为 TikZ 命令并在createData(OutputStream)中组装最终文件。5.1 完整 .tex 的骨架当format FileFormat.LATEX即带 preamble时生成的文件结构如下对应 TikzGraphics.java 的逻辑\documentclass[tikz]{standalone} \usepackage{amsmath} \usepackage[T1]{fontenc} % 若图中有 URL 链接 \usetikzlibrary{calc} \usepackage{hyperref} % 用户通过 !pragma texPreamble 注入的内容 \begin{document} % 非 deterministic 模式下% generated by Plantuml 版本号 % 自定义颜色的 \definecolor{plantucolor0000}{RGB}{r,g,b} % scale ! 1 时\scalebox{...}{% \begin{tikzpicture}[yscale-1 ,pstyle0/.style{...} % 被复用的样式定义 ] ... 各条 \draw / \shade / \node 命令 ... \end{tikzpicture}% % } \end{document}值得注意的几个细节坐标系统使用[yscale-1]PlantUML 内部是屏幕坐标系y 向下TikZ 默认是数学坐标系y 向上通过yscale-1翻转实现坐标对齐所有坐标都以pt为单位输出例如(10pt,20pt)自定义颜色被统一命名为plantucolor0000、plantucolor0001…… 并通过\definecolor{...}{RGB}{...}定义TikzGraphics.java黑白两色直接映射为 TikZ 内建white/black相同绘图样式会被提取为pstyleN并在\begin{tikzpicture}中声明复用从而压缩文件体积只出现一次的样式不会进入样式表purgeStyles。5.2 基本图形元素的 TikZ 翻译PlantUML 内部元素生成的 TikZ 命令示意源码位置直线line\draw[color...,line width1pt] (x1pt,y1pt) -- (x2pt,y2pt);TikzGraphics.java矩形rectangle\draw[...] (xpt,ypt) rectangle (x2pt,y2pt);TikzGraphics.java圆角矩形rectangleRound由四段arc 直线段组合成闭合路径TikzGraphics.java椭圆ellipse\draw[...] (xpt,ypt) ellipse (wpt and hpt);TikzGraphics.java弧线arc\draw[...] (xpt,ypt) arc (start:end:rpt);TikzGraphics.java任意路径upath折线--、三次贝塞尔..controls A and B ..、圆弧arcTikzGraphics.java多边形polygon各顶点依次--后以cycle;闭合TikzGraphics.java文本text\node at (xpt,ypt)[below right,...]{...};TikzGraphics.java单字符drawSingleCharacter\node at (xpt,ypt)[]{\textbf{\Large c}};TikzGraphics.java5.3 文本样式与特殊字符保护text()方法把 underline / italic / bold 分别映射为 LaTeX 的\underline{}/\textit{}/\textbf{}并支持嵌套TikzGraphics.java。同时LatexTextMetrics.protectText() 负责对文本中的 LaTeX 特殊字符进行转义保护包括#、$、%、、_、{、}转义为\#、\$、\%、\、\_、\{、\}^与~转义为\^{}与\~{}反斜杠\最终转为\textbackslash{}法语引号«»转义为\guillemotleft{}/\guillemotright{}制表符被替换为 8 个空格处理见 issue #1016行首行尾空白被替换为~不可断行空格。这套保护机制保证了图内文本即便包含_、%等字符也不会破坏 LaTeX 编译。5.4 超链接支持当图中元素带有 URL 时TikzGraphics会开启hasUrl标记并输出两套 TikZ 样式TikzGraphics.javahref node外部链接使用\href{url}{...}hyperref node内部交叉引用URL 以latex://前缀标记使用\hyperref[label]{...}前缀由extractInternalHref剥离。生成的注释还特别说明xelatex 需要\XeTeXLinkBox包裹的文本才会产生可点击链接而 pdflatex 与 lualatex 也能正常编译这段代码说明该实现刻意做了跨引擎兼容。六、文本测量LatexTextMetrics 如何问 LaTeX 要尺寸PlantUML 布局系统在排版前必须知道每个文本块的精确宽高否则盒子大小与连线位置都会错位。TikZ 后端没有直接复用 AWT 字体度量而是采用了最可靠的方式启动真实的 LaTeX 引擎来测量。LatexTextMetrics.java 的工作原理如下在构造时创建一个临时目录Files.createTempDirectory(plantuml-latex-)在该目录中以-halt-on-error模式启动所选引擎的交互式进程向进程写入一段最小文档头\documentclass[tikz]{standalone}\usepackage{amsmath} 用户 preamble并等待回显*latex_query_start确认引擎就绪每次需要测量时向进程写入模板{\sbox0{文本}\typeout{\the\wd0,\the\ht0,\the\dp0}}即用\sbox把文本放入盒子再把盒子的宽度\wd0、高度\ht0、深度\dp0通过\typeout打到标准输出用正则\*?[\d.]pt,[\d.]pt,[\d.]pt解析回显得到宽、高、深三个数值结果写入容量为 128 的 LRU 缓存相同文本不再重复测量。从该实现可以得到两个重要事实若本机没有安装对应引擎或缺少amsmath、tikz宏包构造会抛出异常并提示please install command, and package amsmath, tikz这正是 LaTeX 输出最常见的报错来源测量进程与主进程同时存活PlantUML 在生成阶段就与真实 LaTeX 引擎保持实时通信。源码中还针对已知问题做了加固测量进程的环境变量中移除了TEXMF_OUTPUT_DIRECTORYTeX Live 会为子进程设置该相对路径可能导致测量进程在临时目录外写文件而挂起见 issue #2764临时目录注册了deleteOnExit以便退出时清理。七、字体参数TikzFontDistortion 的 magnify 与 distortionTikzFontDistortion.java 定义了文本测量时的字体补偿参数格式为magnify;distortionmagnify放大系数默认值1.20distortion畸变修正量默认值4.0允许负数。fromValue(String)解析形如1.2;-2.0的字符串第一个 token 必须匹配[\d.]第二个必须匹配[-\\d.]否则回退到默认值。该对象还持有texPreamble字段供文本测量使用。这些参数影响的是布局阶段对字体尺寸的估计最终渲染仍由真实 LaTeX 引擎完成。八、布局集成StringBounderTikz 如何接入 PlantUML 布局StringBounderTikz.java 实现了 PlantUML 布局系统所需的StringBounder接口calculateDimension(font, text)调用LatexTextMetrics.getWidthHeightDepth返回宽与高深组成的XDimension2DgetDescent(font, text)直接返回深度\dp0matchesProperty(TIKZ)标识该测量器面向 TikZ 后端特别处理当测量出的高度为 0 且文本为空白时回退用单个空格文本的宽度作为高度避免布局异常对应 issue #1259 的修复。styleText会把字体样式翻译成 LaTeX 命令后送入测量进程斜体包\textit{}粗体包\textbf{}与最终渲染时TikzGraphics.text()的做法保持一致从而保证测得准与画得准。九、测试与确定性LATEX_DETERMINISTIC 的用途在 FileFormat.java 中LATEX、LATEX_NO_PREAMBLE、LATEX_DETERMINISTIC三个格式被归为一组而LATEX_DETERMINISTIC由TextBlockExporter等内部路径使用TextBlockExporter.java用于测试与对比。LatexEngine.FORCE_NONE标志LatexEngine.java注释明确说明在 Vega 等测试中强制返回NONE使渲染不依赖构建机是否安装 LaTeX 发行版。结合LATEX_DETERMINISTIC省略版本注释行TikzGraphics.java的设计可以推断测试框架利用这两点获得稳定、可重复的基准输出。十、典型使用流程与排障指南10.1 从 PlantUML 到 PDF 的完整链路确认本机已安装 TeX Live / MiKTeX 等发行版且lualatex、xelatex、pdflatex至少其一在 PATH 中编写.puml文件必要时通过!pragma texSystem指定引擎、!pragma texPreamble注入宏包使用java -jar plantuml.jar -tlatex diagram.puml或-tlatex:nopreamble生成.tex使用对应引擎编译lualatex diagram.tex或xelatex/pdflatex得到 PDF。10.2 常见报错与对策现象原因对策提示please install lualatex, and package amsmath, tikz引擎未安装或宏包缺失安装对应引擎及宏包或改用!pragma texSystem xelatex/pdflatexUNKNOWN_OR_NOT_INSTALLED显式指定的引擎在 PATH 中不存在检查引擎名拼写与 PATH 配置编译 PDF 时中文/Unicode 乱码默认引擎为 pdflatex无原生 Unicode 支持通过!pragma texSystem lualatex或xelatex指定支持 fontspec 的引擎并在texPreamble中引入字体方案需要嵌入已有主文档独立.tex自带\documentclass改用-tlatex:nopreamble生成纯 TikZ 片段十一、进一步阅读包级说明与入口tikz/readme.md、package-info.java引擎探测LatexEngine.java文本测量LatexTextMetrics.java、StringBounderTikz.java图形输出TikzGraphics.java格式与命令行FileFormat.java、CliFlag.java、PlantUmlTask.javapragma 定义PragmaKey.java、Pragma.java。通过本文的源码级拆解可以看到PlantUML 的 LaTeX/TikZ 输出并非简单的文本拼接而是一套引擎探测—实时文本测量—TikZ 命令生成—样式去重—链接兼容的完整工程实现适合追求期刊排版质量、需要把 UML 图无缝融入 LaTeX 文档的开发者直接使用。赞分享开发工具文档【免费下载链接】plantumlGenerate diagrams from textual description项目地址https://gitcode.com/gh_mirrors/pl/plantuml点击查看免费下载相关推荐PlantUML sdot 包源码解析Smetana 布局引擎GraphViz 内部移植版的导出实现PlantUML sdot 包源码解析Smetana 布局引擎GraphViz 内部移植版的导出实现 本指南以 PlantUML 仓库中 sdot 包目录开发工具文档plantuml-mcp-js基于 TeaVM 编译引擎的纯 Node.js PlantUML MCP 服务器实战指南plantuml mcp js基于 TeaVM 编译引擎的纯 Node.js PlantUML MCP 服务器实战指南 PlantUML 官方仓库中提供了一款开发工具文档Pandoc 从 LaTeX 到 PlainGutenberg 输出章节编号与 \ref 交叉引用的解析实战Pandoc 从 LaTeX 到 PlainGutenberg 输出章节编号与 \ref 交叉引用的解析实战 导读 本篇技术指南以 pandoc 官方命令测文档开发工具CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
