Quelle est la chaîne d'outils recommandée pour formater XML DocBook? [fermé]

StackOverflow https://stackoverflow.com/questions/122752

Était-ce utile?

La solution

Je suis en train d'écrire manuellement avec DocBook, sous cygwin, pour produire du code HTML à une page, plusieurs pages HTML, CHM et PDF.

J'ai installé ce qui suit:

  1. Le référentiel docbook (xsl).
  2. xmllint, pour vérifier si le code XML est correct.
  3. xsltproc, pour traiter le XML avec les feuilles de style.
  4. fop d'Apache , pour produire des PDF. Je m'assure d'ajouter le dossier installé au CHEMIN.
  5. Aide en ligne HTML / a>, pour produire des CHM. Je veille à ajouter le dossier installé à la variable PATH.

Modifier : dans le code ci-dessous, j'utilise plus que les 2 fichiers. Si quelqu'un veut une version nettoyée des scripts et de la structure des dossiers, merci de me contacter: guscarreno (squiggly / at) googlemail (period / dot) com

J'utilise ensuite un fichier 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

et 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

pour automatiser la production des sorties de fichiers susmentionnées.

Je préfère utiliser une approche nix du script simplement parce que les outils sont plus faciles à trouver et à utiliser, sans parler de leur facilité de chaînage.

Autres conseils

Nous utilisons XMLmind XmlEdit pour l'édition et docbkx plug-in pour créer une sortie lors de nos générations. Pour un ensemble de bons modèles, jetez un coup d'œil à ceux Hibernate ou Printemps fourni.

Pour la sortie HTML, j'utilise les feuilles de style Docbook XSL avec le processeur xsltproc. XSLT.

Pour la sortie PDF, j'utilise dblatex , qui est traduit en LaTeX, puis utilisé pdflatex pour le compiler au format PDF. . (J'ai utilisé Jade, les feuilles de style DSSSL et jadetex auparavant.)

Nous utilisons

  • Editeur XML Serna
  • Eclipse (édition XML simple, principalement utilisée par les techniciens)
  • propre plug-in Eclipse spécifique (uniquement pour nos notes de version)
  • plug-in Maven docbkx
  • Un pot Maven avec une feuille de style spécifique, basée sur les feuilles de style docbook standard
  • Plug-in Maven pour la conversion de csv en table DocBook
  • Plug-in Maven pour extraire des données BugZilla et créer une section DocBook à partir de celle-ci
  • Hudson (pour générer le ou les documents PDF)
  • Nexus va déployer les documents PDF créés

Quelques idées que nous avons:

Déployez avec chaque version du produit non seulement le PDF, mais également le document DocBook complet original (car nous écrivons et générons en partie le document). L'enregistrement de l'intégralité du document DocBook les rend indépendants des modifications futures de la configuration du système. Cela signifie que si le système change, à partir duquel le contenu est extrait (ou remplacé par différents systèmes), nous ne serons plus en mesure de générer le contenu exact. Ce qui pourrait poser problème si nous devions rééditer (avec une feuille de style différente) tout le ranche de manuels du produit. Identique aux bocaux ces classes Java compilées sont également placées dans Nexus (vous ne voulez pas les stocker dans votre SCM); nous ferions également cela avec le document DocBook généré.

Mise à jour:

Fresh a créé un plug-in Maven HTML Cleaner , qui permet de ajouter du contenu DocBook à un site de projet Maven (version bêta disponible). Les commentaires sont les bienvenus via le forum Open Discussion .

Les feuilles de style DocBook, ainsi que FOP, fonctionnent bien, mais j’ai finalement décidé de me lancer dans RenderX, qui couvre la norme de manière plus approfondie et comporte quelques extensions intéressantes dont les feuilles de style DocBook tirent parti.

Le livre de Bob Stayton, DocBook XSL: Le Guide complet , décrit plusieurs chaînes d'outils alternatives, y compris ceux qui fonctionnent sous Linux ou Windows (presque sûrement aussi avec MacOS, même si je n'ai pas personnellement utilisé un Mac).

Une approche populaire consiste à utiliser les feuilles de style DocBook XSL .

En ce qui concerne la question sur la FOP d’Apache: lorsque nous avons créé notre chaîne d’outils (similaire à celle suggérée par Gustavo), nous avons obtenu de très bons résultats en utilisant Moteur RenderX XEP . La sortie XEP semble un peu plus raffinée et, autant que je sache, FOP rencontrait quelques problèmes avec les tables (c’était il ya quelques années, cela aurait peut-être changé).

Avec FOP, vous obtenez les fonctionnalités que quelqu'un a décidé de vouloir mettre en oeuvre. Je dirais que personne qui se passionne pour l'édition ne l'utilise en production. RenderX, Antenna House ou Arbortext . (Je les ai utilisés au cours des derniers projets d'implémentation.) Cela dépend des besoins de votre entreprise, du degré d'automatisation que vous souhaitez automatiser, ainsi que des compétences, du temps et des ressources de votre équipe. Ce n’est pas seulement une question de technologie.

Si vous utilisez Red Hat, Ubuntu ou Windows, jetez un coup d’œil à Publican, qui est supposé être une chaîne d’outils assez complète en ligne de commande. Red Hat l’utilise beaucoup.

L'article intitulé La chaîne d'outils DocBook pourrait être utile car bien. C'est une section d'un HOWTO sur DocBook écrit par Eric Raymond .

J'ai utilisé deux utilitaires CLI pour simplifier la chaîne d'outils docbook: xmlto et publican.

Publican a l’air élégant, mais il est bien adapté à Fedora & amp; Publication Redhat a besoin.

Je publie / travaille actuellement sur un projet open-source appelé bookshop, qui est un RubyGem qui installe un pipeline / une chaîne d'outils complète de Docbook-XSL. Il inclut tout le nécessaire pour créer et éditer des fichiers source de Docbook et générer différents formats (actuellement au format pdf et epub, et en croissance rapide).

Mon objectif est de permettre de passer de zéro à l'exportation (au format PDF ou autre) depuis votre source Docbook en moins de 10 minutes.

Le résumé:

bookShop est un framework OSS à base de ruby ??pour le bonheur et la productivité durable dans les outils de documentation. La structure est optimisée pour aider les développeurs à s’accélérer rapidement, leur permettant de se lancer plus rapidement et de développer leurs flux DocBook-to-Output, en privilégiant la convention par rapport à la configuration, en les configurant avec les meilleures pratiques, normes et outils dès le départ. .

Voici l'emplacement de la gemme: https://rubygems.org/gems/bookshop

Et le code source: https://github.com/blueheadpublishing/bookshop

Je préfère utiliser Windows pour la plupart de mes créations de contenu (éditeur Notepad ++). Publican sous Linux est une bonne chaîne d’outils pour créer une bonne structure de documentation et traiter les résultats. J'utilise Dropbox (il existe également d'autres services de partage de documents, qui devraient bien fonctionner sur les deux plates-formes) sur ma machine Windows ainsi que sur une machine Linux virtuelle. Avec cette configuration, j'ai pu réaliser une combinaison qui fonctionne très bien pour moi. Une fois le travail d'édition terminé sous Windows (qui se synchronise immédiatement sur une machine Linux), je passe sous Linux pour exécuter publican build et créer des sorties HTML et PDF, qui sont à nouveau mises à jour dans mon dossier Windows par Dropbox.

Licencié sous: CC-BY-SA avec attribution
Non affilié à StackOverflow
scroll top