推荐的XML DocBook格式化工具链是什么？

Question

我看到了与处理DocBook XML文档相关的最佳工具, 但我的问题略有不同。目前推荐使用哪种格式化工具链 - 而不是编辑工具 - 用于XML DocBook？在2003年出版的Eric Raymond的《Unix编程艺术》（一本很好的书！）中建议使用XML-FO（XML格式化对象），但我后来在这里看到的建议表明XML-FO不再处于开发阶段（虽然我无法在StackOverflow上找到那个问题，所以可能是错误的）。假设我主要关注Unix/Linux（包括MacOS X），但我不会自动忽略仅限于Windows的解决方案。Apache's FOP是最好的选择吗？还有其他替代方案吗？

- Jonathan Leffler

---

格式化为什么？PDF？HTML？ - bortzmeyer

PDF和HTML是两种主要格式，不确定ODF是否有意义。有时也会用到文本。由于许多建议的工具链通过Latex进行，这并不成问题。我正在考虑将使用troff（以及pic、tbl和eqn - 以及用于练习的自定义预处理器 - 章节中仅包含问题，附录中包含问题和答案）编写的旧书迁移到DocBook。还有各种程序的手册页和其他程序文档。 - Jonathan Leffler

Answer 1

我一直在使用Cygwin下的DocBook进行手动编写，以生成单页HTML、多页HTML、CHM和PDF。

我安装了以下内容：

1. DocBook 样式表（xsl）仓库。
2. xmllint，用于测试xml是否正确。
3. xsltproc，用于使用样式表处理xml。
4. Apache's fop，用于制作PDF。我确保将已安装文件夹添加到PATH环境变量中。
5. 微软的HTML帮助工具包，用于生成CHM。我确保将已安装文件夹添加到PATH环境变量中。

编辑：在下面的代码中，我正在使用超过2个文件。如果有人需要清理后的脚本和文件夹结构，请联系我：guscarreno (at) googlemail (dot) com

然后我使用 configure.in 文件：

AC_INIT(Makefile.in)

FOP=fop.sh
HHC=hhc
XSLTPROC=xsltproc

AC_ARG_WITH(fop, [  --with-fop  Where to find Apache FOP],
[
    if test "x$withval" != "xno"; then
        FOP="$withval"
    fi
]
)
AC_PATH_PROG(FOP,  $FOP)

AC_ARG_WITH(hhc, [  --with-hhc  Where to find Microsoft Help Compiler],
[
    if test "x$withval" != "xno"; then
        HHC="$withval"
    fi
]
)
AC_PATH_PROG(HHC,  $HHC)

AC_ARG_WITH(xsltproc, [  --with-xsltproc  Where to find xsltproc],
[
    if test "x$withval" != "xno"; then
        XSLTPROC="$withval"
    fi
]
)
AC_PATH_PROG(XSLTPROC,  $XSLTPROC)

AC_SUBST(FOP)
AC_SUBST(HHC)
AC_SUBST(XSLTPROC)

HERE=`pwd`
AC_SUBST(HERE)
AC_OUTPUT(Makefile)

cat > config.nice <<EOT
#!/bin/sh
./configure \
    --with-fop='$FOP' \
    --with-hhc='$HHC' \
    --with-xsltproc='$XSLTPROC' \

EOT
chmod +x config.nice

还有一个Makefile.in文件：

FOP=@FOP@
HHC=@HHC@
XSLTPROC=@XSLTPROC@
HERE=@HERE@

# Subdirs that contain docs
DOCS=appendixes chapters reference 

XML_CATALOG_FILES=./build/docbook-xsl-1.71.0/catalog.xml
export XML_CATALOG_FILES

all:    entities.ent manual.xml html

clean:
@echo -e "\n=== Cleaning\n"
@-rm -f html/*.html html/HTML.manifest pdf/* chm/*.html chm/*.hhp chm/*.hhc chm/*.chm entities.ent .ent
@echo -e "Done.\n"

dist-clean:
@echo -e "\n=== Restoring defaults\n"
@-rm -rf .ent autom4te.cache config.* configure Makefile html/*.html html/HTML.manifest pdf/* chm/*.html chm/*.hhp chm/*.hhc chm/*.chm build/docbook-xsl-1.71.0
@echo -e "Done.\n"

entities.ent: ./build/mkentities.sh $(DOCS)
@echo -e "\n=== Creating entities\n"
@./build/mkentities.sh $(DOCS) > .ent
@if [ ! -f entities.ent ] || [ ! cmp entities.ent .ent ]; then mv .ent entities.ent ; fi
@echo -e "Done.\n"

# Build the docs in chm format

chm:    chm/htmlhelp.hpp
@echo -e "\n=== Creating CHM\n"
@echo logo.png >> chm/htmlhelp.hhp
@echo arrow.gif >> chm/htmlhelp.hhp
@-cd chm && "$(HHC)" htmlhelp.hhp
@echo -e "Done.\n"

chm/htmlhelp.hpp: entities.ent build/docbook-xsl manual.xml build/chm.xsl
@echo -e "\n=== Creating input for CHM\n"
@"$(XSLTPROC)" --output ./chm/index.html ./build/chm.xsl manual.xml

# Build the docs in HTML format

html: html/index.html

html/index.html: entities.ent build/docbook-xsl manual.xml build/html.xsl
@echo -e "\n=== Creating HTML\n"
@"$(XSLTPROC)" --output ./html/index.html ./build/html.xsl manual.xml
@echo -e "Done.\n"

# Build the docs in PDF format

pdf:    pdf/manual.fo
@echo -e "\n=== Creating PDF\n"
@"$(FOP)" ./pdf/manual.fo ./pdf/manual.pdf
@echo -e "Done.\n"

pdf/manual.fo: entities.ent build/docbook-xsl manual.xml build/pdf.xsl
@echo -e "\n=== Creating input for PDF\n"
@"$(XSLTPROC)" --output ./pdf/manual.fo ./build/pdf.xsl manual.xml

check: manual.xml
@echo -e "\n=== Checking correctness of manual\n"
@xmllint --valid --noout --postvalid manual.xml
@echo -e "Done.\n"

# need to touch the dir because the timestamp in the tarball
# is older than that of the tarball :)
build/docbook-xsl: build/docbook-xsl-1.71.0.tar.gz
@echo -e "\n=== Un-taring docbook-xsl\n"
@cd build && tar xzf docbook-xsl-1.71.0.tar.gz && touch docbook-xsl-1.71.0

自动化生成上述文件输出。

我更喜欢使用nix方法来编写脚本，因为工具集更易于找到和使用，而且更容易进行链式操作。

- Gustavo Carreno

Answer 2

我们使用以下工具进行编程相关内容的编辑和处理：

• Serna XML Editor（XML编辑器）
• Eclipse（纯XML编辑，主要由技术人员使用）
• 自己专用的Eclipse插件（仅用于我们的发布说明）
• Maven docbkx插件
• Maven jar包含特定公司样式表，基于标准的docbook样式表
• Maven插件将csv转换为DocBook表格
• Maven插件从BugZilla数据中提取信息并创建一个DocBook章节
• Hudson（生成PDF文档）
• Nexus（部署生成的PDF文档）

以下是我们的一些想法：

在每个产品版本中部署不仅包括PDF，还要包括完整的原始DocBook文档（因为我们部分编写文档，部分生成文档）。保存完整的DocBook文档使它们独立于未来系统设置的更改。这意味着，如果提取内容的系统发生更改（或被其他系统替换），我们将无法再生成完全相同的内容。如果我们需要重新发布（使用不同的样式表）整个产品手册系列，这可能会导致问题。与JAR文件一样；这些已编译的Java类也放置在Nexus中（您不希望将它们存储在源代码管理器中）；我们也会将生成的DocBook文档放置在其中。

更新：Fresh创建了一个Maven HTML清理插件，可以将DocBook内容添加到Maven项目站点中（Beta版本可用）。欢迎通过“开放讨论”论坛提供反馈。

- Verhagen

Answer 3

我们使用XMLmind XmlEdit进行编辑，并使用Maven的docbkx插件在构建过程中生成输出。如需一组优秀的模板，请查看Hibernate或Spring提供的模板。请注意，我们保留了HTML标签。

- Oliver Drotbohm

---

+1 for the docbkx Maven插件，它提供了一切必要的工具以平台无关的方式处理DocBook。即使您不是在Java项目上工作，这仍然是一个绝佳的工具。http://code.google.com/p/docbkx-tools - Emmanuel Bourg

Answer 4

对于HTML输出，我使用具有XSLT处理器xsltproc的Docbook XSL样式表。

对于PDF输出，我使用dblatex，它将其转换为LaTeX，然后使用pdflatex编译为PDF。（之前我使用过Jade，DSSSL样式表和jadetex。）

- bortzmeyer

---

从jadetex转换到dblatex的原因是什么？质量更好吗？ - schoetbi

Answer 5

DocBook样式表加上FOP的效果不错，但我最终决定购买RenderX，它更全面地覆盖了标准，并具有一些DocBook样式表所利用的不错扩展功能。

Bob Stayton的书，DocBook XSL：完全指南，描述了几个备选工具链，包括适用于Linux或Windows（几乎肯定也适用于MacOS，尽管我个人没有使用过Mac）的工具链。

- Dick

Answer 6

如果你正在使用Red Hat、Ubuntu或Windows，你可以看一下Publican这个命令行工具链，它被认为是相当完整的。Red Hat广泛使用它。

• 维基请参考：https://fedorahosted.org/publican/
• 文档请参考：http://jfearn.fedorapeople.org/Publican/
• 源代码tarballs和exes请参考：https://fedorahosted.org/releases/p/u/publican/

- uman

Answer 7

这篇文章名为DocBook工具链，可能也很有用。它是由Eric Raymond写的关于DocBook的HOWTO指南的一部分。

- Ishan De Silva

Answer 8

使用FOP，您可以获得某些人认为非常重要并实现的功能。我会说，没有一个严肃的出版物专业人士在生产中使用它。您最好选择RenderX、Antenna House或Arbortext。 （在过去十年的实施项目中，我使用了它们所有。）这取决于您的业务需求、您想要自动化多少以及您团队的技能、时间和资源等情况。这不仅仅是一个技术问题。

- Liz Fraley

Answer 9

一种流行的方法是使用DocBook XSL 样式表。

- Jim

Answer 10

关于Apache FOP的问题：当我们建立了类似Gustavo建议的工具链时，使用RenderX XEP引擎可以获得非常好的结果。XEP的输出看起来更加精美，据我回忆，FOP在表格方面存在一些问题（虽然这是几年前的事情，现在可能已经改变）。

- Palmin