Qual è la toolchain consigliata per la formattazione di DocBook XML? [chiuso]

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

Domanda

Ho visto I migliori strumenti per lavorare con documenti DocBook XML , ma la mia domanda è leggermente diversa. Qual è la toolchain di formattazione attualmente consigliata, al contrario dello strumento di modifica, per XML DocBook?

In "L'arte della programmazione Unix" di Eric Raymond dal 2003 ( un libro eccellente!), il suggerimento è XML-FO (XML Formatting Objects), ma da allora ho visto dei suggerimenti che indicano che XML-FO non è più in fase di sviluppo (anche se non riesco più a trovare quella domanda su StackOverflow, quindi forse era errato).

Supponiamo di essere interessato principalmente a Unix / Linux (incluso MacOS X), ma non ignorerei automaticamente le soluzioni solo per Windows.

FOP di Apache è la strada migliore da percorrere? Ci sono alternative?

È stato utile?

Soluzione

Ho fatto un po 'di scrittura manuale con DocBook, sotto cygwin, per produrre HTML di una pagina, HTML di molte pagine, CHM e PDF.

Ho installato quanto segue:

  1. Il docbook repository dei fogli di stile (xsl).
  2. xmllint, per verificare se l'xml è corretto.
  3. xsltproc, per elaborare l'xml con i fogli di stile.
  4. Fop di Apache , per produrre PDF. Mi assicuro di aggiungere la cartella installata al PERCORSO.
  5. Microsoft HTML Help Workshop , per produrre CHM. Mi assicuro di aggiungere la cartella installata al PERCORSO.

Modifica : nel codice seguente sto usando più di 2 file. Se qualcuno vuole una versione ripulita degli script e della struttura delle cartelle, per favore contattami: guscarreno (squiggly / at) googlemail (punto / punto) com

Uso quindi 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

e 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

per automatizzare la produzione degli output dei file sopra menzionati.

Preferisco usare un approccio nix allo scripting solo perché il set di strumenti è più facile da trovare e utilizzare, per non parlare più facile da concatenare.

Altri suggerimenti

Utilizziamo XMLmind XmlEdit per l'editing e docbkx per creare output durante le nostre build. Per una serie di buoni modelli, dai un'occhiata a quelli Hibernate o Spring fornire.

Per l'output HTML, utilizzo i fogli di stile XSL Docbook con il processore XSLT xsltproc.

Per l'output PDF, utilizzo dblatex , che si traduce in LaTeX e quindi utilizzo pdflatex per compilarlo in PDF . (Prima avevo usato Jade, i fogli di stile DSSSL e jadetex.)

Usiamo

  • Serna XML Editor
  • Eclipse (semplice modifica di xml, utilizzata principalmente dai tecnici)
  • proprio plug-in Eclipse specifico (solo per le nostre note di rilascio)
  • Plug-in Maven docbkx
  • Vaso Maven con foglio di stile aziendale specifico, basato sui fogli di stile standard per docbook
  • Plug-in Maven per la conversione di CSV in tabella DocBook
  • Plug-in Maven per l'estrazione dei dati BugZilla e la creazione di una sezione DocBook da esso
  • Hudson (per generare i documenti PDF)
  • Nexus per distribuire i documenti PDF creati

Alcune idee che abbiamo:

Distribuisci con ogni versione del prodotto non solo il PDF, ma anche il documento DocBook completo originale (poiché in parte scriviamo il documento e in parte li generiamo). Il salvataggio dell'intero documento DocBook li rende indipendenti per le modifiche apportate alla configurazione del sistema in futuro. Ciò significa che se il sistema cambia, da cui il contenuto è stato estratto (o sostituito da sistemi diff.) Non saremmo più in grado di generare il contenuto esatto. Ciò potrebbe causare un problema, se fosse necessario rilasciare nuovamente (con fogli di stile diversi) l'intera gamma di manuali dei prodotti. Come per i vasetti; queste classi Java compilate sono anche collocate in Nexus (non si desidera memorizzarle nel proprio SCM); questo faremmo anche con il documento DocBook generato.

Aggiornamento:

Fresh ha creato un plug-in Maven HTML Cleaner , che consente di aggiungi il contenuto di DocBook a un sito del progetto Maven (versione beta disponibile). Il feedback è benvenuto tramite il Apri discussione Forum.

I fogli di stile DocBook, oltre a FOP, funzionano bene, ma alla fine ho deciso di lanciarmi per RenderX, che copre lo standard in modo più approfondito e ha alcune belle estensioni di cui i fogli di stile DocBook sfruttano.

Il libro di Bob Stayton, DocBook XSL: The Complete Guide , descrive diverse catene di strumenti alternative, compresi quelli che funzionano su Linux o Windows (quasi sicuramente anche MacOS, anche se non ho usato personalmente un Mac).

Un approccio popolare è quello di utilizzare Fogli di stile XSL per DocBook .

Per quanto riguarda la domanda sulla FOP di Apache: quando abbiamo stabilito la nostra toolchain (simile a quanto suggerito Gustavo) abbiamo ottenuto ottimi risultati usando motore RenderX XEP . L'output degli XEP sembra un po 'più raffinato e, per quanto ricordo, la FOP ha avuto alcuni problemi con le tabelle (questo è stato alcuni anni fa, questo potrebbe essere cambiato).

Con FOP ottieni le funzionalità che qualcuno ha deciso di volere abbastanza male da implementare. Direi che nessuno che si occupi seriamente di editoria lo usa nella produzione. Stai molto meglio con RenderX o Antenna House o Arbortext . (Li ho usati negli ultimi dieci anni di progetti di implementazione.) Dipende dai requisiti della tua azienda, da quanto vuoi automatizzare e da quali sono anche le competenze, il tempo e le risorse del tuo team. Non è solo una domanda di tecnologia.

Se usi Red Hat, Ubuntu o Windows, potresti dare un'occhiata a Publican, che dovrebbe essere una toolchain abbastanza completa da riga di comando. Red Hat lo utilizza ampiamente.

L'articolo chiamato La toolchain di DocBook potrebbe essere utile come bene. È una sezione di un HOWTO su DocBook scritto da Eric Raymond .

Ho usato due programmi di utilità CLI per semplificare il mio toolchain docbook: xmlto e publican.

Publican mi sembra elegante ma abbastanza adatto per Fedora & amp; La pubblicazione di Redhat ha bisogno.

Rilascio / sto lavorando a un progetto open source chiamato bookshop che è un RubyGem che installa una pipeline / toolchain completa per Docbook-XSL. Include tutto il necessario per creare e modificare i file sorgente di Docbook e generare formati diversi (attualmente pdf ed epub e in rapida crescita).

Il mio obiettivo è quello di rendere possibile passare da Zero a Esportazione (pdf o altro) dalla fonte del tuo Docbook in meno di 10 minuti.

Il sommario:

bookShop è un framework basato su ruby ??OSS per la felicità della toolchain docbook e la produttività sostenibile. Il framework è ottimizzato per aiutare gli sviluppatori a accelerare rapidamente, consentendo loro di saltare più rapidamente e sviluppare i loro flussi DocBook-to-Output, favorendo la convenzione sulla configurazione, impostandoli con best practice, standard e strumenti fin dall'inizio .

Ecco la posizione della gemma: https://rubygems.org/gems/bookshop

E il codice sorgente: https://github.com/blueheadpublishing/bookshop

Preferisco usare Windows per la maggior parte della mia creazione di contenuti (Notepad ++ editor). Publican in Linux è una buona catena di strumenti per creare una buona struttura di documentazione e elaborare i risultati. Uso Dropbox (ci sono anche altri servizi di condivisione di documenti, che dovrebbero funzionare bene su entrambe le piattaforme) sia sul mio computer Windows che su quello virtuale Linux. Con questa configurazione sono stato in grado di ottenere una combinazione che funziona alla grande per me. Una volta completato il lavoro di modifica in Windows (che si sincronizza immediatamente con la macchina Linux), passo a Linux per eseguire build di publican e creare output HTML e PDF, che vengono nuovamente aggiornati nella mia cartella Windows da Dropbox.

Autorizzato sotto: CC-BY-SA insieme a attribuzione
Non affiliato a StackOverflow
scroll top