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

Question

我见过使用DocBook XML文档的最佳工具,但我的问题略有不同.对于XML DocBook,目前推荐的格式化工具链 - 而不是编辑工具？

Eric Raymond的"Unix编程艺术"(一本优秀的书!)中,建议是XML-FO(XML格式化对象),但我在此看到的建议表明XML-FO不再处于开发阶段(虽然我无法再在StackOverflow上找到这个问题,所以可能是错误的).

假设我主要对Unix/Linux(包括MacOS X)感兴趣,但我不会自动忽略仅限Windows的解决方案.

是Apache的FOP去的最佳途径？还有其他选择吗？

Answer 1

在cygwin下,我一直在用DocBook进行一些手工编写,以生成One Page HTML,Many Pages HTML,CHM和PDF.

我安装了以下内容:

1. 在DocBook的样式表(XSL)资源库.
2. xmllint,用于测试xml是否正确.
3. xsltproc,用样式表处理xml.
4. Apache的fop,用于生成PDF.我确保将已安装的文件夹添加到PATH中.
5. 微软的HTML帮助研讨会,生产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方法编写脚本,因为工具集更容易查找和使用,更不用说链接了.

Answer 2

我们使用XMLmind XmlEdit进行编辑,使用Maven的docbkx插件在构建期间创建输出.对于一组好的模板,请看一下Hibernate或Spring提供的模板.

Answer 3

对于HTML输出,我使用Docbook XSL样式表和XSLT处理器xsltproc.

对于PDF输出,我使用dblatex,它转换为LaTeX,然后使用pdflatex将其编译为PDF.(之前我使用过Jade,DSSSL样式表和jadetex.)

Answer 4

我们用

• Serna XML编辑器
• Eclipse(纯xml编辑,主要由技术人员使用)
• 拥有特定的Eclipse插件(仅适用于我们的发行说明)
• Maven docbkx插件
• 具有特定公司样式表的Maven jar,基于标准docbook样式表
• 用于将csv转换为DocBook表的Maven插件
• Maven插件,用于提取BugZilla数据并从中创建DocBook部分
• 哈德森(生成PDF文件)
• Nexus部署创建的PDF文档

我们有一些想法:

使用每个产品版本部署不仅包括PDF,还包括原始完整的DocBook文档(因为我们部分编写文档并部分生成它们).保存完整的DocBook文档使它们将来可以独立于系统设置的更改.意思是,如果系统发生变化,内容被从中提取(或由差异系统替换),我们将无法再生成确切的内容.这可能会导致问题,如果我们需要重新发布(使用不同的样式表)整个产品手册.与罐子相同; 这些已编译的Java类也放在Nexus中(您不希望将它们存储在SCM中); 我们也会使用生成的DocBook文档.

更新:

Fresh创建了一个Maven HTML Cleaner插件,可以将DocBook内容添加到Maven项目站点(可用的Beta版本).欢迎通过公开讨论论坛提供反馈.