6.5. 注释callout

例 6.11. programlisting的callout:programlistingco


<programlistingco>
    <programlisting language="c">
static struct platform_driver s3c2410_nand_driver = {
	.probe<co id="co.probe" linkends="co.note.probe" />		= s3c2410_nand_probe,
	.remove<co id="co.remove" linkends="co.note.remove" />		= s3c2410_nand_remove,
	.suspend<co id="co.suspend" linkends="co.note.suspend" />	= s3c24xx_nand_suspend,
	.resume<coref linkend="co.suspend" />		= s3c24xx_nand_resume,
	.driver		= {
		.name	= "s3c2410-nand",
		.owner	= THIS_MODULE,
	},
};
    </programlisting>
    <calloutlist>
        <callout id="co.note.probe" arearefs="co.probe" >
            <para>probe就是系统“探测”,就是前面解释的整个过程,这个过程中的多数步骤,都是和你自己的Nand Flash相关的,尤其是那些硬件初始化部分,是你必须要自己实现的。</para>
        </callout>
        <callout id="co.note.remove" arearefs="co.remove" >
            <para>remove,就是和probe对应的,“反初始化”相关的动作。主要是释放系统相关资源和关闭硬件的时钟等常见操作了。</para>
        </callout>
        <callout id="co.note.suspend" arearefs="co.suspend" >
            <para>suspend和resume,对于很多没用到电源管理的情况下,至少对于我们刚开始写基本的驱动的时候,可以不用关心,放个空函数即可。</para>
        </callout>
    </calloutlist>
</programlistingco>

            

对应的screenco,就是把programlistingco和programlisting换为screenco和screen即可。

screenco举例如下:

例 6.12. screen的callout:screenco


    <screenco>
        <screen>
crosstool-ng-1.18.0<co id="co.ctng_src_folder" linkends="co.note.ctng_src_folder" />
crosstool-ng-1.18.0_build<co id="co.ctng_build_folder" linkends="co.note.ctng_build_folder" />
src<co id="co.download_src_folder" linkends="co.note.download_src_folder" />
x-tools<co id="co.x_tools_folder" linkends="co.note.x_tools_folder" />
crosstool-ng-1.18.0.tar.bz2<co id="co.ctng_tar_file" linkends="co.note.ctng_tar_file" />
        </screen>
        <calloutlist>
            <callout id="co.note.ctng_src_folder" arearefs="co.ctng_src_folder" >
                <para>crosstool-ng的源码包:<xref linkend="co.ctng_tar_file" />,解压后的文件夹</para>
                <para>包含了crosstool-ng的相关源码</para>
            </callout>
            <callout id="co.note.ctng_build_folder" arearefs="co.ctng_build_folder" >
                <para>专门为后期使用crosstool-ng去建立交叉编译器,的编译(build),而专门建立的文件夹</para>
                <para>对应的,后续的<command>ct-ng menuconfig</command>,<command>ct-ng build</command>等命令,都是在此文件夹下执行的。</para>
                <para></para>
            </callout>
            <callout id="co.note.download_src_folder" arearefs="co.download_src_folder" >
                <para>为crosstool-ng中,后续需要下载各种软件的源码包,而准备的,</para>
                <para>crosstool-ng中,在开始执行build之后,会去下载对应的源码包,都会存放到这个文件夹下</para>
                <para></para>
            </callout>
            <callout id="co.note.x_tools_folder" arearefs="co.x_tools_folder" >
                <para>这个文件夹,是,用crosstool-ng所生成的交叉编译器,所在的路径。</para>
                <para>对应的配置中,会有,类似于:</para>
                <screen>(${HOME}/develop/crosstool-ng/x-tools/${CT_TARGET}) Prefix directory</screen>
                <para>的配置,用来指定生成的交叉编译器,存放在何处。</para>
                <para>此时,就是去设置为此处对应的路径即可。</para>
            </callout>
            <callout id="co.note.ctng_tar_file" arearefs="co.ctng_tar_file" >
                <para>很明显,这个就是之前我在折腾crosstool-ng-1.18.0时,去下载的源码包了。</para>
                <para>对应的上面的<xref linkend="co.ctng_src_folder" />,就是此源码包解压后的路径。</para>
                <para></para>
            </callout>
        </calloutlist>
    </screenco>

            

对应的table中添加callout,就是在table的任意位置使用co,然后再table之外使用calloutlist+callout即可。

下面这个例子,是自己摸索出来的,通过在任意位置使用co,然后别处直接可以使用coref引用该co,且不一定需要对应的callout和calloutlist:

例 6.13. 没有callout的co实现在任意位置使用co然后在别处使用coref去引用


<orderedlist>
    <listitem><emphasis>Evacuation</emphasis><co id="co.evacuation" linkends="co.note.evacuation" /> procedures are implemented whenever the fire alarms have been activated.</listitem>
    <listitem>The following rules and policies are binding for every employee who works at the <emphasis>premises</emphasis><co id="co.premises" linkends="co.note.premises" /> of M&amp;M Software (Suzhou) GmbH</listitem>
</orderedlist>

<table xml:id="tbl.eng_words_1_20"><title>1-20单词的含义</title>
    <tgroup cols="4">
        <colspec colnum="1" colname="col1" colwidth="1*" />
        <colspec colnum="2" colname="col2" colwidth="2*" />
        <colspec colnum="3" colname="col3" colwidth="2*" />
        <colspec colnum="4" colname="col4" colwidth="4*" />
    
        <thead align="center">
            <row><entry>序号</entry><entry>英文单词</entry><entry>中文含义</entry><entry>说明注释</entry></row>
        </thead>
        
        <tbody>
            <row><entry><coref linkend="co.evacuation" id="co.note.evacuation" /></entry><entry>evacuation</entry><entry>疏散,撤离</entry><entry>指失火了,要逃离的情况</entry></row>
            <row><entry><coref linkend="co.premises" id="co.note.premises" /></entry><entry>premises</entry><entry>经营场所</entry><entry>此处是公司地址,场所的意思</entry></row>
        </tbody>
    </tgroup>
</table>

            

不过目前此种用法,有个小bug,那就是生成的HTML中鼠标虽可点击,但是无法跳转,不过生成的PDF中是正常的支持鼠标点击co和coref互相跳转的。