Was ist die empfohlene Toolchain XML DocBook zur Formatierung? [geschlossen]

https://stackoverflow.com/questions/122752

02-07-2019
|

Frage

Ich habe für das Arbeiten mit DocBook XML-Dokumente besten Werkzeuge gesehen , aber meine Frage ist etwas anders. Welches ist die derzeit empfohlenen Formatierung Toolchain ist - wie zum Editing-Tool im Gegensatz - für XML DocBook

Eric Raymonds 'The Art of Unix Programming' von 2003 ( ein ausgezeichnetes Buch!), ist der Vorschlag XML-FO (XML Formatierung von Objekten), aber ich habe hier seit gesehen Vorschlägen, die der angegebenen XML-FO nicht mehr in der Entwicklung ist (obwohl ich nicht mehr diese Frage auf Stackoverflow finden kann, so vielleicht ist es falsch war).

Angenommen ich in Unix / Linux in erster Linie interessiert bin (einschließlich MacOS X), aber ich würde nur für Windows-Lösungen nicht automatisch ignorieren.

Apache FOP der beste Weg zu gehen? Gibt es Alternativen?

Lösung

Ich habe einige manuelle Schreiben mit DocBook getan, unter Cygwin, Eine Seite HTML, viele Seiten HTML, CHM und PDF zu erzeugen.

Ich installierte die folgenden:

Die docbook Sheets (xsl) Repository.
xmllint, zu testen, ob die xml korrekt ist.
xsltproc, die XML mit den Formatvorlagen zu verarbeiten.
Apache FOP , produzieren PDF's.I stellen Sie sicher, den installierten Ordner hinzufügen zur PATH.
Microsofts HTML Help Workshop , um CHM der zu produzieren. Ich stelle sicher, den installierten Ordner in den PATH hinzuzufügen.

Bearbeiten : Im folgenden Code, den ich mehr als die 2-Dateien bin mit. Wenn jemand eine aufgeräumt Version der Skripte und die Ordnerstruktur will, bitte kontaktieren Sie mich: guscarreno (verschnörkelt / at) google (Zeit / dot) com

Ich verwende dann einen 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

und ein 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

die Produktion der oben genannten Dateiausgaben zu automatisieren.

Ich bevorzuge nichts Annäherung an das Scripting zu verwenden, nur weil das Toolset leichter zu finden und zu verwenden ist, nicht leichter Kette zu nennen.

Andere Tipps

Wir verwenden XMLmind XMLEdit für die Bearbeitung und Maven docbkx Plugin-Ausgabe erstellen während unserer Builds. Für eine Reihe von guten Vorlagen einen Blick auf die, die Hibernate oder Frühling bieten.

Für die HTML-Ausgabe, verwende ich die DocBook XSL Stylesheets mit dem XSLT-Prozessor xsltproc .

Für die PDF-Ausgabe, verwende ich dblatex , die LaTeX übersetzt und dann pdflatex verwenden, um PDF zu kompilieren . (I verwendet Jade, die DSSSL Stylesheets und jadetex vor.)

Wir verwenden

Serna XML Editor
Eclipse-(plain XML-Bearbeitung, vor allem von den technischen Menschen verwendet wird)
besitzt spezifische Eclipse-Plug-in (nur für unser Release-Notes)
Maven docbkx Plug-In
Maven jar mit spezifischer Corporate Stylesheet, basierend auf dem Standard DocBook Stylesheets
Maven Plug-in für csv zu DocBook Tabelle konvertieren
Maven Plug-in für BugZilla Extrahieren von Daten und einen Abschnitt von ihr DocBook
Hudson (das PDF-Dokument (e) zu erzeugen)
Nexus die erstellten PDF-Dokumente

Einige Ideen, die wir haben:

Stellen bei jeder Produktversion nicht nur die PDF, sondern auch das komplette Original DocBook Dokument (wie wir teilweise das Dokument schreiben und teilweise erzeugen sie). das vollständige DocBook Dokument zu speichern macht sie für Änderungen im System-Setup in Zukunft unabhängig. Das heißt, wenn die Systemänderungen, aus denen der Inhalt extrahiert wurde (oder durch diff ersetzt. Systeme) würden wir den genauen Inhalt zu erzeugen, nicht mehr möglich sein. Welche könnte ein Problem verursachen, wenn wir die ganzen Produkt ranche von Handbuch zum Re-Release (mit verschiedener Style-Sheet) benötigt. Das gleiche wie mit den Gläsern; diese kompilierten Java-Klassen sind auch in Nexus (Sie nicht wollen, speichern sie in Ihrem SCM) platziert; das würden wir auch mit dem erzeugten DocBook Dokument bearbeitet wird.

Update:

Frische a erstellt Maven HTML-Reiniger Plug-in , die es ermöglicht, hinzufügen DocBook Inhalt zu einer Maven Projekt-Website (Beta-Version verfügbar). Feedback ist willkommen durch die Offene Diskussion Forum.

Die DocBook-Stylesheets, sowie FOP, gut funktionieren, aber ich entschied mich schließlich für RenderX zu springen, die den Standard gründlich mehr bedeckt und hat einige nette Erweiterungen, die die DocBook Stylesheets nutzen.

Bob Stayton Buch DocBook XSL: The Complete Guide , mehrere alternative Werkzeugketten beschreibt, darunter auch solche, die (auch fast sicher MacOS, obwohl ich persönlich habe einen Mac nicht verwendet) unter Linux oder Windows.

Eine beliebte Methode ist die Verwendung DocBook XSL Stylesheets .

In Bezug auf die Frage zu Apache FOP: Wenn wir unsere Werkzeugkette etabliert (ähnlich dem, was Gustavo vorgeschlagen hat) wir sehr gute Ergebnisse hatte die RenderX XEP Motor . XEPs Ausgang ein bisschen mehr poliert aussieht, und so weit wie ich mich erinnere, FOP hatte einige Probleme mit Tabellen (das war vor ein paar Jahren aber dies haben könnte geändert).

Mit FOP erhalten Sie die Eigenschaften, die jemand beschlossen sie schlecht genug umsetzen wollten. Ich würde sagen, dass niemand, der über das Veröffentlichen ernst ist verwendet es in der Produktion. Du bist viel besser dran mit RenderX oder Antenna House oder Arbortext . (Ich habe sie überall in den letzten zehn Jahren im Wert von Implementierungsprojekten verwendet.) Es hängt von Ihren Geschäftsanforderungen, wie viel Sie automatisieren mögen, und was Ihr Team Fähigkeiten, Zeit und Ressourcen wie auch sind. Es ist nicht nur eine Technologie Frage.

Wenn Sie auf Red Hat, Ubuntu sind, oder Windows, können Sie einen Blick auf Publican zu nehmen, die angeblich eine ziemlich vollständige Befehlszeile Werkzeugkette sein. Red Hat nutzt es ausgiebig.

Wiki hier: https://fedorahosted.org/publican/
Doc hier: http://jfearn.fedorapeople.org/Publican/
Quellarchive und EXE-Dateien hier: https://fedorahosted.org/releases/p/ u / publican /

Der Artikel mit dem Titel Die DocBook Toolkette nützlich sein könnten als Gut. Es ist ein Abschnitt eines HOWTO auf DocBook geschrieben von Eric Raymond .

Ich habe zwei CLI utils benutze für meine DocBook Toolkette vereinfachen: xmlto und Zöllner

Publican sieht elegant mir aber genug für die Fedora & Redhat Veröffentlichung Bedürfnisse ausgestattet.

Ich befreie / ist auf einer Open-Source-Projekt namens Buchhandlung, die ein RubyGem ist, die eine vollständige Docbook-XSL-Pipeline / Toolchain installiert. Es enthält alles, was benötigt, um zu erstellen und Docbook Quelldateien und Ausgabe unterschiedlicher Formate (derzeit pdf und epub und wächst schnell).

bearbeiten

Mein Ziel ist es möglich zu machen, von Zero-to-Export (pdf ist oder was auch immer) von Ihrer Docbook Quelle zu gehen in weniger als 10 Minuten.

Die Zusammenfassung:

Buchhandlung ist ein OSS rubin basiertes Framework für DocBook Toolchain Glück und nachhaltige Produktivität. Der Rahmen ist optimiert Entwickler schnell zu helfen, ramp-up, so dass sie in springen schneller und entwickeln ihre DocBook-to-Output fließt, durch Konvention über Konfiguration begünstigt, so dass sie sich mit Best Practices, Standards und Werkzeuge aus der get-go Einstellung .

Hier ist der Edelstein Lage: https://rubygems.org/gems/bookshop

Und der Quellcode: https://github.com/blueheadpublishing/bookshop

ziehe ich es Windows für die meisten meiner Content-Erstellung (Notepad ++ Editor) verwenden. Publican in Linux ist ein gutes Werkzeug Kette eine gute Dokumentationsstruktur und Prozessausgänge zu erstellen. Ich benutze Dropbox (es gibt auch andere Dokument-Sharing-Dienste als auch, was auf beiden Plattformen funktionieren gut soll) auf meinem Windows-Rechner sowie Virtual Linux-Rechner. Mit diesem Setup habe ich in der Lage gewesen, eine Kombination zu erreichen, das für mich funktioniert gut. Sobald bearbeiten Arbeit in Windows abgeschlossen ist (die sofort auf Linux-Rechner synchronisiert), wechsle ich auf Linux publican Build zu laufen und HTML und PDF-Ausgaben erstellen, die wieder in meinem Windows-Ordner von Dropbox aktualisiert werden.

Lizenziert unter: CC-BY-SA mit Zuschreibung

Nicht verbunden mit StackOverflow