PostgreSQL的学习心得和知识总结（七十五）|深入理解PostgreSQL数据库文档说明及代码提交SGML文档编辑制作方法
目录结构
注：提前言明 本文借鉴了以下博主、书籍或网站的内容，其列表如下：
1、参考书籍：《PostgreSQL数据库内核分析》
2、参考书籍：《数据库事务处理的艺术：事务管理与并发控制》
3、PostgreSQL数据库仓库链接，点击前往
4、日本著名PostgreSQL数据库专家 铃木启修 网站主页，点击前往
5、参考书籍：《PostgreSQL 在线用户手册 Appendix J. Documentation，点击前往》
6、参考书籍：《PostgreSQL指南：内幕探索》，点击前往
7、参考书籍：《事务处理 概念与技术》
8、GNU Emacs An extensible, customizable, free/libre text editor — and more.，点击前往
1、本文内容全部来源于开源社区 GitHub和以上博主的贡献，本文也免费开源（可能会存在问题，评论区等待大佬们的指正）
2、本文目的：开源共享 抛砖引玉 一起学习
3、本文不提供任何资源 不存在任何交易 与任何组织和机构无关
4、大家可以根据需要自行 复制粘贴以及作为其他个人用途，但是不允许转载 不允许商用 （写作不易，还请见谅 💖）
5、本文内容基于PostgreSQL14.2源码开发而成
深入理解PostgreSQL数据库文档说明及代码提交SGML文档编辑制作方法
- 文章快速说明索引
- 文档说明工具介绍
-
- DocBook语言
- 工具集的介绍
- 文档编译以及编辑
文章快速说明索引
学习目标：
做数据库内核开发久了就会有一种 少年得志，年少轻狂 的错觉，然鹅细细一品觉得自己其实不算特别优秀 远远没有达到自己想要的。也许光鲜的表面掩盖了空洞的内在，每每想到于此，皆有夜半临渊如履薄冰之感。为了睡上几个踏实觉，即日起 暂缓其他基于PostgreSQL数据库的兼容功能开发，近段时间 将着重于学习分享Postgres的基础知识和实践内幕。
备注1：
遇一本好书，很难得
读一本好书，很重要
我给大家推荐一本书：《PostgreSQL指南：内幕探索》，点击前往
备注2：大家在给PostgreSQL开源社区提交代码的时候，不仅仅是数据库内核 工具周边的代码提交，而且更为重要的一项就是：补充或修改 文档！示例如下：
备注3：如上commit是我的一位微信好友 成都文武信息技术有限公司主页，点击前往 的开发人员所提交，之后我会对这次的commit进行详细的原理介绍和一些新的想法的补充说明！
学习内容：（详见目录）
1、深入理解PostgreSQL数据库文档说明及代码提交SGML文档编辑制作方法
学习时间：
2022年04月14日 10:55:37
学习产出：
1、PostgreSQL数据库基础知识回顾 1个
2、CSDN 技术博客 1篇
3、PostgreSQL数据库内核深入学习
注：下面我们所有的学习环境是Centos7+PostgreSQL14.2+Oracle11g+MySQL8.0
postgres=# select version();version----------------------------------------------------------------------------- PostgreSQL 14.2 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 7.1.0, 64-bit(1 row)postgres=# \dx List of installed extensions Name | Version | Schema | Description -----------+---------+------------+------------------------------------------------------------ plpgsql | 1.0 | pg_catalog | PL/pgSQL procedural language tablefunc | 1.0 | public | functions that manipulate whole tables, including crosstab(2 rows)postgres=# #-----------------------------------------------------------------------------#SQL> select * from v$version;BANNER--------------------------------------------------------------------------------Oracle Database 11g Enterprise Edition Release 11.2.0.1.0 - 64bit ProductionPL/SQL Release 11.2.0.1.0 - ProductionCORE11.2.0.1.0ProductionTNS for Linux: Version 11.2.0.1.0 - ProductionNLSRTL Version 11.2.0.1.0 - ProductionSQL>#-----------------------------------------------------------------------------#mysql> select version();+-----------+| version() |+-----------+| 8.0.27 |+-----------+1 row in set (0.06 sec)mysql>文档说明工具介绍
PostgreSQL有四种主要的文档格式：
- 纯文本，用于安装前信息
- HTML，用于在线浏览和参考
- PDF，用于打印
- 手册页，用于快速参考
另外，在PostgreSQL源码树里面还有许多纯文本风格的README文件，它们记录各种实现问题。 HTML文档和手册页是标准发布的一部分并且被默认安装。PDF格式的文档可以独立地下载。
DocBook语言
文档源码是用DocBook编写的，它是一种用XML定义的标记语言。在下文中，虽然术语 DocBook 和XML都被使用，但在技术上它们是不能互换的。 DocBook允许作者指定一份技术文档的结构和内容，而不需要关心表现的细节。一份文档风格定义其内容如何呈现为几种最终形式之一。DocBook.org 主页，点击前往
sudo yum install pandocsudo yum install texlive-xetex texlive texlive-science示例如下：
[postgres@local64:~]$ cat myDocbook.xml <article xmlns='http://docbook.org/ns/docbook'> <info> <title>My first docbook document</title> <author><personname> <firstname>song</firstname> <surname>baobao</surname> </personname></author> <publisher><publishername>https://rng-songbaobao.blog.csdn.net/?type=blog</publishername></publisher> <pubdate>2022</pubdate> </info><section id="intro"> <title>Introduction</title> <para>Introductory text goes here.</para> </section><section id="body"> <title>Section with a title</title> <para>Main body text goes here.</para> </section><section id="conclusion"> <title>Conclusion</title> <para>Exciting and inspiring conclusion goes here.</para> </section> </article>[postgres@local64:~]$ pandoc --from docbook --to html --output myDocbook.html myDocbook.xml[postgres@local64:~]$ [postgres@local64:~]$ pandoc --from docbook --to latex --output myDocbook.pdf myDocbook.xml[postgres@local64:~]$ [postgres@local64:~]$ lsjson-v3.10.4 myDocbook.html myDocbook.pdf myDocbook.xml mystudy patch pgNodeGraph postgres test.c v3.10.4?format=tar.gz[postgres@local64:~]$
关于DocBook的介绍就到这里，有兴趣的小伙伴们可以去看一下这篇文档：An introduction to DocBook, a flexible markup language worth learning，点击前往
工具集的介绍
在 Fedora、RHEL 和衍生品上安装 所需的包，如下：
sudo yum install docbook-dtds docbook-style-xsl fop libxslt
[postgres@local64:~/postgres → REL_14_2]$ ./configure --prefix=/home/postgres/test --enable-debug
文档编译以及编辑
一旦你把所有的东西都设置好以后，切换到doc/src/sgml目录，并且运行下面小节中介绍的命令之一就可以编译文档（记住使用 GNU make）。
关于文档编译的，主要有以下几种：
- HTML
要编译文档的HTML版本：
[postgres@local64:~/postgres/doc/src/sgml → REL_14_2]$ make html{ \ echo "<!ENTITY version \"14.2\">"; \ echo "<!ENTITY majorversion \"14\">"; \} > version.sgml'/usr/bin/perl' ./mk_feature_tables.pl YES ../../../src/backend/catalog/sql_feature_packages.txt ../../../src/backend/catalog/sql_features.txt > features-supported.sgml'/usr/bin/perl' ./mk_feature_tables.pl NO ../../../src/backend/catalog/sql_feature_packages.txt ../../../src/backend/catalog/sql_features.txt > features-unsupported.sgml'/usr/bin/perl' ./generate-errcodes-table.pl ../../../src/backend/utils/errcodes.txt > errcodes-table.sgml'/usr/bin/perl' ./generate-keywords-table.pl . > keywords-table.sgml/usr/bin/xmllint --path . --noout --valid postgres.sgml/usr/bin/xsltproc --path . --stringparam pg.version '14.2' stylesheet.xsl postgres.sgmlcp ./images/genetic-algorithm.svg ./images/pagelayout.svg ./images/gin.svg html/cp ./stylesheet.css html/touch html-stamp[postgres@local64:~/postgres/doc/src/sgml → REL_14_2]$
这也是默认的目标。这个命令的输出将出现在子目录html中。查看一下，如下：
要用postgresql.org所使用的样式表 而不是默认的简单样式生成 HTML 文档：
doc/src/sgml$ make STYLE=website html如果使用STYLE=website选项，生成的 HTML 文件包括对托管在postgresql.org 上的样式表的引用，需要网络访问来查看。
- MAN
我们使用 DocBook XSL 样式表来把DocBook refentry页转换成适合于手册页的 *roff 输出。要创建手册页，使用命令：
doc/src/sgml$ make man要使用FOP产生文档的PDF版本，可以使用下列命令之一，取决于你喜欢的纸张格式：
doc/src/sgml$ make postgres-A4.pdfdoc/src/sgml$ make postgres-US.pdf[postgres@local64:~/postgres/doc/src/sgml → REL_14_2]$ make postgres-A4.pdf/usr/bin/xmllint --path . --noout --valid postgres.sgml/usr/bin/xsltproc --path . --stringparam pg.version '14.2' --stringparam img.src.path './' --stringparam paper.type A4 -o postgres-A4.fo stylesheet-fo.xsl postgres.sgmlMaking portrait pages on A4 paper (210mmx297mm)/usr/bin/fop -fo postgres-A4.fo -pdf postgres-A4.pdfApr 14, 2022 2:32:03 PM org.apache.fop.apps.FOUserAgent processEventWARNING: Font "Symbol,normal,700" not found. Substituting with "Symbol,normal,400"....示例如下：
- 纯文本文件
安装指导也被发布为纯文本，它们被用于那些没有好的阅读工具的情况。INSTALL文件对应于第 17 章，但针对不同的环境做了小幅修改。要重建该文件，切换到目录doc/src/sgml并输入make INSTALL。 编译文本输出需要Pandoc 1.13或更高版本作为附加编译工具。
在过去，发行注记和回归测试指导也被作为纯文本发布，但是事实上已经没有这样做了。
[postgres@local64:~/postgres/doc/src/sgml → REL_14_2]$ make INSTALL{ \ echo "<!ENTITY version \"14.2\">"; \ echo "<!ENTITY majorversion \"14\">"; \} > version.sgml'/usr/bin/perl' ./mk_feature_tables.pl YES ../../../src/backend/catalog/sql_feature_packages.txt ../../../src/backend/catalog/sql_features.txt > features-supported.sgml'/usr/bin/perl' ./mk_feature_tables.pl NO ../../../src/backend/catalog/sql_feature_packages.txt ../../../src/backend/catalog/sql_features.txt > features-unsupported.sgml'/usr/bin/perl' ./generate-errcodes-table.pl ../../../src/backend/utils/errcodes.txt > errcodes-table.sgml'/usr/bin/perl' ./generate-keywords-table.pl . > keywords-table.sgml/usr/bin/xsltproc --path . --stringparam pg.version '14.2' --xinclude standalone-profile.xsl standalone-install.xml >INSTALL.xml/usr/bin/xmllint --noout --valid INSTALL.xml/usr/bin/xsltproc --stringparam pg.version '14.2' stylesheet-text.xsl INSTALL.xml >INSTALL.htmlpandoc -t plain -o INSTALL.tmp INSTALL.htmliconv -f utf8 -t us-ascii//TRANSLIT INSTALL.tmp > INSTALLrm INSTALL.tmp[postgres@local64:~/postgres/doc/src/sgml → REL_14_2]$ 
如上的文档编译，可能会花很长时间。但是有办法只检查文档中的语法，这个过程只需要数秒：
[postgres@local64:~/postgres/doc/src/sgml → REL_14_2]$ make check{ \ echo "<!ENTITY version \"14.2\">"; \ echo "<!ENTITY majorversion \"14\">"; \} > version.sgml'/usr/bin/perl' ./mk_feature_tables.pl YES ../../../src/backend/catalog/sql_feature_packages.txt ../../../src/backend/catalog/sql_features.txt > features-supported.sgml'/usr/bin/perl' ./mk_feature_tables.pl NO ../../../src/backend/catalog/sql_feature_packages.txt ../../../src/backend/catalog/sql_features.txt > features-unsupported.sgml'/usr/bin/perl' ./generate-errcodes-table.pl ../../../src/backend/utils/errcodes.txt > errcodes-table.sgml'/usr/bin/perl' ./generate-keywords-table.pl . > keywords-table.sgml/usr/bin/xmllint --path . --noout --valid postgres.sgml[postgres@local64:~/postgres/doc/src/sgml → REL_14_2]$示例如下：
OK，这里.sgml文档都是文本文档，我们可以使用任何喜欢的编辑器进行开发，诸如 vim 等。官方用户手册上面推荐的工具：
- GNU Emacs
文档的源码可以很方便地用具有XML编辑模式的编辑器来修改，而如果它们懂一些XML模式语言那就更好了，那样它们就能理解专门的DocBook语法。 注意由于历史原因，文档源文件被命名为以扩展名.sgml结尾，尽管它们现在都是XML文件。因此你可能需要调整你的编辑器配置来设置正确的模式。
OK，这里我给大家推荐的是 Vscode，这才是YYDS，如下(安装XML扩展，并选择右下角的语言模式为：xml)：
make postgres-A4.pdf如下：
关于大家在补充文档的时候，请遵守文档格式指南：
参考页面应遵循标准布局
这使用户可以更快地找到所需的信息，并且还鼓励编写者记录命令的所有相关方面
不仅需要在PostgreSQL参考页面之间保持一致，而且还需要与操作系统和其他软件包提供的参考页面保持一致
因此，制定了以下指南。它们在很大程度上与各种操作系统建立的类似准则一致
- J.5. Style Guide，点击前往
创作挑战赛 
新人创作奖励来咯，坚持创作打卡瓜分现金大奖中国大学排行榜
