前面所展示的firstbook.xml
这个文件只是一个架构,如果所有的内容全部写好后,是非常长的一个文件。一个人编写非常大的一个文件是非常恼人的事情,更不用说多人来共同创作了。所以我们需要将文档进行分割,通常情况下,会把一个chapter或一个section放在一个文件里面,例如,firstbook.xml
,我们把它分为四章,这样就变成了5个文件,一个firstbook.xml
和四个“章文件”。下面是我们这份手册的目录树。
chunxin@CC$ tree firstbook/ firstbook/ ├── chapters │ ├── chapter01_beginning.xml │ ├── chapter02_xml.xml │ ├── chapter03_xsl.xml │ └── chapter04_fonts.xml ├── firstbook.xml ├── colophon.xml ├── info.xml └── preface.xml
要完成这种分割,需要做两件事,在firstbook.xml
定义各个章节文件,然后单独完成每个章节的编撰。在目录树中,还有几个其他的文件:info.xml
、preface.xml
和colophon.xml
,他们分别是关于“书”的一些信息、“序言”和“后记”。
这个部分是在前面我们描述的“头”部分完成的,在根元素之前,在DTD声明之后。定义好之后,在适当的位置引用他们,那么我们的firstbook.xml
l真实的样子就诞生了,如下的样子:
1 <?xml version="1.0" encoding="utf-8"?> 2 <!DOCTYPE book [ 3 <!ENTITY info SYSTEM "info.xml"> 4 <!ENTITY preface SYSTEM "preface.xml"> 5 6 <!ENTITY chapter01_beginning SYSTEM "chapters/chapter01_beginning.xml"> 7 <!ENTITY chapter02_xml SYSTEM "chapters/chapter02_xml.xml"> 8 <!ENTITY chapter03_xsl SYSTEM "chapters/chapter03_xsl.xml"> 9 <!ENTITY chapter04_fonts SYSTEM "chapters/chapter04_fonts.xml"> 10 11 <!ENTITY colophon SYSTEM "chapters/colophon.xml"> 12 ]> 13 14 <book xmlns:xlink='http://www.w3.org/1999/xlink' 15 xmlns="http://docbook.org/ns/docbook" 16 xml:lang="zh_cn" 17 version="5.0"> 18 19 <title>docbook简要参考⼿册</title> 20 <subtitle>DocBook 5.0 and XSLT 1.0 Stylesheet</subtitle> 21 &info; 22 &preface; 23 24 &chapter01_beginning; 25 &chapter02_xml; 26 &chapter03_xsl; 27 &chapter04_fonts; 28 29 &colophon; 30 </book>
分割好以后就有点文档工程的味道了。接下来就是完成各个章节的撰写。章节的撰写相对firstbook.xml
来讲就相对简单里,不需要那些定义和声明,只要按照标准的docbook规范来书写就可以了。在这里以第一章为例来说明,如下:
1 <chapter><title>制作第一份docbook文档</title> 2 <para>前面已经提到过,docbook主要分为SGML和XML两个版本,... ...</para> 3 <para>docbook的入门是有一定门槛的,... ...</para> 4 <orderedlist> 5 <listitem><emphasis>XML文档</emphasis> 6 <para>首先,需要按照docbook DTD的规范要求,... ...</para> 7 </listitem> 8 <listitem><emphasis>XSL样式表</emphasis> 9 <para>有了docbook格式的xml文件之后,... ...</para> 10 </listitem> 11 <listitem><emphasis>字体</emphasis> 12 <para>有几种类型的字体需要我们提前准备好主要包括sans、serif、monospace等。后面会有详细的介绍。</para> 13 </listitem> 14 <listitem><emphasis>处理程序</emphasis> 15 <para>有了docbook格式的文件、docbook-xsl样式表及字体,... ...</para> 16 </listitem> 17 </orderedlist> 18 </chapter>
其他的章节也是按照这样的方式来撰写。
这个文件里面包含了“书”的很多信息,主要是作者、版本信息、发行信息、出版日期等。
1 <info> 2 3 <corpauthor>****信息科技有限公司</corpauthor> 4 <author><firstname>Li </firstname><surname>Lawrence</surname></author> 5 <pubdate>2021年9月18日</pubdate> 6 7 <copyright> 8 <year>2021</year> 9 <holder>ChunXin Li</holder> 10 </copyright> 11 12 <legalnotice><title>legalnotice </title> 13 <para>... ...</para> 14 </legalnotice> 15 16 <revhistory> 17 <revision> 18 <revnumber>1.0</revnumber> 19 <date>2021年8月28日</date> 20 <authorinitials>ddpt</authorinitials> 21 <revremark>发布第二个Draft</revremark> 22 </revision> 23 24 <revision> 25 <revnumber>1.0</revnumber> 26 <date>2021年9月8日</date> 27 <authorinitials>ddpt</authorinitials> 28 <revremark>发布第一个Draft</revremark> 29 </revision> 30 </revhistory> 31 32 <releaseinfo><para>This document was generated by chunxin.</para></releaseinfo> 33 <abstract><title>摘要</title> 34 <para>docware是基于docbook的一套文档发布工具... ...</para> 35 </abstract> 36 </info>
这个例子里只是展示了一部分,关于书的信息(标签)还有很多,可以根据自己的需求添加或减少。
这两个文件是一本“书”的序言和后记。一般情况下也不是必须的。可以把喜欢的一些“引子”之类的东西写在序言里,把后续要做的或一些花絮写在后记里。
在book里,可以把preface和colophon标签看成和chapter是一样的,preface.xml大致如下的样子:
1 <preface><title>写在前面</title> 2 <para>在接触到docbook之前,写一些计算机技术相关的一些文档,对我来说是件很辛苦的事情。</para> 3 <itemizedlist> 4 <listitem>该用什么样的一些样式展示不同的一些文档元素?如一些代码、或者系统命令等。</listitem> 5 <listitem>如何保证同样的文档元素总是保持一样的显示风格?</listitem> 6 <listitem>如何进行版式的一些设计?用word来排版对我来说实在太痛苦。</listitem> 7 <listitem>如何让文档能够同时生成在线阅读的版本和可以打印的版本?</listitem> 8 <listitem>如何完成多人协作书写,又同时保证样式的完全一致?</listitem> 9 </itemizedlist> 10 <para>还有就是诸如如何进行版本控制等... ...</para> 11 </preface>
colophon.xml大致如下的样子:
1 <colophon><title>结束语</title> 2 <para>... ...</para> 3 </colophon>