Dokumentation mit DocBook

Posts 1-10 of 11

Back
Next

Elke Vogt
The company name is only visible to registered members.

Welche Tools erleichtern das Erlernen von DocBook?
Liebe DocBook-Könner,

kann mir jemand bei der Suche nach einem Tool bzw. einer Umgebung helfen, die es mir (und neuen, WYSIWYG-verwöhnten Kollegen) erstmal erlaubt, DocBook so einfach/schnell wie möglich zu erlernen und wenn möglich auch noch später professionell damit arbeiten zu können.

Meine Situation ist folgende:
- ich bin es als Technische Redakteurin gewöhnt mit WYSIWYG-Programmen zu arbeiten (u.a. FrameMaker),
- bei meinem neuen Auftraggeber, soll ich nun XML-Dokumente in DocBook erstellen bzw. vorhandene Dokumente überarbeiten; in einer Unix/Linux-Umgebung
- das Buch von Herrn Trieloff "DocBook-XML" ist mir eine große Hilfe
- außerdem haben mir Kollegen den Editor XMLMind empfohlen (mit DocBook-AddOn). Ich muss(te) also auch noch lernen mit diesem komplexen Editor umzugehen; er hat aber den Vorteil, dass ich sofort das Ergebnis meiner Arbeit sehe, leider aber nicht in XML
- damit ich sehen kann, wie meine Datei in XML aussieht, und weil ich XMLMind noch nicht so gut beherrsche, arbeite ich wechselweise auch direkt im VIM-Editor.

Ein Nachteil vom XMLMind ist, dass bei uns viele existierende Dateien Entitäten (&) haben. Die kann XMLMind nicht öffnen, d.h. ich muss sie erst im VIM bearbeiten. Auch die ü,ä, ß usw. bereiten mir Probleme.
Es wäre noch von Vorteil einen Editor zu haben, der probelmlos MS-Word-Dateien einlesen kann.

Da ich zusammen mit vielen Software-Entwicklern arbeite, die auch Beschreibungstexte erstellen, haben also zumindest alle neue Kollegen, das gleiche Problem wie ich, zumal sie ja auch nur hin und wieder mit DocBook arbeiten.

Wir suchen also eine Umgebung, die uns das editieren von DocBook so leicht wie möglich macht.
Es ist nicht so wichtig, dass der Editor die letzten Feinheiten beherrscht, denn diese könnten die Profi-Kollegen übernehmen.

Wir haben übrigens ein professionelles "Tool", dass die Versionierung der DocBook-Dateien/Dokumente übernimmt (d.h. Beschreibung passend zum Software-Stand) und auch die Verarbeitung der Dokumente als PDF und HTML, sowie die Veröffentlichung im Intranet. D.h. DocBook ansich bleibt ein "muss".

Grüße
Elke Vogt
Freiberuflich tätiger Technischer Redakteur, Mainz

Ing-Vogt@vogt-dokumentation.de
- 11 Feb 2007, 7:09 pm
Elke Vogt wrote: > Liebe DocBook-Könner, > > kann mir jemand bei der Suche nach einem Tool bzw. einer Umgebung > helfen, die es mir (und neuen, WYSIWYG-verwöhnten Kollegen) erstmal > erlaubt, DocBook so einfach/schnell wie möglich zu erlernen und wenn > möglich auch noch später professionell damit arbeiten zu können. > > Meine Situation ist folgende: > - ich bin es als Technische Redakteurin gewöhnt mit > WYSIWYG-Programmen zu arbeiten (u.a. FrameMaker), > - bei meinem neuen Auftraggeber, soll ich nun XML-Dokumente in > DocBook erstellen bzw. vorhandene Dokumente überarbeiten; in einer > Unix/Linux-Umgebung > - das Buch von Herrn Trieloff "DocBook-XML" ist mir eine große Hilfe > - außerdem haben mir Kollegen den Editor XMLMind empfohlen (mit > DocBook-AddOn). Ich muss(te) also auch noch lernen mit diesem > komplexen Editor umzugehen; er hat aber den Vorteil, dass ich sofort > das Ergebnis meiner Arbeit sehe, leider aber nicht in XML > - damit ich sehen kann, wie meine Datei in XML aussieht, und weil ich > XMLMind noch nicht so gut beherrsche, arbeite ich wechselweise auch > direkt im VIM-Editor. > > Ein Nachteil vom XMLMind ist, dass bei uns viele existierende Dateien > Entitäten (&) haben. Die kann XMLMind nicht öffnen, d.h. ich muss sie > erst im VIM bearbeiten. Auch die ü,ä, ß usw. bereiten mir Probleme. > Es wäre noch von Vorteil einen Editor zu haben, der probelmlos > MS-Word-Dateien einlesen kann. > > Da ich zusammen mit vielen Software-Entwicklern arbeite, die auch > Beschreibungstexte erstellen, haben also zumindest alle neue > Kollegen, das gleiche Problem wie ich, zumal sie ja auch nur hin und > wieder mit DocBook arbeiten. > > Wir suchen also eine Umgebung, die uns das editieren von DocBook so > leicht wie möglich macht. > Es ist nicht so wichtig, dass der Editor die letzten Feinheiten > beherrscht, denn diese könnten die Profi-Kollegen übernehmen. > > Wir haben übrigens ein professionelles "Tool", dass die Versionierung > der DocBook-Dateien/Dokumente übernimmt (d.h. Beschreibung passend > zum Software-Stand) und auch die Verarbeitung der Dokumente als PDF > und HTML, sowie die Veröffentlichung im Intranet. D.h. DocBook ansich > bleibt ein "muss". > > Grüße > Elke Vogt > Freiberuflich tätiger Technischer Redakteur, Mainz > > Ing-Vogt@vogt-dokumentation.de
Lars Trieloff
The company name is only visible to registered members.

Re: Welche Tools erleichtern das Erlernen von DocBook?
Hallo Frau Vogt,

der XMLmind sollte eigentlich mit XML-Dateien klar kommen, die Entitäten enthalten, wenn es Probleme mit dem & gibt, handelt es sich wahrscheinlich nicht um gültige XML-Dateien.

Die Konvertierung bestehender Word-Dokumente in DocBook ist nach wie vor ein schwieriges Thema, da es in der Regel schwer ist, ein Mapping von Format-orientierten Formaten wie Word in Struktur-orientierte Formate wie DocBook vorzunehmen. Eventuell können sie jedoch den ersten Schritt durch ein Programm wie OpenOffice.org Writer übernehmen lassen, das sowohl Word als auch DocBook unterstützt.

mit freundlichen Grüßen,

Lars Trieloff
- 12 Feb 2007, 09:37 am
Lars Trieloff wrote: > Hallo Frau Vogt, > > der XMLmind sollte eigentlich mit XML-Dateien klar kommen, die > Entitäten enthalten, wenn es Probleme mit dem & gibt, handelt es sich > wahrscheinlich nicht um gültige XML-Dateien. > > Die Konvertierung bestehender Word-Dokumente in DocBook ist nach wie > vor ein schwieriges Thema, da es in der Regel schwer ist, ein Mapping > von Format-orientierten Formaten wie Word in Struktur-orientierte > Formate wie DocBook vorzunehmen. Eventuell können sie jedoch den > ersten Schritt durch ein Programm wie OpenOffice.org Writer > übernehmen lassen, das sowohl Word als auch DocBook unterstützt. > > mit freundlichen Grüßen, > > Lars Trieloff
Christian Dizdar
The company name is only visible to registered members.

Re: Welche Tools erleichtern das Erlernen von DocBook?
Hallo Frau Vogt,

ich kann Ihnen hierzu den Arbortext Editor vom PTC (ehem. Epic Editor von Arbortext) empfehlen. Wir nutzen Ihn seit Jahren hier für technische Dokumentation. Der Editor ist für die Unterstützung von DocBook auch bereits vorbereitet. Der Editor ist nicht ganz billig, da weitere Komponenten je nach Anwendungsbereich zusätzlich lizenziert werden müssen, allerdings ist der Editor im Vergleich zu vielen anderen bereits sehr ausgereift.

Gruß aus Eisenstadt

Christian Dizdar
- 12 Feb 2007, 12:26 pm
Christian Dizdar wrote: > Hallo Frau Vogt, > > ich kann Ihnen hierzu den Arbortext Editor vom PTC (ehem. Epic Editor > von Arbortext) empfehlen. Wir nutzen Ihn seit Jahren hier für > technische Dokumentation. Der Editor ist für die Unterstützung von > DocBook auch bereits vorbereitet. Der Editor ist nicht ganz billig, > da weitere Komponenten je nach Anwendungsbereich zusätzlich > lizenziert werden müssen, allerdings ist der Editor im Vergleich zu > vielen anderen bereits sehr ausgereift. > > Gruß aus Eisenstadt > > Christian Dizdar
Michael Valent Group moderator
The company name is only visible to registered members.

Re^2: Welche Tools erleichtern das Erlernen von DocBook?
Das Arbortext-Tool ist superfein (speziell die Generierungsmaschine), aber auch recht teuer.

Wir verwenden XMetaL Version 4 (http://www.xmetal.com). Ist zwar auch nicht geschenkt, aber doch günstiger - zumindest, als ich zum letzten Mal nachgesehen habe.

Vorteil: Ich habe drei Sichten: Plain Text, Tags-on (grafische Tags) und WYSIWYG. Bei Letzterem werden die Text Entities korrekt aufgelöst, bei zweiterem sind sie als Icons im Text eingebettet.

Der Nachteil: Zur perfekten Darstellung von Tags-on und WYSIWYG muss zuerst ein CSS bereitstehen. Wir haben unseres selbst gebastelt.

mfg

Michael Valent
- 19 Feb 2007, 4:13 pm
Michael Valent wrote: > Das Arbortext-Tool ist superfein (speziell die > Generierungsmaschine), aber auch recht teuer. > > Wir verwenden XMetaL Version 4 (www.xmetal.com). Ist zwar auch nicht > geschenkt, aber doch günstiger - zumindest, als ich zum letzten Mal > nachgesehen habe. > > Vorteil: Ich habe drei Sichten: Plain Text, Tags-on (grafische Tags) > und WYSIWYG. Bei Letzterem werden die Text Entities korrekt > aufgelöst, bei zweiterem sind sie als Icons im Text eingebettet. > > Der Nachteil: Zur perfekten Darstellung von Tags-on und WYSIWYG muss > zuerst ein CSS bereitstehen. Wir haben unseres selbst gebastelt. > > mfg > > Michael Valent
Christian Dizdar
The company name is only visible to registered members.

Re^3: Welche Tools erleichtern das Erlernen von DocBook?
XMetal kenn ich leider nicht. Bzgl. dem Arbortexttool, find ich die Preise gar nicht so Schlimm. Der Editor ist bei entsprechender Lizenzierung sogar günstiger als FrameMaker. Mit Generierungstool hat Herr Valent wahrscheinlich die E3-Publishing Engine angesprochen, die tatsächlich sehr teuer ist. Allerdings es gibt auch Alternativen dazu, die es ermöglichen lokal zu publizieren, wobei hier die Preise dann deutlich günstiger sind.

Großer Vorteil bei Arbortext ist, dass man die Sichten auch selbst definieren kann - Baum, Editor (mit und ohne Tags,....). Die Erstellung von Stylesheets ist auch möglich. Erforderlich hierzu ist der Styler, den man als Komponente zum Editor erhält.

Ich hab selbst bereits Handbücher damit erstellt und kann bestätigen, dass es sich um ein sehr feines Tool handelt, welches wahrlich so ziemlich alles bietet was man sich nur erwartet. Allerdings wie auch von Herrn Valent angesprochen eben nicht gerade zum günstigsten Preis.

Besten Gruß

Christian Dizdar
- 19 Feb 2007, 4:29 pm
Christian Dizdar wrote: > XMetal kenn ich leider nicht. Bzgl. dem Arbortexttool, find ich die > Preise gar nicht so Schlimm. Der Editor ist bei entsprechender > Lizenzierung sogar günstiger als FrameMaker. Mit Generierungstool hat > Herr Valent wahrscheinlich die E3-Publishing Engine angesprochen, die > tatsächlich sehr teuer ist. Allerdings es gibt auch Alternativen > dazu, die es ermöglichen lokal zu publizieren, wobei hier die Preise > dann deutlich günstiger sind. > > Großer Vorteil bei Arbortext ist, dass man die Sichten auch selbst > definieren kann - Baum, Editor (mit und ohne Tags,....). Die > Erstellung von Stylesheets ist auch möglich. Erforderlich hierzu ist > der Styler, den man als Komponente zum Editor erhält. > > Ich hab selbst bereits Handbücher damit erstellt und kann bestätigen, > dass es sich um ein sehr feines Tool handelt, welches wahrlich so > ziemlich alles bietet was man sich nur erwartet. Allerdings wie auch > von Herrn Valent angesprochen eben nicht gerade zum günstigsten Preis. > > Besten Gruß > > Christian Dizdar
Post visible to registered members
Christina Reimann
The company name is only visible to registered members.

Re^5: Welche Tools erleichtern das Erlernen von DocBook?
Hallo Frau Vogt,

probieren Sie die Übertragung von Word-Dateien mit dem Tool Office2DocBook.

Allerdings muss dort das Format für die Übertragung etwas angepasst werden.

Gruss
Christina Reimann
- 11 Jan 2008, 07:50 am
Christina Reimann wrote: > Hallo Frau Vogt, > > probieren Sie die Übertragung von Word-Dateien mit dem Tool > Office2DocBook. > > Allerdings muss dort das Format für die Übertragung etwas angepasst > werden. > > Gruss > Christina Reimann
Karsten Krumrück Premium Member Group moderator
The company name is only visible to registered members.

Re^6: Welche Tools erleichtern das Erlernen von DocBook?
Hallo Frau Vogt,

wir verwenden bei uns in der Firma für die technische Dokumentation Syntext Serna (http://www.syntext.com). Das besondere bei diesem Editor ist, das der Editor für die Darstellung XSL:FO verwendet. Der Autor sieht somit schon bei der Eingabe das Ergebnis der Ausgabe. Der Editor ist nicht nur für Windows, sondern auch für Linux und MacOS verfügbar, die Lizenzkosten halten sich noch in Grenzen (ca. 200 Euro).

Wir bearbeiten mit dem Tool direkt die Docbook-XML-Dateien, die über Subversion versioniert werden. Die PDF-Generierung erfolgt dann automatisch per Script mit Opensource Tools (SAXON, FOP) unter Verwendung eines selbst erstellten XSL-Stylesheets.

Übrigens haben wir auch eine Migrierung von Word nach Docbook-XML vorgenommen. Dabei sind wir über den Zwischenschritt OpenOffice gegangen. Also zuerst die Worddateien in OpenOffice geöffnet und dann als Docbook (Article) abgespeichert. Abschließend waren noch einige manuelle Korrekturen nötig, da der Docbook-Export von OpenOffice leider nicht alle Docbook-Elemente unterstützt, die wir benötigen.

mit freundlichen Grüßen

Karsten Krumrück
This post was modified on 30 Jan 2008 at 09:33 pm.
- 30 Jan 2008, 9:29 pm
Karsten Krumrück wrote: > Hallo Frau Vogt, > > wir verwenden bei uns in der Firma für die technische Dokumentation > Syntext Serna (http://www.syntext.com). Das besondere bei diesem > Editor ist, das der Editor für die Darstellung XSL:FO verwendet. Der > Autor sieht somit schon bei der Eingabe das Ergebnis der Ausgabe. Der > Editor ist nicht nur für Windows, sondern auch für Linux und MacOS > verfügbar, die Lizenzkosten halten sich noch in Grenzen (ca. 200 > Euro). > > Wir bearbeiten mit dem Tool direkt die Docbook-XML-Dateien, die über > Subversion versioniert werden. Die PDF-Generierung erfolgt dann > automatisch per Script mit Opensource Tools (SAXON, FOP) unter > Verwendung eines selbst erstellten XSL-Stylesheets. > > Übrigens haben wir auch eine Migrierung von Word nach Docbook-XML > vorgenommen. Dabei sind wir über den Zwischenschritt OpenOffice > gegangen. Also zuerst die Worddateien in OpenOffice geöffnet und dann > als Docbook (Article) abgespeichert. Abschließend waren noch einige > manuelle Korrekturen nötig, da der Docbook-Export von OpenOffice > leider nicht alle Docbook-Elemente unterstützt, die wir benötigen. > > mit freundlichen Grüßen > > Karsten Krumrück
Post visible to registered members
Karsten Krumrück Premium Member Group moderator
The company name is only visible to registered members.

Re^8: Welche Tools erleichtern das Erlernen von DocBook?
Hallo Herr Fischer,

laut Online-Hilfe von Serna sollte das Programm diese Funktionalität zur Verfügung stellen:

===
Zitat:

Working with Entities
An entity is a reusable fragment of the document content that can be reused multiple times by reference. Unlike other editors, Serna allows you to edit entity references in-place and shows them as regular content.
There are two types of entities:
Internal Entities . An internal entity can be reused only in the document in which it was declared.
External Entities . An external entity is saved to a separate file and can be reused in any document.

===

Getestet habe ich diese Funktion selbst bisher noch nicht. Man kann aber bei Syntext eine Trial-Version zum Testen herunterladen. Die Trial-Version ist voll funktionsfähig, nur halt zeitlich begrenzt

Viele Grüße

Karsten Krumrück
- 06 Feb 2008, 4:48 pm
Karsten Krumrück wrote: > Hallo Herr Fischer, > > laut Online-Hilfe von Serna sollte das Programm diese Funktionalität > zur Verfügung stellen: > > === > Zitat: > > Working with Entities > An entity is a reusable fragment of the document content that can be > reused multiple times by reference. Unlike other editors, Serna > allows you to edit entity references in-place and shows them as > regular content. > There are two types of entities: > Internal Entities . An internal entity can be reused only in the > document in which it was declared. > External Entities . An external entity is saved to a separate file > and can be reused in any document. > > === > > Getestet habe ich diese Funktion selbst bisher noch nicht. Man kann > aber bei Syntext eine Trial-Version zum Testen herunterladen. Die > Trial-Version ist voll funktionsfähig, nur halt zeitlich begrenzt > > Viele Grüße > > Karsten Krumrück

Back
Next