乐谱是书里的文本；它的外观是一项设置。

在 Postext 中，乐谱是写出来的记谱，而不是画出来的图。章节里的一个代码块用四种文本格式之一记下音乐，引擎用 Verovio（Music Encoding Initiative 的刻谱库）把它刻出来。乐谱按所在栏的宽度刻制，并切成若干谱行（系统），也就是读者从左到右读的一行行乐谱。每行谱作为单独的块放置：页面剩余空间放不下的乐谱会接到下一栏顶端继续，而且绝不会在一行谱内部断开。谱表大小、音乐字体、小节号和间距来自配置中的 scoreStyle 部分，改一项设置，整本书的乐谱外观就跟着改变。

乐谱是可选功能：没有记谱代码块的文档排版照旧，刻谱器（约 3.7 MB）只在含有乐谱的书中加载。

#格式

代码块	格式	适用于
```abc	ABC 2.1	旋律和单声部谱例、音符下配歌词的歌曲。紧凑，便于手写。刻谱器只读取 ABC 曲子的一个声部：多声部请用其他格式。
```musicxml	MusicXML 4.0	从 Dorico、Sibelius、Finale 或 MuseScore 导出的任何乐谱。篇幅较长，宜放在资源文件里。
```mei	MEI	校勘本和学术版本、早期音乐。
```humdrum、```kern	Humdrum (kern)	众赞歌和四部和声、分析谱例：每个声部一列，用制表符分隔，最低声部在前。

普通的 ```xml 代码块仍是代码清单。带 {listing} 的记谱代码块也保持为代码清单，便于在教程中展示曲子的源码。

#正文中的乐谱

完全正格终止在最高声部落在主音上：
 
```humdrum {alt="G 大调众赞歌乐句，以完全正格终止结束"}
**kern	**kern	**kern	**kern
*clefF4	*clefGv2	*clefG2	*clefG2
*k[f#]	*k[f#]	*k[f#]	*k[f#]
*M4/4	*M4/4	*M4/4	*M4/4
4GG	4B	4d	4b
4D	4d	4f#	4a
=	=	=	=
1GG	1B	1d	1g
==	==	==	==
*-	*-	*-	*-
```
 
半终止则停在属和弦上。

一段带歌词的旋律，用 ABC 写：

```abc
X:1
T:Evening hymn
M:3/4
L:1/4
K:F
c | A2 B | c2 A | G2 F | E2 c | A2 B | c2 A | G2 E | F2 |]
w: Now the day is o-ver, night is draw-ing nigh, sha-dows of the eve-ning steal a-cross the sky.
```

代码块有两个属性：

alt="…"：乐谱的内容说明，供读屏软件、带标签的 PDF 和 EPUB 使用。不写时读出记谱中写明的标题和作曲者（ABC 的 T: 和 C:，MusicXML 的 <work-title> 和 <creator type="composer">）。标题不会印出来：请写在正文或题注中。
style="…"：书中的命名乐谱样式（scoreStyles），例如为框内谱例准备的小号谱表样式。

正文中的乐谱不编号、不带题注，就像行间公式。它上下取样式的边距，两行谱之间取谱行间距，其后的正文回到基线网格。

#编号谱例

正文引用的谱例（“见谱例 3.2”）是一个 score 类资源，像插图一样排：编号、带题注、浮动或就地放置，并用 :ref 引用。

{
  "id": "ex-cadence",
  "typeId": "example",
  "kind": "score",
  "caption": "G 大调完全正格终止",
  "score": { "format": "musicxml", "source": "<?xml version=\"1.0\"?>…", "styleId": "small" }
}

:ref{id="ex-cadence"} 中的终止结束了这个乐句。
 
::resource{id="ex-cadence"}

类型为 example 的资源按 Postext 自带的谱例类型编号，名称随文档语言而定：Example、Ejemplo、Exemple、Notenbeispiel、Esempio、Exemplo、谱例、譜例、مثال。只要有资源用到，这一类型就会加入书的资源类型；想用别的名称就自定义一个类型。在资源包（preset.json）中，资源可以指向一个记谱文件，而不必携带全文：

{ "id": "ex-cadence", "typeId": "example", "kind": "score", "file": "resources/ex-cadence.musicxml" }

以 .abc、.musicxml、.mei 或 .krn 结尾的文件一律读作乐谱，不论 kind 写的是什么。命令行会把 --resources 文件夹中的这些文件读作谱例；Sandbox 的“资源”面板可以用 新建 › 新建乐谱 或拖入文件来创建。

乐谱资源整体保持：浮动或作为一个块放置。超过一页的乐曲应写成记谱代码块，它会在谱行之间断开。

#乐谱的外观

所有乐谱遵循 scoreStyle；叠加其上的命名样式只改变它所设定的部分：

const config: PostextConfig = {
  scoreStyle: {
    staffSize: { value: 5.5, unit: 'mm' },
    musicFont: 'Leland',
    barNumbers: 'system',
    minSystemsAtBreak: 2,
  },
  scoreStyles: [
    { id: 'small', name: '小号谱例', staffSize: { value: 4.5, unit: 'mm' }, barNumbers: 'none' },
  ],
};

谱表大小：五线谱表的高度。学校课本用 6～7 毫米，教材和教程用 5～6 毫米，正文中的谱例用 4～5 毫米。
音乐字体：Bravura（传统刻版风格）、Leland（较轻）、Petaluma（手写风格）、Leipzig 和 Gootville。
文字字体：歌词、速度标记和表情记号，未设置时用正文字体。若某个词用这种字体比刻谱器所用的 Times 更宽，就缩小排出，音节绝不会互相叠压。
间距、小节号、谱行间距、边距和墨色。
保持在一起的谱行（minSystemsAtBreak）：乐谱在栏底留下或转到下一栏的最少谱行数。设为 2 时，不会有一行谱孤零零地留下；不足四行的乐谱整体移动。

各字段及其类型和默认值见配置 › 乐谱样式。Sandbox 在 版面设计 › 图与表 › 乐谱 和 乐谱样式 中编辑它们。

#各种输出

Canvas 和 HTML：每行谱以矢量路径和文字绘出，颜色取乐谱的墨色；HTML 查看器用替代文本为乐谱命名。
PDF：矢量图形，文字使用书中嵌入的字体。在带标签的 PDF 中，每份乐谱是一个带替代文本的 Figure。
EPUB：可重排 EPUB 把各行谱显示为与阅读栏同宽的内联 SVG，作为一幅图像朗读；固定版式 EPUB 保留印刷页面。
Word：导出的文档按原样保留记谱代码块，就像代码清单一样，再次导入时乐谱会恢复。

#与音乐出版社合作

Postext 围绕音乐排书；写谱仍在打谱软件中完成。

在 Dorico、Sibelius、Finale 或 MuseScore 中刻制或校对乐谱，把每个谱例导出为 MusicXML（.musicxml，不压缩）。
把文件放进书的资源，类型设为 example。简短的单声部谱例可以直接在章节里用 ABC 写。
测量谱表大小，在 scoreStyle 中对上出版社的音乐字体；框内或页边的谱例用命名样式。
排版全书并检查分页。每行谱的小节数取决于栏宽、谱表大小和间距。

postext-port 技能在移植音乐教材、教程或歌本时遵循同样的步骤。

#限制

谱行填满整个栏宽：记谱中写明的换行位置目前还不保留。
ABC 读取器只读一个声部。
压缩的 MusicXML（.mxl）需要先解压。
完整的乐谱版本（管弦乐总谱、分谱、逐小节安排的翻页）属于打谱软件的工作，而不是排书软件的工作。

乐谱记谱

简单来说

#格式

#正文中的乐谱

#编号谱例

#乐谱的外观

#各种输出

#与音乐出版社合作

#限制