¿Cuál es la cadena de herramientas recomendada para formatear XML DocBook?[cerrado]

https://stackoverflow.com/questions/122752

02-07-2019
|

Pregunta

He visto Las mejores herramientas para trabajar con documentos DocBook XML, pero mi pregunta es ligeramente diferente.¿Cuál es la cadena de herramientas de formato recomendada actualmente (a diferencia de la herramienta de edición) para XML DocBook?

En casa de Eric Raymond 'El arte de la programación Unix' de 2003 (¡un libro excelente!), la sugerencia es XML-FO (Objetos de formato XML), pero desde entonces he visto sugerencias aquí que indican que XML-FO ya no está en desarrollo (aunque ya no puedo encontrar esa pregunta en StackOverflow, así que tal vez fue un error).

Supongamos que estoy interesado principalmente en Unix/Linux (incluido MacOS X), pero no ignoraría automáticamente las soluciones exclusivas de Windows.

Es FOP de Apache ¿el mejor camino a seguir?¿Hay alguna alternativa?

Solución

He estado escribiendo un poco manualmente con DocBook, bajo cygwin, para producir HTML de una página, HTML de muchas páginas, CHM y PDF.

Instalé lo siguiente:

El libro de documentos Repositorio de hojas de estilo (xsl).
xmllint, para probar si el xml es correcto.
xsltproc, para procesar el xml con las hojas de estilo.
El petimetre de Apache, para producir archivos PDF. Me aseguro de agregar la carpeta instalada a la RUTA.
Microsoft Taller de ayuda HTML, para producir CHM.Me aseguro de agregar la carpeta instalada a la RUTA.

Editar:En el siguiente código estoy usando más de 2 archivos.Si alguien quiere una versión limpia de los scripts y la estructura de carpetas, comuníquese conmigo:guscarreno (squiggly/at) googlemail (punto/punto) com

Luego uso un 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

y un 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

para automatizar la producción de los archivos mencionados anteriormente.

Prefiero usar un enfoque nix para las secuencias de comandos solo porque el conjunto de herramientas es más fácil de encontrar y usar, sin mencionar que es más fácil de encadenar.

Otros consejos

Usamos XMLmind Xml para edición y Maven docbkx complemento para crear resultados durante nuestras compilaciones.Para obtener un conjunto de buenas plantillas, eche un vistazo a las que Hibernar o Primavera proporcionar.

Para la salida HTML, uso el Hojas de estilo Docbook XSL con el procesador XSLT xsltproc.

Para la salida PDF, uso dblatex, que se traduce a LaTeX y luego usa pdflatex para compilarlo en PDF.(Antes usé Jade, las hojas de estilo DSSSL y jadetex).

Usamos

Editor XML de Serna
Eclipse (edición xml simple, utilizada principalmente por técnicos)
propio complemento específico de Eclipse (solo para nuestras notas de versión)
Complemento Maven docbkx
Jar Maven con hoja de estilo corporativa específica, basada en las hojas de estilo estándar de Docbook
Complemento Maven para convertir csv a tabla DocBook
Complemento Maven para extraer datos de BugZilla y crear una sección DocBook a partir de ellos
Hudson (para generar los documentos PDF)
Nexus para implementar los documentos PDF creados

Algunas ideas que tenemos:

Implemente con cada versión del producto no solo el PDF, sino también el documento DocBook completo original (ya que en parte escribimos el documento y en parte lo generamos).Guardar el documento DocBook completo los hace independientes para cambios en la configuración del sistema en el futuro.Es decir, si cambia el sistema del cual se extrajo el contenido (o se reemplazó por diff.sistemas) ya no podríamos generar el contenido exacto.Lo que podría causar un problema si necesitáramos volver a publicar (con hojas de estilo diferentes) toda la gama de manuales del producto.Lo mismo que con los frascos;estas clases Java compiladas también se colocan en Nexus (no desea almacenarlas en su SCM);Esto también lo haríamos con el documento DocBook generado.

Actualizar:

Recién creado un Complemento de limpieza HTML de Maven, lo que permite agregar contenido de DocBook a un sitio de proyecto Maven (Versión Beta disponible).Los comentarios son bienvenidos a través del Discusión abierta Foro.

Las hojas de estilo de DocBook, además de FOP, funcionan bien, pero finalmente decidí optar por RenderX, que cubre el estándar más a fondo y tiene algunas extensiones interesantes que aprovechan las hojas de estilo de DocBook.

El libro de Bob Stayton, DocBook XSL:La guía completa, describe varias cadenas de herramientas alternativas, incluidas algunas que funcionan en Linux o Windows (casi seguramente también en MacOS, aunque personalmente no he usado una Mac).

Un método popular es utilizar Hojas de estilo DocBook XSL.

Respecto a la pregunta sobre el FOP de Apache:cuando establecimos nuestra cadena de herramientas (similar a lo que Gustavo ha sugerido) obtuvimos muy buenos resultados usando el Motor RenderX XEP.La salida de XEP parece un poco más pulida y, hasta donde recuerdo, FOP tuvo algunos problemas con las tablas (aunque esto fue hace unos años, esto podría haber cambiado).

Con FOP obtienes las características que alguien decidió que quería implementar.Yo diría que nadie que se tome en serio la publicación lo utiliza en producción.Estás mucho mejor con RenderX o Antenna House o Arbortexto.(Los he usado en todos los proyectos de implementación de la última década). Depende de los requisitos de su negocio, de cuánto desea automatizar y de las habilidades, el tiempo y los recursos de su equipo.No es sólo una cuestión de tecnología.

Si está en Red Hat, Ubuntu o Windows, puede echarle un vistazo a Publican, que se supone que es una cadena de herramientas de línea de comandos bastante completa.Red Hat lo utiliza ampliamente.

Wiki aquí: https://fedorahosted.org/publican/
Doctor aquí: http://jfearn.fedorapeople.org/Publican/
Fuente tarballs y exes aquí: https://fedorahosted.org/releases/p/u/publican/

El artículo llamado La cadena de herramientas DocBook podría ser útil también.Es una sección de un CÓMO en DocBook escrito por Eric Raymond.

He estado usando dos utilidades CLI para simplificar mi cadena de herramientas de docbook:xmlto y publicano.

Publican me parece elegante pero lo suficientemente adecuado para las necesidades de publicación de Fedora y Redhat.

Lancé/estoy trabajando en un proyecto de código abierto llamado librería, que es un RubyGem que instala una cadena de herramientas/canalización Docbook-XSL completa.Incluye todo lo necesario para crear y editar archivos fuente de Docbook y generar diferentes formatos (actualmente pdf y epub, y está creciendo rápidamente).

Mi objetivo es hacer posible pasar de cero a exportar (pdf o lo que sea) desde su fuente Docbook en menos de 10 minutos.

El resumen:

bookShop es un marco OSS basado en Ruby para la felicidad de la cadena de herramientas de docbook y la productividad sostenible.El marco está optimizado para ayudar a los desarrolladores a avanzar rápidamente, permitiéndoles lanzarse y desarrollar más rápidamente sus flujos de DocBook a salida, favoreciendo la convención sobre la configuración, configurándolos con las mejores prácticas, estándares y herramientas desde el principio. .

Aquí está la ubicación de la joya: https://rubygems.org/gems/bookshop

Y el código fuente: https://github.com/blueheadpublishing/bookshop

Prefiero usar Windows para la mayor parte de mi creación de contenido (editor Notepad++).Publican en Linux es una buena cadena de herramientas para crear una buena estructura de documentación y resultados de procesos.Utilizo Dropbox (también existen otros servicios para compartir documentos, que deberían funcionar bien en ambas plataformas) en mi máquina Windows, así como en mi máquina Virtual Linux.Con esta configuración he podido lograr una combinación que me funciona muy bien.Una vez que se completa el trabajo de edición en Windows (que se sincroniza inmediatamente con la máquina Linux), cambio a Linux para ejecutar publican build y crear resultados HTML y PDF, que nuevamente se actualizan en mi carpeta de Windows mediante Dropbox.

Licenciado bajo: CC-BY-SA con atribución

No afiliado a StackOverflow