1 如何构建 OTP 风格的文档

1.1 用于准备 XML 文件的工具

从代码创建 XML 文件

如果模块中有 EDoc 注释，则可以使用 escript xml_from_edoc.escript 根据 erlref DTD 为此模块生成 XML 文件。

示例

	1> escript $ERL_TOP/lib/erl_docgen/priv/bin/xml_from_edoc.escript ex1.erl

在 XML 中包含代码

如果源 XML 文件中包含 OTP DTD 的 codeinclude 标签，则可以使用 escript codeline_preprocessing.escript 包含代码并根据 OTP DTD 生成 XML 文件。

示例

	1> escript $ERL_TOP/lib/erl_docgen/priv/bin/codeline_preprocessing.escript \
	   ex1.xmlsrc ex1.xml

1.2 使用 xsltproc 生成不同的输出格式

所有 XSL 转换中使用的参数

这些 xsltproc 参数用于所有支持的输出格式。

docgen: erl_docgen 的顶级目录路径。
gendate: 将在文档中使用的日期字符串。
appname: 应用程序的名称。>
appver: 应用程序的版本。

生成 HTML 输出

生成 HTML 时，还需要为 xsltproc 提供以下三个参数。

outdir: 生成的 html 文件的输出目录。
topdocdir: 如果为应用程序构建独立文档，则应将其设置为 "."。
pdfdir: 从 html 目录到放置 pdf 文件的位置的相对路径。

示例

	1> xsltproc --noout --stringparam outdir /tmp/myhtmldoc \
	      --stringparam docgen $ERL_TOP/lib/erl_docgen \
              --stringparam topdocdir . \
              --stringparam pdfdir $PDFDIR \
              --xinclude \
	      --stringparam gendate "December 5 2011" \
              --stringparam appname MyApp \
              --stringparam appver 0.1 \
              -path $ERL_TOP/lib/erl_docgen/priv/dtd \
              -path $ERL_TOP/lib/erl_docgen/priv/dtd_html_entities \
	      $ERL_TOP/lib/erl_docgen/priv/xsl/db_html.xsl mybook.xml

生成 PDF

生成 PDF 文件分两个步骤完成。首先使用 xsltproc 生成 .fo 文件，该文件用作 fop 命令的输入以生成 PDF 文件。

示例

	1> xsltproc --output MyApp.fo \
             --stringparam docgen $ERL_TOP/lib/erl_docgen \
	     --stringparam gendate  "December 5 2011" \
             --stringparam appname MyApp \
             --stringparam appver 0.1 \
             --xinclude \
             -path $ERL_TOP/lib/erl_docgen/priv/dtd \
             -path $ERL_TOP/lib/erl_docgen/priv/dtd_html_entities \
	     $ERL_TOP/lib/erl_docgen/priv/xsl/db_pdf.xsl mybook.xml


        2> fop -fo MyApp.fo -pdf MyApp.pdf

生成手册页

可以使用 xsltproc 从根据不同 OTP ref 类型 DTD 编写的 XML 文件中生成 Unix 手册页。

示例

	1> xsltproc --output  my_module.3\
	      --stringparam docgen $ERL_TOP/lib/erl_docgen \
	      --stringparam gendate  "December 5 2011" \
	      --stringparam appname MyApp \
	      --stringparam appver 0.1 \
	      --xinclude -path $ERL_TOP/lib/erl_docgen/priv/dtd  \
              -path $ERL_TOP/lib/erl_docgen/priv/dtd_man_entities \
              $ERL_TOP/lib/erl_docgen/priv/xsl/db_man.xsl my_refpage.xml

即将发生的更改

erl_docgen 文档构建过程的输出现在仅为 OTP 风格。但在不久的将来，我们将例如添加更改 PDF 中的徽标、颜色以及 HTML 的样式表的功能。