Какой набор инструментов рекомендуется использовать для форматирования XML DocBook?[закрыто]

https://stackoverflow.com/questions/122752

02-07-2019
|

Вопрос

я видел Лучшие инструменты для работы с XML-документами DocBook, но у меня вопрос немного другой.Какой набор инструментов форматирования рекомендуется в настоящее время (в отличие от инструмента редактирования) для XML DocBook?

У Эрика Рэймонда «Искусство программирования для Unix» из 2003 года (отличная книга!), предлагается XML-FO (объекты форматирования XML), но с тех пор я видел здесь предложения, в которых указывалось, что XML-FO больше не находится в разработке (хотя я больше не могу найти этот вопрос на StackOverflow, так что, возможно, это была ошибка).

Предположим, меня в первую очередь интересуют Unix/Linux (включая MacOS X), но я бы не стал автоматически игнорировать решения только для Windows.

Является ФОП Apache лучший способ пойти?Есть ли альтернативы?

Решение

Я писал руководства с помощью DocBook под Cygwin для создания одностраничного HTML, многостраничного HTML, CHM и PDF.

Я установил следующее:

А документация Репозиторий таблиц стилей (xsl).
xmllint, чтобы проверить правильность XML.
xsltproc, для обработки XML с таблицами стилей.
щеголь Apache, для создания PDF-файлов. Я обязательно добавляю установленную папку в PATH.
Microsoft Справочный семинар по HTML, для производства CHM.Я обязательно добавляю установленную папку в PATH.

Редактировать:В приведенном ниже коде я использую более двух файлов.Если кому-то нужна подчищенная версия скриптов и структуры папок, обращайтесь:guscarreno (волнистая линия/at) googlemail (точка/точка) 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 XmlПравить для редактирования и Maven docbkx плагин для создания вывода во время наших сборок.Чтобы найти набор хороших шаблонов, обратите внимание на те, которые Спящий режим или Весна предоставлять.

Для вывода HTML я использую Таблицы стилей Docbook XSL с процессором XSLT xsltproc.

Для вывода PDF я использую дблатекс, который преобразуется в LaTeX, а затем используется pdflatex для компиляции его в PDF.(Раньше я использовал Jade, таблицы стилей DSSSL и jadetex.)

Мы используем

XML-редактор Serna
Eclipse (простое редактирование XML, в основном используется техническими специалистами)
собственный специальный плагин Eclipse (только для наших примечаний к выпуску)
Плагин Maven docbkx
Jar Maven со специальной таблицей корпоративных стилей, основанной на стандартных таблицах стилей docbook.
Плагин Maven для преобразования csv в таблицу DocBook
Плагин Maven для извлечения данных BugZilla и создания из них раздела DocBook
Хадсон (для создания PDF-документов))
Nexus для развертывания созданных PDF-документов

Некоторые идеи у нас есть:

Развертывайте с каждой версией продукта не только PDF-файл, но и исходный полный документ DocBook (поскольку мы частично пишем документ, а частично его генерируем).Сохранение полного документа DocBook делает их независимыми от изменений в настройке системы в будущем.То есть, если изменится система, из которой был извлечен контент (или заменен на diff.системы) мы больше не сможем генерировать точный контент.Это могло бы вызвать проблему, если бы нам нужно было перевыпустить (с другой таблицей стилей) весь набор руководств по продукту.То же, что и с банками;эти скомпилированные классы Java также помещаются в Nexus (вы не хотите хранить их в своем SCM);то же самое мы могли бы сделать и с созданным документом DocBook.

Обновлять:

Свежий создал Плагин Maven HTML Cleaner, что позволяет добавить содержимое DocBook на сайт проекта Maven (Доступна бета-версия).Обратная связь приветствуется через Открытая дискуссия Форум.

Таблицы стилей DocBook, а также FOP работают хорошо, но в конце концов я решил остановиться на RenderX, который более подробно охватывает стандарт и имеет несколько хороших расширений, которыми пользуются таблицы стилей DocBook.

Книга Боба Стейтона, Документ XSL:Полное руководство, описывает несколько альтернативных цепочек инструментов, в том числе те, которые работают в Linux или Windows (почти наверняка и в MacOS, хотя лично я не использовал Mac).

Популярный подход заключается в использовании Таблицы стилей DocBook XSL.

Что касается вопроса о FOP Apache:когда мы создали нашу цепочку инструментов (аналогично тому, что предложил Густаво), мы получили очень хорошие результаты, используя Движок RenderX XEP.Вывод XEP выглядит немного более отточенным, и, насколько я помню, у FOP были некоторые проблемы с таблицами (хотя это было несколько лет назад, возможно, что-то изменилось).

С FOP вы получаете функции, которые кто-то решил реализовать достаточно сильно.Я бы сказал, что никто из тех, кто серьезно относится к издательскому делу, не использует его в производстве.Вам гораздо лучше использовать RenderX, Antenna House или Арбортекст.(Я использовал их во всех проектах внедрения за последнее десятилетие.) Это зависит от ваших бизнес-требований, от того, насколько вы хотите автоматизировать, а также от навыков, времени и ресурсов вашей команды.Это не просто технологический вопрос.

Если вы используете Red Hat, Ubuntu или Windows, вы можете взглянуть на Publican, который должен представлять собой довольно полную цепочку инструментов командной строки.Red Hat широко его использует.

Вики здесь: https://fedorahosted.org/publican/
Док здесь: http://jfearn.fedorapeople.org/Publican/
Исходные файлы и исполняемые файлы здесь: https://fedorahosted.org/releases/p/u/publican/

Статья под названием Набор инструментов DocBook может быть и полезно.Это часть КАК в DocBook, написанный Эриком Рэймондом.

Я использовал две утилиты CLI для упрощения своей цепочки инструментов docbook:xmlto и publican.

Publican кажется мне элегантным, но достаточно подходящим для нужд публикаций Fedora и Redhat.

Я выпускаю/работаю над проектом с открытым исходным кодом под названием книжный магазин, который представляет собой RubyGem, который устанавливает полный конвейер/цепочку инструментов Docbook-XSL.Он включает в себя все необходимое для создания и редактирования исходных файлов Docbook и вывода различных форматов (в настоящее время pdf и epub, число которых быстро растет).

Моя цель — сделать возможным переход от нулевого экспорта к экспорту (pdf-файлов или чего-то еще) из вашего источника Docbook менее чем за 10 минут.

Резюме:

bookShop — это платформа OSS на Ruby, обеспечивающая счастье и устойчивую производительность в наборе инструментов docbook.Платформа оптимизирована, чтобы помочь разработчикам быстро приступить к работе, позволяя им быстрее приступить к разработке потоков DocBook-to-Output, отдавая предпочтение соглашениям, а не конфигурации, настраивая их с использованием лучших практик, стандартов и инструментов с самого начала. .

Вот расположение драгоценного камня: https://rubygems.org/gems/bookshop

И исходный код: https://github.com/blueheadpublishing/bookshop

Я предпочитаю использовать Windows для создания большей части контента (редактор Notepad++).Publican в Linux — это хорошая цепочка инструментов для создания хорошей структуры документации и обработки результатов.Я использую Dropbox (есть и другие службы обмена документами, которые должны хорошо работать на обеих платформах) на своем компьютере с Windows, а также на компьютере с виртуальным Linux.С помощью этой настройки я смог добиться комбинации, которая отлично работает для меня.Как только работа по редактированию завершена в Windows (которая немедленно синхронизируется с машиной Linux), я переключаюсь на Linux, чтобы запустить сборку Publican и создать выходные данные HTML и PDF, которые снова обновляются в моей папке Windows с помощью Dropbox.

Лицензировано под: CC-BY-SA с атрибуция

Не связан с StackOverflow