24

我见过Best tools for working with DocBook XML 文档，但我的问题略有不同。当前推荐的 XML DocBook 格式化工具链（与编辑工具相对）是哪个？

在 Eric Raymond 的2003 年的“The Art of Unix Programming”（一本优秀的书！）中，建议是 XML-FO（XML 格式化对象），但我在这里看到的建议表明 XML-FO 不再处于开发阶段（虽然我在 StackOverflow 上找不到那个问题，所以可能是错误的）。

假设我主要对 Unix/Linux（包括 MacOS X）感兴趣，但我不会自动忽略仅限 Windows 的解决方案。

Apache 的 FOP是最好的方法吗？有没有其他选择？

4

13 回答 13

14

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

我安装了以下内容：

  1. docbook样式表(xsl) 存储库。
  2. xmllint，测试 xml 是否正确。
  3. xsltproc，使用样式表处理 xml。
  4. Apache 的 fop，用于生成 PDF。我确保将安装的文件夹添加到 PATH。
  5. Microsoft 的HTML Help Workshop，用于制作 CHM 的。我确保将安装的文件夹添加到 PATH。

编辑：在下面的代码中，我使用的不仅仅是 2 个文件。如果有人想要脚本和文件夹结构的清理版本，请联系我：guscarreno (squiggly/at) googlemail (period/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 方法编写脚本，只是因为工具集更容易找到和使用，更不用说更容易链接。

于 2008-09-23T18:40:46.950 回答
7

我们使用XMLmind XmlEdit进行编辑，并使用 Maven 的docbkx插件在构建期间创建输出。有关一组好的模板，请查看Hibernate或Spring提供的模板。

于 2009-05-17T17:25:57.020 回答
7

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

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

于 2009-05-18T19:19:59.267 回答
7

我们用

  • Serna XML 编辑器
  • Eclipse（纯xml编辑，多为技术人员使用）
  • 自己的特定 Eclipse 插件（仅用于我们的发行说明）
  • Maven docbkx 插件
  • 具有特定公司样式表的 Maven jar，基于标准 docbook 样式表
  • 用于将 csv 转换为 DocBook 表的 Maven 插件
  • 用于提取 BugZilla 数据并从中创建 DocBook 部分的 Maven 插件
  • Hudson（生成 PDF 文档）
  • Nexus 部署创建的 PDF 文档

我们有一些想法：

部署每个产品版本不仅是 PDF，还包括原始完整的 DocBook 文档（因为我们部分编写文档并部分生成它们）。保存完整的 DocBook 文档使它们独立于未来系统设置的更改。这意味着，如果系统发生变化，从中提取内容（或被差异系统替换），我们将无法再生成确切的内容。如果我们需要重新发布（使用不同的样式表）整个产品系列的手册，这可能会导致问题。和罐子一样；这些已编译的 Java 类也放在 Nexus 中（您不想将它们存储在 SCM 中）；我们也将使用生成的 DocBook 文档来执行此操作。

更新：

Fresh 创建了一个Maven HTML Cleaner Plug-in，它可以将 DocBook 内容添加到 Maven 项目站点（提供 Beta 版）。欢迎通过开放讨论论坛提供反馈。

于 2010-01-29T20:52:19.853 回答
4

DocBook 样式表和 FOP 运行良好，但我最终决定选择 RenderX，它更全面地涵盖了标准并且有一些 DocBook 样式表利用的不错的扩展。

Bob Stayton 的书DocBook XSL: The Complete Guide描述了几个替代工具链，包括在 Linux 或 Windows 上工作的工具链（几乎可以肯定是 MacOS，尽管我没有亲自使用过 Mac）。

于 2008-11-05T18:24:54.983 回答
3

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

于 2008-09-23T18:24:11.233 回答
3

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

于 2008-09-23T19:49:47.567 回答
3

使用 FOP，您可以获得某些人认为他们想要实现的功能。我想说，没有一个认真对待出版的人在生产中使用它。使用 RenderX 或 Antenna House 或Arbortext会好得多。（在过去十年的实施项目中，我一直在使用它们。）这取决于您的业务需求、您想要自动化的程度，以及您的团队的技能、时间和资源情况。这不仅仅是一个技术问题。

于 2010-03-08T17:44:26.010 回答
3

如果你使用的是 Red Hat、Ubuntu 或 Windows，你可以看看 Publican，它应该是一个相当完整的命令行工具链。Red Hat 广泛使用它。

于 2010-06-12T22:15:08.250 回答
3

名为The DocBook toolchain的文章也可能很有用。它是Eric Raymond 在 DocBook 上编写的HOWTO的一部分。

于 2012-05-24T23:31:51.030 回答
3

我一直在使用两个 CLI 实用程序来简化我的 docbook 工具链：xmlto 和 publican。

Publican 对我来说看起来很优雅，但足以满足 Fedora 和 Redhat 的发布需求。

于 2012-10-22T20:22:45.313 回答
2

我发布/正在开发一个名为 bookshop 的开源项目，它是一个安装完整 Docbook-XSL 管道/工具链的 RubyGem。它包括创建和编辑 Docbook 源文件和输出不同格式（当前为 pdf 和 epub，并且发展迅速）所需的一切。

我的目标是在 10 分钟内从您的 Docbook 源中实现从零到导出（pdf 或其他）。

摘要：

bookShop 是一个基于 OSS ruby​​ 的框架，用于 docbook 工具链的快乐和可持续的生产力。该框架经过优化，可帮助开发人员快速升级，使他们能够更快地加入并开发他们的 DocBook-to-Output 流程，通过支持约定优于配置，从一开始就为他们设置最佳实践、标准和工具.

这是宝石的位置：https ://rubygems.org/gems/bookshop

以及源代码：https ://github.com/blueheadpublishing/bookshop

于 2011-03-28T21:20:20.020 回答
1

我更喜欢在我的大部分内容创建（Notepad++ 编辑器）中使用 Windows。Linux 中的 Publican 是一个很好的工具链，可以创建良好的文档结构和流程输出。我在我的 Windows 机器和虚拟 Linux 机器上使用 Dropbox（还有其他文档共享服务，应该在两个平台上都可以正常工作）。通过这种设置，我已经能够实现对我来说非常有用的组合。一旦在 Windows 中完成编辑工作（立即同步到 Linux 机器），我切换到 Linux 运行 publican build 并创建 HTML 和 PDF 输出，这些输出再次由 Dropbox 在我的 Windows 文件夹中更新。

于 2013-09-02T05:51:26.840 回答