Какой набор инструментов рекомендуется использовать для форматирования XML DocBook?
Я видел лучшие инструменты для работы с документами DocBook XML, но мой вопрос немного другой. Какой набор инструментов форматирования рекомендуется использовать в отличие от инструмента редактирования для XML DocBook?
В книге Эрика Рэймонда " Искусство программирования на Unix" от 2003 года (отличная книга!) Предлагается XML-FO (объекты форматирования XML), но с тех пор я видел здесь предложения, указывающие на то, что XML-FO больше не разрабатывается. (хотя я больше не могу найти этот вопрос в Stackru, так что, возможно, он был ошибочным).
Предположим, что я в первую очередь интересуюсь Unix/Linux (включая MacOS X), но я не буду автоматически игнорировать решения только для Windows.
Является ли Apache FOP лучшим способом? Есть ли альтернативы?
13 ответов
Я работал с DocBook под Cygwin, чтобы создать одностраничный HTML, многостраничный HTML, CHM и PDF.
Я установил следующее:
- Хранилище стилей docbook (xsl).
- xmllint, чтобы проверить правильность XML.
- xsltproc, для обработки xml с помощью таблиц стилей.
- Apache fop, для создания PDF. Я обязательно добавляю установленную папку в PATH.
- HTML Help Workshop от Microsoft для создания 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-подход к написанию сценариев только потому, что набор инструментов проще найти и использовать, не говоря уже о том, что его легче связать.
Мы используем XMLmind XmlEdit для редактирования и плагин Maven docbkx для создания выходных данных во время наших сборок. Для набора хороших шаблонов взгляните на те, которые предоставляют Hibernate или Spring.
Для вывода HTML я использую таблицы стилей Docbook XSL с процессором XSLT xsltproc.
Для вывода PDF я использую dblatex, который переводится в LaTeX, а затем использую pdflatex, чтобы скомпилировать его в PDF. (Ранее я использовал Jade, таблицы стилей DSSSL и jadetex.)
Мы используем
- Serna XML Editor
- Eclipse (простое редактирование XML, в основном используется техническими специалистами)
- собственный специальный плагин Eclipse (только для наших заметок о выпуске)
- Плагин Maven docbkx
- Кувшин Maven со специальной таблицей стилей, основанной на стандартных таблицах стилей docbook
- Плагин Maven для преобразования CSV в таблицу DocBook
- Плагин Maven для извлечения данных BugZilla и создания из него раздела DocBook
- Хадсон (для создания PDF документа (ов))
- Nexus для развертывания созданных документов PDF
Некоторые идеи у нас есть:
Развертывайте с каждой версией продукта не только PDF, но и исходный полный документ DocBook (так как мы частично пишем документ и частично генерируем их). Сохранение полного документа DocBook делает их независимыми для изменений в настройках системы в будущем. Это означает, что если система изменится, из которой контент был извлечен (или заменен другими системами), мы больше не сможем генерировать точный контент. Что может вызвать проблему, если нам потребуется переиздать (с другой таблицей стилей) весь набор руководств по продукту. Так же, как с банками; эти скомпилированные классы Java также размещены в Nexus (вы не хотите хранить их в своем SCM); это мы также сделаем с сгенерированным документом DocBook.
Обновить:
Fresh создал плагин Maven HTML Cleaner, который позволяет добавлять контент DocBook на сайт проекта Maven (доступна бета-версия). Обратная связь приветствуется через открытый дискуссионный форум.
Таблицы стилей DocBook, плюс FOP, работают хорошо, но я, наконец, решил использовать RenderX, который более подробно охватывает стандарт и имеет несколько приятных расширений, которыми пользуются таблицы стилей DocBook.
Книга Боба Стэйтона, DocBook XSL: Полное руководство, описывает несколько альтернативных цепочек инструментов, включая те, которые работают на Linux или Windows (почти наверняка MacOS, хотя я лично не использовал Mac).
С FOP вы получаете функции, которые кто-то решил, что они хотели бы реализовать достаточно плохо. Я бы сказал, что никто, кто серьезно относится к публикации, не использует его в производстве. Вам гораздо лучше с RenderX, Antenna House или Arbortext. (Я использовал их все за последние 10 лет реализации проектов.) Это зависит от ваших бизнес-требований, от того, насколько вы хотите автоматизировать работу, а также от того, на что похожи навыки, время и ресурсы вашей команды. Это не просто вопрос технологии.
Если вы работаете в Red Hat, Ubuntu или Windows, вы можете взглянуть на Publican, который должен быть довольно полным набором инструментов командной строки. Red Hat использует это широко.
- Вики здесь: https://fedorahosted.org/publican/
- Док здесь: http://jfearn.fedorapeople.org/Publican/
- Исходные архивы и exes здесь: https://fedorahosted.org/releases/p/u/publican/
Популярным подходом является использование таблиц стилей DocBook XSL.
Я использовал два утилиты CLI для упрощения моей цепочки инструментов docbook: xmlto и publican.
Publican выглядит элегантно для меня, но достаточно подходит для публикации в Fedora и Redhat.
Статья под названием DocBook toolchain также может быть полезна. Это раздел HOWTO по DocBook, написанный Эриком Рэймондом.
Что касается вопроса о FOP Apache: когда мы создали наш набор инструментов (аналогично тому, что предлагал Густаво), у нас были очень хорошие результаты с использованием механизма RenderX XEP. Вывод XEP выглядит немного более отточенным, и, насколько я помню, у FOP были некоторые проблемы с таблицами (хотя это было несколько лет назад, но это могло измениться).
Я выпускаю / работаю над проектом с открытым исходным кодом, называемым bookshop, который представляет собой RubyGem, устанавливающий полный конвейер / набор инструментов Docbook-XSL. Он включает в себя все необходимое для создания и редактирования исходных файлов Docbook и вывода различных форматов (в настоящее время pdf и epub, и быстро растет).
Моя цель - сделать так, чтобы переход от нуля к экспорту (pdf или любой другой) из источника в Docbook был сделан менее чем за 10 минут.
Резюме:
bookShop - это основанная на рубрике платформа OSS для счастья и устойчивой производительности docbook. Платформа оптимизирована, чтобы помочь разработчикам быстро наращивать скорость, позволяя им быстрее подключаться и развивать свои потоки DocBook-to-Output, предпочитая соглашение по конфигурации, настраивая их с помощью передовых методов, стандартов и инструментов с самого начала.,
Вот местоположение драгоценного камня: https://rubygems.org/gems/bookshop
И исходный код: https://github.com/blueheadpublishing/bookshop
Я предпочитаю использовать Windows для создания большей части моего контента (редактор Notepad++). Publican в Linux - это хорошая цепочка инструментов для создания хорошей структуры документации и вывода результатов процесса. Я использую Dropbox (есть и другие службы обмена документами, которые должны хорошо работать на обеих платформах) на моей машине с Windows, а также на машине с Virtual Linux. С помощью этой настройки я смог получить комбинацию, которая прекрасно работает для меня. Когда работа по редактированию завершена в Windows (которая сразу синхронизируется с машиной Linux), я переключаюсь на Linux, чтобы запустить сборку publican и создавать выходные данные HTML и PDF, которые снова обновляются в моей папке Windows с помощью Dropbox.