progdoc格式说明
1. 简介
progdoc格式主要用于编写软件开发和程序设计方面的设计、使用说明、API等文档。
progdoc把符合progdoc格式的文本文件转换为单一html文件。
progdoc格式文件的文件名后缀通常是 .pd ，文件编码必须是UTF-8。
progdoc格式设计原则为：
- 格式尽可能简约，以降低学习使用难度
- 使用 # ` 这两个程序设计中很少使用的字符作为格式前导字符
- 有内嵌html功能，以用于文档中插入latex数学公式等需求
1.1. progdoc格式主页
progdoc格式解析程序、格式说明和使用方法请看：
2. 太长不看版
| 格式 | 名称 | 说明 |
| 正文格式 | ||
[[AA]] |
5.4. 内链 | 指向文档内部锚点 |
#[AA#](BB) |
5.5. 外链 | AA是外链说明，BB是外部链接 |
!#[AA#](BB) |
5.6. 图片 | AA是图片说明，BB是图片链接 |
| `AA` | 5.2. 短代码 | AA可以是任意字符，不参与格式解析 |
| ``AA$ | 5.3. 行代码 | 从``开始到行尾的字符不参与格式解析 |
| #` | 5.1. 实体替换 | 用 #` 来表示不起格式作用的 ` 字符 |
| 行分类 | ||
^{数字+.}+AA |
6. 标题行 | 每个标题行是锚点，也是目录一项，多少个点就是多少级标题 |
| 多行代码类 | ||
| ```AA | 7.2. 多行代码行S | 多行代码行的开始，后续均看作代码行，不作格式解析 |
^```$ |
7.3. 多行代码行SE | 根据上下文，可当成多行代码行的开始行或结束行 |
| 列表类 | ||
^{空白+}#-AA$ |
8.2. 单行列表行 | 列表内不能有其它类的格式行（如表格、多行代码等） |
^{空白+}#--AA$ |
8.3. 多行列表行S | 列表的多行列表项的开始行 |
^{空白+}#--$ |
8.4. 多行列表行E | 列表的多行列表项的结束行 |
| 表格类 | ||
^#|GAA#|GBB..#|GNN$ |
9.2. 单行表格行 | G是对齐字符，< 左对齐，> 右对齐，^ 居中 |
^#|-AA$ |
9.3. 多行表格行SE | AA是任意填充字符，不作格式解析不参与输出 |
| 内嵌html类 | ||
^#<<AA$ |
10.2. 内嵌html多行S | 内嵌html多行的开始行，后续行不做任何格式解析，原样输出 |
^#>>AA$ |
10.3. 内嵌html多行E | 内嵌html多行的结束行 |
3. 文档描述约定
3.1. 特定大写字母含义
- S 开始
- C 继续
- E 结束
- AAA 或 BBB 表示若干个普通格式正文字符
3.2. 格式字符串格式字符含义
- ^ 在格式字符串的最前面，则表示行首
- $ 在格式字符串的最后面，则表示行尾
- + 表示1个或多个
- {AB} 表示AB是1个最小单元整体
- 空白字符，是指空格符和水平制表符。
3.3. 格式描述说明
- 格式：该格式的格式字符和相关正文的描述规则
- 行首尾：对行首或行尾有无特殊约定
- 禁用字符：该格式内的禁用字符或禁用字符串
- 字符替换：该格式内对哪些字符进行输出字符替换
- 内部格式：该格式内允许有哪些内部格式
- 说明：其它说明
- 示例：使用示例，分两部分：源文本是格式文本内容，实际效果是解析后html的显示效果。
4. 行分类
progdoc对输入文件按行分类，进行格式解析。行的类别有：
- 格式正文行
- 标题行
- 多行代码类
- 多行代码行S
- 多行代码行SE
- 列表类
- 单行列表行
- 多行列表行S
- 多行列表行E
- 表格类
- 单行表格行
- 多行表格行SE
- 内嵌html类
- 内嵌html多行S
- 内嵌html多行E
5. 格式正文行
格式：不符合其它格式行的所有行
行首尾：无特殊约定
禁用字符：无
字符替换：< > #` 分别被替换为 < > `
内部格式：允许短代码、行代码、内链、外链、图片
说明：
示例：
源文本：
中国国内源代码托管网站有：#[gitee#](https://gitee.com)，程序员的第1行代码大多数是类似于 `print("hello world")`
实际效果：
国内源代码托管网站有：gitee，程序员的第1行代码大多数是类似于 print("hello world")
5.1. 实体替换
因为在html中，< > 有特殊含义，用于标签格式；` 在progdoc中，表示代码格式字符。
所以在绝大多数情况下，要对这三个字符进行替换。
| 原字符 | 输出替换字符 |
| < | < |
| > | > |
| #` | ` |
5.2. 短代码
格式： `AAA` A是任意字符，该字符不能是 `
行首尾：无特殊约定，开始和结尾的` 必须在同一行内。
禁用字符：` 想在短代码中用 `，用 #` 字符串来表示。
字符替换：< > #` 分别被替换为 < > `
内部格式：普通正文
说明：主要用于正文中的源代码，或者用于把其它格式字符串当普通正文处理。
示例：
源文本：
这是短代码示例，如：`逃逸 #[ [[`；或`a[i] = 5`表示数组索引。
实际效果：
这是短代码示例，如：逃逸 #[ [[；或a[i] = 5表示数组索引。
5.3. 行代码
格式： `` AAA$ A是任意字符
行首尾：无特殊约定
禁用字符：无，` 可正常输出为 ` 字符
字符替换：< > #` 分别被替换为 < > `
内部格式：普通正文
说明：从 `` 开始一直到行尾均做为代码；在表格的单元格中慎重使用，因为把 #| 当普通字符串解析。
示例：
源文本：
这是行代码示例，如：`` #|在行代码中不能当做单元格区隔来用。
实际效果：
这是行代码示例，如： #|在行代码中不能当做单元格区隔来用。
5.4. 内链
格式： [[AAA]]
行首尾：无特殊约定
禁用字符： [[ ]]
字符替换：< > #` 分别被替换为 < > `
内部格式：普通正文+短代码
说明：内链是指向文档中的锚点，在progdoc中，锚点只能是标题。注意：内链中的文本AAA须与标题完全一样，否则无效。
示例：
源文本：
progdoc的行分类参见[[4. 行分类]]。
实际效果：
progdoc的行分类参见4. 行分类。
5.5. 外链
格式： #[AAA#](BBB) AAA是外链说明，BBB是外链链接。
行首尾：无特殊约定
禁用字符：AAA中，禁用 #[ #] 字符串，BBB中，禁用( )字符。
字符替换：< > #` 分别被替换为 < > `
内部格式：AAA中是普通正文+短代码，BBB中是普通正文
说明：外链是指向外部链接的，注意：BBB尽量符合URL编码规范。
示例：
源文本：
近年来，较新的程序设计语言有#[Zig语言#](https://ziglang.org/zh/)、#[rust语言#](https://www.rust-lang.org/zh-CN/)等。
实际效果：
5.6. 图片
格式： !#[AAA#](BBB) AAA是图片说明，BBB是图片链接。
行首尾：无特殊约定
禁用字符：AAA中，禁用 #[ #] 字符串，BBB中，禁用( )字符。
字符替换：< > #` 分别被替换为 < > `
内部格式：AAA中是普通正文+短代码，BBB中是普通正文
说明：图片是指向外部链接图片的，注意：BBB尽量符合URL编码规范。
示例：
源文本：
中国第五套人民币100元图样：!#[正面#](http://www.cbpm.cn/cn/rmbpic/dwtnesw/nffl/qbnf/201911/P020220714546661471829.png)，!#[背面#](http://www.cbpm.cn/cn/rmbpic/dwtnesw/nffl/qbnf/201911/P020220714546661509320.png)
实际效果：
中国第五套人民币100元图样：
，
6. 标题行
格式： ^{数字+.}+ AAA$
行首尾：行首必须是数字开头的，不允许有空白字符
禁用字符：不建议用 [[ ]] 字符
字符替换：< > #` 分别被替换为 < > `
内部格式：只允许短代码，其它格式字符按普通字符处理
说明：为降低复杂性，及分析实际编写中的需求必要性，在progdoc格式中，锚点（即内链指向）只能是标题行。
建议写文档时，章节的篇幅尽量短少，如果章节篇幅过长，要重新考虑文章架构。
最多有六级标题，有几个句点就表示几级标题。如：1. 是一级标题； 1.5.3. 是三级标题。 2.4.3.5.7.6.8.9. 是六级标题。
每一行标题是生成一个目录项，最终生成的目录在文档的左侧边或一开始显示（根据显示屏宽度而定）。
示例：
参见本文档中的各标题。
7. 多行代码类
多行代码是指1行或1行以上以代码形式输出。
7.1. 多行代码代码行
格式： ^AAA$ AAA是任意字符
行首尾：无特殊约定
禁用字符：无
字符替换：< > 分别被替换为 < > 注意：不对#`进行替换。
内部格式：所有格式字符失效，视做普通正文
说明：多行代码行自动加行号。
示例：
源文本：
``` hello.c
#include <stdio.h>
int main(){
printf("hello world\n");
}
```
实际效果：
#include <stdio.h>
int main(){
printf("hello world\n");
}
7.2. 多行代码行S
格式： ^``` AAA$
行首尾：行首必须是```开头的，且不允许有空白字符
禁用字符：< > 建议AAA尽量是普通字符
字符替换：无
内部格式：所有格式字符失效，AAA视做普通正文
说明：AAA通常是多行代码行对应的文件名，根据文件名后缀增加输出的html文档class属性。
示例：
7.3. 多行代码行SE
格式： ^```$
行首尾：行首和行尾中间只能是```字符串，不允许有空白字符或其它字符
禁用字符：无
字符替换：无
内部格式：无
说明：如果当前不是多行代码行继续状态，则表示新开始1个多行代码行块，访代码行块没有名字；
如果当前是多行代码行继续状态，则表示结束当前多行代码行块。
多行代码行SE必须成对使用，或者和多行代码行S成对使用，否则出错。
示例：
源文本：
这是多行代码行示例：
```
for(int i=0;i<LEN;i++){
if(array[i]!='\n') array[i]++;
}
```
实际效果：
这是多行代码行示例：
for(int i=0;i<LEN;i++){
if(array[i]>MIN) array[i]++;
}
8. 列表类
单行列表行是指每一行是一个列表项。多行列表行是指一个列表项有多个连续行组成。
把列表分为单行列表行和多行列表行，以支持多级列表。
多行列表行中，仅支持普通格式正文行，不支持标题行、表格行类、多行代码行类、内嵌html行类。
多行表格行内可支持列表。
8.1. 列表行中正文内容
格式： AAA AAA是任意字符
行首尾：无特殊约定
禁用字符：无
字符替换：< > #` 分别被替换为 < > `
内部格式：与普通格式正文行一样，允许短代码、行代码、内链、外链、图片。
说明：在表格中的列表可以正确识别 #| 单元格分隔符。
示例：
源文本：
#- 列表项一
#- 列表项二
#-- 列表项三
列表项三说明文字
#- 列表项三.一
#- 列表项三.二
#-- 列表项三.三
列表项三.三说明文字
#- 列表项三.三.一
#- 列表项三.三.二
#--
#- 列表项三.四
#--
#- 列表项四
实际效果：
- 列表项一
- 列表项二
- 列表项三
列表项三说明文字- 列表项三.一
- 列表项三.二
- 列表项三.三
列表项三.三说明文字- 列表项三.三.一
- 列表项三.三.二
- 列表项三.四
- 列表项四
8.2. 单行列表行
格式： ^{空白字符+}#-AAA$ 或 #|{空白字符+}#-AAA #| ，这是表格单元格中的列表
行首尾：行首允许有空白字符
禁用字符：尽量不要用 #| 字符串，因为在表格中会当作单元格区隔。 需要用的话，用短代码方式。
字符替换：< > #` 分别被替换为 < > `
内部格式：与普通格式正文行一样，允许短代码、行代码、内链、外链、图片。
说明：单行列表行每一行是列表中的一项。
示例：
8.3. 多行列表行S
格式： ^{空白字符+}#--AAA$ 或 #|{空白字符+}#--AAA #| ，这是表格单元格中的列表
行首尾：行首允许有空白字符
禁用字符：尽量不要用 #| 字符串，因为在表格中会当作单元格区隔。 需要用的话，用短代码方式。
字符替换：< > #` 分别被替换为 < > `
内部格式：与普通格式正文行一样，允许短代码、行代码、内链、外链、图片。
说明：该行表示多行列表行的开始，即从这一行到对应的多行列表行E，之间的普通正文行和单行列表行，统一做为列表的一个列表项。
一个多行列表行S必须有一个对应的多行列表行E，反之亦然。
示例：
8.4. 多行列表行E
格式： ^{空白字符+}#--$ 或 #|{空白字符+}#--#| ，这是表格单元格中的列表
行首尾：行首允许有空白字符，行尾不允许有任何其它字符。
禁用字符：无
字符替换：无
内部格式：无
说明：该行表示多行列表行的结束。注意：行尾或单元格尾不允许有任何其它字符。
示例：
9. 表格类
表格类分为单行表格行和多行表格行，多行表格行是指一个表格行由多行组成。
区分出多行表格行主要是为了实现表格内列表。
两个不同的表格不能紧挨着，必须用其它行隔开。否则会出错。
表格行中的单元格用 #| 字符串来区隔。
行尾不必也不能用 #| 结尾。
9.1. 表格行中正文内容
格式： AAA AAA是任意字符
行首尾：无特殊约定
禁用字符：#|
字符替换：< > #` 分别被替换为 < > `
内部格式：与普通格式正文行一样，允许短代码、行代码、内链、外链、图片。注意：表格行中谨慎使用行代码，因为行代码不解析其后格式字符。
说明：
示例：
源文本：
下面是一个表格
#| aa #| bb #|> cc
#|-----------------
#| #-a1#| b1 #|^ c1
#| #-a2#| `#|` #| c2
#|-----------------
#|-----------------
#| a3 #|#--b3 #|
#|`[[` #| #-b4 #|^ c4
#| a5 #| #--#| cccccccccc
#|-----------------
实际效果：
下面是一个表格
| aa | bb | cc |
|
b1 #| |
c1 c2 |
a3 [[ a5 |
|
^ c4 cccccccccc |
9.2. 单行表格行
格式： ^#|GAAA#|GBBB...#|GNNN$ G是对齐字符 < 表示左对齐， > 表示右对齐， ^ 表示居中对齐
行首尾：行首不允许有空白字符，行尾通常不允许有#|
禁用字符：#|
字符替换：< > #` 分别被替换为 < > `
内部格式：见9.1. 表格行中正文内容
说明：单行表格行根据用途可分为：表格开始行、单独一行的表格行、多行表格开始行、多行表格后续行。
如果是表格开始行、单独一行表格行、多行表格行开始行，对齐字符有效。如果是多行表格行的后续行，则对齐字符无效，当成普通字符处理。
示例：
9.3. 多行表格行SE
格式： ^#|-AAA$ AAA是任意无用字符，不参与解析和输出，仅用于填充。
行首尾：行首不允许有空白字符，行尾的任意字符无实际用处。
禁用字符：无
字符替换：无
内部格式：无
说明：多行表格行SE成对出现，第一个多行表格行SE表示多行表格行开始，第二个多行表格行SE表示多行表格结束。
示例：
10. 内嵌html类
内嵌html类分为内嵌html多行S和内嵌html多行E。
内嵌html类不对其字符进行任何转义，直接输出。
10.1. 内嵌html中正文内容
格式： ^AAA$ AAA是任意字符
行首尾：无特殊约定
禁用字符：无
字符替换：无
内部格式：所有格式字符失效，也不进行任何替换，直接原样输出。
说明：
示例：
源文本：
#<<
<b>加粗字符串</b><br />
<i>斜体字符串</i><br />
#>>
实际效果：
加粗字符串斜体字符串
10.2. 内嵌html多行S
格式： ^#<<AAA$ AAA是任意无用字符，不参与解析和输出，仅用于填充。
行首尾：行首不允许有空白字符，行尾的任意字符无实际用处。
禁用字符：无
字符替换：无
内部格式：无
说明：内嵌html多行S和内嵌html多行E成对出现，缺一不可。
示例：
10.3. 内嵌html多行E
格式： ^#>>AAA$ AAA是任意无用字符，不参与解析和输出，仅用于填充。
行首尾：行首不允许有空白字符，行尾的任意字符无实际用处。
禁用字符：无
字符替换：无
内部格式：无
说明：内嵌html多行S和内嵌html多行E成对出现，缺一不可。
示例：
11. 作者及版权说明
编写时间：2022年11月
作者联系方式：sx_wangzhiwen@163.com；
网址：
本文档版权声明为：
本作品采用知识共享署名-非商业性使用-禁止演绎 4.0 国际许可协议进行许可。