tutorial. Flora:用Grove构建可执行文档[flora]

Flora是一个用Grove构建的文档森林。每篇文章都来自一份.plant源文件;普通文字、内容命令和Scheme计算共同组成内容树,再由Grove分析、执行并渲染为HTML。

Grove的写作模型、数学语言、文学编程实验与英语写作翻译彼此独立,也彼此链接。可以从感兴趣的主题索引进入;每篇文章和具名小节都能单独阅读。

主题索引[#4]

  • Grove文档:.plant源码、命令、Scheme求值、tree身份与内容组合。
  • 数学语言:Formula、Semantic与Notation表示,构造、计算、推导和关系查询。
  • 文学编程:从文章中的可执行定义到可复用片段、程序装配和元循环解释器。
  • 英语写作:Strunk与White的The Elements of Style第四版中文翻译。
  • 计算流体力学:Blazek的Computational Fluid Dynamics第二版双语翻译(试点:前置材料与第1–2章)。

术语表[#5]

三个主题共用的术语集中解释于术语表,例如tree、片段、计划、实例、taxon与Formula。

同一内容可以有多种阅读位置[#6]

下面这段定义来自Grove文档写作。它保留在来源树中,也嵌入在这里;嵌入保留来源:分析阶段会从这次嵌入建立一条指向来源树的阅读关系,但不导入任何程序binding。点击标题或地址可以回到独立页面。

一份页面源码的形状[source-shape]

页面源码由元数据、内容命令、普通文本和可选的Scheme计算组成。它保留为内容树,之后才交给分析和渲染阶段。

@use-modules[(flora commands) (language scribble commands)]

  @title{Page title}
  @summary{One-sentence description.}

  A paragraph written as ordinary text.

  @(define value (+ 20 22))
  @paragraph{The result is @code[value].}

这个例子包含模块导入、元数据、普通段落和Scheme计算;输出是一篇有标题、摘要和显示“The result is 42.”段落的页面。

项目与构建[#7]

project.scm声明源目录、模块和首页,并将Forester的文档分析接入Grove构建。.plant是Scribble风格的文档语法:@命令产生内容节点,Scheme表达式在读取时求值。文章中的Scheme表达式在读取时执行;构建产物包括HTML页面及可选的程序源码。项目配置和命令见仓库根目录的README。

文档森林的边界[#8]

一棵tree是可独立寻址的内容;它可以链接、嵌入或被查询。阅读关系不会自动成为Scheme依赖,嵌入代码也不会导入程序binding。Flora的实验围绕这些可组合边界展开。