Guidedog / 文档 0.2.0

用图表解释概念¶

按问题选择图示。流程图解释选择，框图解释职责，时序图解释顺序，关系图解释联系。文字能更直接回答时，就用文字。

流程图¶

容量足够则转换；否则由宿主准备存储，再重试。 — 图 3 借用或扩展存储前，先检查容量。¶

图中在扩展步骤标明所有者，不暗示转换核心会分配内存。这一区别属于契约。

编写图表¶

.. graphviz::
   :caption: Parsing precedes resolution.
   :alt: The source becomes a tree, then references are resolved.

   digraph pipeline {
     graph [rankdir=LR, bgcolor="transparent"];
     node [shape=box];
     "source" -> "tree" -> "resolved tree";
   }

graphviz、graph 和 digraph 为内置指令。Guidedog 通过 Graphviz 渲染；HTML 获得 SVG 资源，PDF 嵌入渲染后的图示，两者使用同一图源。

让图表清晰易读¶

节点标签要短，较长规则写在图下。主路径尽量保持一个方向，返回边标明条件。除颜色外，也使用形状和文字；打印读者可能看不到颜色。

提供替代文本和题注。检查窄浏览器窗口和 PDF 页面。若必须用极小字号才能放下，拆成两幅图。图片和插图尺寸见图片、视频、音频与下载。