2. 将文档物理分割

前面所展示的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.xmlpreface.xmlcolophon.xml,他们分别是关于“书”的一些信息、“序言”和“后记”。

  1. 各个文件的定义

    这个部分是在前面我们描述的“头”部分完成的,在根元素之前,在DTD声明之后。定义好之后,在适当的位置引用他们,那么我们的firstbook.xmll真实的样子就诞生了,如下的样子:

      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>
  2. 单独书写各个章节

    分割好以后就有点文档工程的味道了。接下来就是完成各个章节的撰写。章节的撰写相对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>

    其他的章节也是按照这样的方式来撰写。

  3. info.xml

    这个文件里面包含了“书”的很多信息,主要是作者、版本信息、发行信息、出版日期等。

      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>

    这个例子里只是展示了一部分,关于书的信息(标签)还有很多,可以根据自己的需求添加或减少。

  4. preface.xml和colophon.xml

    这两个文件是一本“书”的序言和后记。一般情况下也不是必须的。可以把喜欢的一些“引子”之类的东西写在序言里,把后续要做的或一些花絮写在后记里。

    在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>