格式化XML DocBook的推荐工具链是什么?[关闭]

我在Cygwin的帮助下,用DocBook做了一些手工写作,以生成一页HTML、多页HTML、CHM和PDF。

我安装了以下内容:

1. 这个 docbook 样式表(XSL)存储库。
2. xmllint,测试XML是否正确。
3. 用样式表处理XML。
4. Apache's fop ,以生成PDF。我确保将已安装的文件夹添加到路径中。
5. 微软 HTML Help Workshop ,以生成chm。我确保将已安装的文件夹添加到路径中。

编辑 :在下面的代码中,我使用了两个以上的文件。如果有人想要一个清理版本的脚本和文件夹结构,请联系我:guscareno(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方法来编写脚本,因为工具集更容易找到和使用,更不用说更容易链接。

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

对于HTML输出,我使用 Docbook XSL stylesheets 使用xslt处理器xsltproc。

对于PDF输出,我使用 dblatex ,转换为乳胶,然后使用pdf latex将其编译为pdf。(我以前用过jade、dsssl样式表和jadetex。)

我们使用

• Serna XML Editor
• Eclipse(纯XML编辑,主要由技术人员使用)
• 拥有特定的Eclipse插件(仅用于我们的发行说明)
• Maven Docbkx插件
• 基于标准DocBook样式表,带有特定公司样式表的Maven JAR
• 用于将csv转换为docbook表的maven插件
• 用于提取Bugzilla数据并从中创建DocBook部分的Maven插件
• Hudson(生成PDF文档)
• nexus部署创建的PDF文档

我们的一些想法:

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

更新:

新鲜创造了一个 Maven HTML Cleaner插件 这使得 add DocBook content to a Maven Project Site (提供测试版)。欢迎通过 Open Discussion 论坛。

一种流行的方法是 DocBook XSL Stylesheets .

DocBook样式表,加上FOP,工作得很好,但是我最终决定使用renderx,它更全面地覆盖了标准,并且有一些DocBook样式表所利用的很好的扩展。

鲍勃·斯泰顿的书, DocBook XSL: The Complete Guide ,描述了几个替代的工具链,包括在Linux或Windows上工作的工具链(几乎可以肯定的是,MacOS也是,尽管我个人没有使用过Mac)。

文章称 The DocBook toolchain 可能也有用。它是A的一部分 HOWTO 在埃里克·雷蒙德写的教科书上。

关于Apache的FOP问题:当我们建立了我们的工具链(类似于Gustavo的建议)时,使用 RenderX XEP engine . Xeps的输出看起来有点精妙,据我所知,FOP在表方面有一些问题(这是几年前的事了,但可能已经改变了)。

有了FOP,你就得到了一些人认为他们需要的功能,这些功能不足以实现。我要说的是,没有一个认真对待出版的人在制作中使用它。你在renderx或天线房里过得更好 Arbortext . (我在过去十年的实施项目中一直使用它们。)这取决于您的业务需求、您希望自动化的程度,以及您团队的技能、时间和资源是什么样的。这不仅仅是一个技术问题。

如果您使用的是RedHat、Ubuntu或Windows,您可以看看Publican,它应该是一个相当完整的命令行工具链。红帽广泛使用。

• 维基在这里: https://fedorahosted.org/publican/
• 博士: http://jfearn.fedorapeople.org/Publican/
• 资料来源:tarballs和exes https://fedorahosted.org/releases/p/u/publican/

我使用了两个cli实用程序来简化DocBook工具链:xmlto和publican。

Publican在我看来很优雅,但足以满足Fedora和Redhat出版物的需求。

• https://fedorahosted.org/xmlto/
• https://fedorahosted.org/publican/

我正在开发一个名为Bookshop的开源项目,它是一个安装完整DocBookXSL管道/工具链的Rubygem。它包括创建和编辑DocBook源文件和输出不同格式(当前为PDF和EPUB,并且增长迅速)所需的一切。

我的目标是在不到10分钟的时间内从0导出到DocBook源文件(PDF或其他文件)。

总结:

书店是一个基于OSS Ruby的DocBook工具链快乐和可持续生产力框架。该框架经过优化以帮助开发人员快速升级,允许他们更快速地进入并开发DocBook到输出流,方法是支持约定而不是配置,从一开始就为他们设置最佳实践、标准和工具。

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

源代码: https://github.com/blueheadpublishing/bookshop

我更喜欢使用Windows来创建大部分内容(记事本+编辑器)。Linux中的publican是一个很好的工具链,可以创建良好的文档结构和处理输出。我在我的Windows机器和虚拟Linux机器上使用Dropbox(还有其他的文档共享服务,在这两个平台上都可以很好地工作)。 有了这个设置,我就能够实现一个对我来说很好的组合。 一旦在Windows中完成编辑工作(它会立即同步到Linux机器),我就切换到Linux来运行Publican Build,并创建HTML和PDF输出,这些输出会在我的Windows文件夹中被Dropbox更新。