DocMaker Doku

[PAMKKKKK]

Hallo habe mal die DocMaker Doku überarbeitet.

--------------------------------------------------------------------

PureBasic DocMaker Help - v3.93

24.Sept. 2005 - PAMKKKKK

--------------------------------------------------------------------

Was ist der PureBasic DocMaker
------------
Der PureBasic DocMaker ist ein Textparser der aus Textdateien, die mit Formatierungs-Tags (Formattags) versehen sind, Dokumente in folgenden Formaten erstellt:

RTF (Word 97+ Kompatibel)
CHM (Windows)
Multiview (Amiga)
HTML

Der DocMaker wandelt nicht nur in viele Betriebssystemspezifische Formate, er unterstützt auch mehrere Zielsprachen (Deutsch, English und Französisch).

Der PureBasic DocMaker war als erstes nur zur Erstellung der Purebasic Hilfe gedacht. Wenn du Dokumente für die verschiedenen Betriebssysteme aus einem einzigen Quellformat in den dort lesbaren Formaten wandeln willst so kannst du den PureBasic DocMaker nutzen.


I. DocMaker Installation
----------------------

Eine Installation des DocMakers ist im allgemeine nicht nötig es sei denn man möchte die vorgegebenen Pfade nicht nutzen.

Mit der Installation von Purebasic liegt der DocMaker im Verzeichnis PureBasic\Library SDK\DocMaker.

Ausgehend vom diesem DocMaker-Verzeichnis muss sich folgende Verzeichnisstruktur dort befinden:

DocMaker\DocMaker.exe
DocMaker\German
DocMaker\German\deutsche_Dateien.txt
DocMaker\English
DocMaker\English\englische_Dateien.txt
DocMaker\French
DocMaker\English\französische_Dateien.txt
DocMaker\Examples Code-Beispiele zur Einbindung mit @Example
DocMaker\HelpPictures Bilddateien zur Einbindung mit @Image
DocMaker\Output Zielverzeichnis für erstellte Dateien

Dann sollte nach einem druck auf start, die ausgewählte Sprachedateien in das Zielformat gewandelt werden.

II. DocMaker steuern
----------------------

Da der PureBasic DocMaker als erstes nur zur Erstellung der Purebasic Hilfe gedacht war, erstellt er voreinstellungsgemäß auch nur die Purebasic Hilfe Datei.

Der 'User Library' Modus erlaubt es eigene Hilfe-Dateien zu erstellen, die dann genauso wie die Purebasic Hilfe mit der Taste F1 aus der Purebasic IDE aufgerufen werden kann wenn sie im PureBasic\Help Verzeichnis liegen.

- Shell/DOS Commandos Parameter um DocMaker per Shell-/DOS-Script zu steuern:

/DOCUMENTATIONPATH: Der Pfad zu den Dokumenten.

/OUTPUTPATH: Das Verzeichnis für die Ausgabe Datei.

/OS: Das Ziel-Betriebssystem für die Dokumente .
Mögliche Werte: "Windows", "Linux", "AmigaOS".

/LANGUAGE: Das Verzeichnis für welche Sprache Dokumente erstellt warden sollen. (Pfade siehe oben)
Mögliche Werte: "German", " English", "French".

/FORMAT: Das Zielformat in das Dokumente erstellt werden sollen.
Mögliche Werte: "Html", "RTF", "Linux", "MultiView".

/CHM: Erzeugt eine Datei im Windows Helpformat CHM (nur unter Windows).
Dazu wird der HTMLWORKSHOP von Microsoft benötig (download bei Microsoft) und folgender Parameter muss zusätzlich angegeben werden:
/HTMLWORKSHOP: Voller Pfad zur hhc.exe

/USERLIBRARY: Schaltet in den 'User Library' Modus

III. DocMaker Formattags
----------------------

Ein Semikolon ';' am Anfang der Zeile ist ein Kommentar, wenn es nicht in einem bestimmten Tag auftaucht (z,B. Bei Code im @SourceExample).

@Library ; name der library z.B. @Library Gadget
@Overview ; Einleitungstext der immer bei ganz oben steht
@OS Linux ; nachfolgende Text wird nur in der Linux hilfe vorkommen
@OS Windows ; nachfolgende Text wird nur in der Windows hilfe vorkommen
@OS Amiga ; nachfolgende Text wird nur in der Amiga hilfe vorkommen
@linebreak ; Zeilenumbruch
@CommandList ; bewirkt die Auflistung aller Befehle auf der Einleitungsseite
@Example ; ein Textdatei die includet wird z.B. @Example filename.pb
@Image ; Ein Bild (diese muss sich im Verzeichnis HelpPictures befinden)
@Function ; Eine PB-Funktion mit Name und Parameter
@Description ; beginnt einen Textabschnitt, der zur Beschreibung eines Befehls gedacht ist

; Zum Eingefügen vorformatierter Texte (Sourcecode). Das Semikolon wird Ignoriert.
; Der nach diesem Befehl eingegebene Text wird einfach mit dem Html-Tag "<PRE>" eingeleitet.
@SourceExample
<code hier>
<code hier>
<code hier>
<code hier>
@EndSourceExample ; Ende des SourceExample. Das Semikolon gilt wieder als Kommentar.

@Link ; bindet einen Link zu einem verwandten Befehl ein.(interner Link im). Benutzung: "@Link Library/Befehl()" ("Library/" kann weggelassen werden, wenn sich der Befehl in der gleichen Lib befindet)

@SupportedOS Windows, Linux, Amiga ; die unterstützten Systeme für einen Befehl


IV. CHM Dateien
---------------

(entnommen aus SelfHTML http://aktuell.de.selfhtml.org/extras/selfchm.htm)

chm-Dateien sind seit Windows 98 das offizielle Format der "Windows-Hilfe". chm-Dateien basieren - im Gegensatz zu dem früheren Windows-Hilfe-Format - nicht mehr auf RTF-Dateien, sondern auf HTML-Dateien. chm steht denn auch für compiled html. chm-Dateien sind auf jedem Windows-Rechner anzeigbar, auf dem Windows 98/2000/XP läuft, bzw. auf dem ein Internet Explorer 4.x oder höher installiert ist.

Es gibt aber auch chm-Betrachter für die Betriebssysteme

Mac OS X: http://www.macupdate.com/info.php/id/13835

Linux: http://www.herdsoft.com/linux/themen/chmviewer.html

chm-Dateien haben den Vorteil, dass alle Inhalte in eine einzige Datei gepackt werden. Eine Dokumentation wie die Purebasic Hilfe besteht dann nicht mehr wie im Original aus mehreren tausend Dateien, sondern aus einer einzigen.

chm-Dateien bestehen aus einem Frameset. Rechts werden die eigentlichen HTML-Inhalte angezeigt (ohne Einschränkungen und genau so, wie sie der Internet Explorer als normale HTML-Dateien anzeigen würde - inklusive JavaScript-Funktionalität, Multimedia, Hyperlinks ins Web usw.). Links dagegen wird eine Navigationsleiste mit einem oder mehreren Reitern angezeigt: der erste Reiter zeigt normalerweise ein Inhaltsverzeichnis im Explorer-Baumstil an und erlaubt die bequeme Auswahl einzelner Seiten. Weitere Reiter bieten zusätzliche Komfort-Funktionen: einen Stichwort-Index, eine Volltextsuche und die Möglichkeit, sich Bookmarks (Favoriten) innerhalb der Datei zu setzen.

Im 'Output' Verzeichnis werden auch die Index-Dateien Index.hhk, PureBasic Help.hhp und Table of Contents.hhc gespeichert. Diese lassen sich im HtmlWorkshop auch noch nachträglich editieren. Danach einfach nochmal kompilieren.


V. PureBasic documentation
----------------------------
Die ganze PureBasic Dokumentation (in 3 Sprachen, im DocMaker Format), ist unter http://cvs.purebasic.com mit einem CVS-System zu bekommen.

Eine gute DocMaker Beispieldatei aus der Purebasic Hilfe, ist die Gadget.txt in dem CVS-System auf http://cvs.purebasic.com.

http://purebasicvs.dyndns.org/index.cgi ... text/plain


Bei Fragen zum DocMaker:
support@purebasic.com

[Deeem2031]

@SourceExample
<code hier>
<code hier>
<code hier>
<code hier>
@EndSourceExample ; Ende des SourceExample. Das Semikolon gilt wieder als Kommentar.

Seit wann heißt das SourceExample? Mein DocMaker mag nur "@code" und "@endcode".

Und dann gibts auch noch mehr Befehle, hier mal die ganze Liste:

Code: Alles auswählen

@library
@function
@title
@os
@elseos
@endos
@commandlist
@supportedos
@formatif
@formatelse
@formatendif
@bold
@code
@constantcolor
@Description
@endcode
@endfixedfont
@endindent
@example
@examplefile
@fastlink
@fixedfont
@functioncolor
@image
@indent
@internetlink
@keyword
@librarylink
@linebreak
@link
@mainguidelink
@referencelink
@section
@syntax
@overview
@Parameter
@parameters
@returnvalue
@underline

Wozu die alle gut sind weiß ich allerdings auch nicht

[Andre]

Hm, hätte ich vielleicht mal selber ins SDK schauen sollen, bevor ich eine neue Beschreibung der DocMaker-Tags von Null anfange...

Naja, im Ernst: bis zum aktuellsten DocMaker sind manche Tags geändert worden und einige neue dazugekommen. Ich schreibe dazu während meiner Arbeiten an der Hilfe nebenbei an einer ordentlichen Tabelle mit Beschreibung, Beispiel, etc. (daher als Word-Datei). Wenn die fertiggestellt ist, werde ich sie hier mit vorstellen.

Und - danke PAMKKKK für Deine Mühe

[PAMKKKKK]

@Deeem2031
Ich habe mir das aus dem Forumsarchiv zusamen gestockelt...
Na halleluja.... das ist ja ne lange Liste.
Wo hast du die denn her ?

Werde mich mal dran machen.........

@Adré es wäre eigentlich klug das OASIS OpenDocument Format als Quellformat zu benutzen. Da dieses in OpenOffice und vielen anderen Programmen zum Standart wird, und XML basierend ist.
http://books.evc-cit.info/

XML the future

[Deeem2031]

@Deeem2031
Ich habe mir das aus dem Forumsarchiv zusamen gestockelt...
Na halleluja.... das ist ja ne lange Liste.
Wo hast du die denn her ?

Einfach mal die Exen durchstöbern, manchmal findet man sehr interessante Dinge

[Danilo]

Es gibt aber auch chm-Betrachter für die Betriebssysteme
[...]
Linux: http://www.herdsoft.com/linux/themen/chmviewer.html

Da ich mich vor längerer Zeit auch mal intensiv mit meinem
Lieblingsformat HTMLHELP (.chm) und Linux beschäftigt habe,
möchte ich hier mal kurz auf KchmViewer verweisen:
http://kchmviewer.sourceforge.net/

Nachdem ich da einige Programme und Libs angeschaut hatte,
dachte ich schon es gibt nichts gescheites und ich muß mir
selber was schreiben. Mit KchmViewer hatte sich der Gedanke
aber dann erledigt. Es benutzt QT als GUI, kann aber auch
direkt als KDE-Version kompiliert werden.

Ich schreibe dazu während meiner Arbeiten an der Hilfe nebenbei an einer ordentlichen Tabelle
mit Beschreibung, Beispiel, etc. (daher als Word-Datei).

Wenn Du PB-Leute auf verschiedenen Platformen ansprechen
möchtest, dann wäre es doch überlegenswert HTML oder PDF
zu generieren, oder meinst Du nicht? Word-Dateien sind platformübergreifend
nicht so stark verbreitet da es ein geheimes Format von Microsoft ist,
weshalb es auf manchen Platformen keine 100% kompatiblen
Anzeigeprogramme dafür gibt. Für PDF gibt es dagegen auf allen
Platformen große Unterstützung, so wie auch für HTML.

Da Du schon seit Jahren an Microsoft Word festhältst, wirst
Du bestimmt nicht davon loslassen wollen. Über einen virtuellen
PDF-Drucker könntest Du es aber trotzdem in ein besseres
Format bekommen.

Das nur mal als Anregung für die Zukunft, vor allem wenn
Du mit Deinen Dokumenten Menschen auf vielen Platformen
ansprechen möchtest.

[PAMKKKKK]

@Danilo
danke für den CHM Tip. So fügt sich doch alles zusammen.
(ich hoffe du hast den Artikel auf pureWiki schon geändert


Zu dem DOC-Format kann ich nur sagen, ich würde auch in DOC schreiben, da ich Office XP original habe und Word gerade bei automatischen Inhaltsverzeichnissen usw. viele vorteile hat.

OpenOffice kann doch DOC lesen und schreiben, auch unter MAC, was ist nun so schlimm an DOC?

In zukunft empfehle ich OpenOffice 2.xx, da ab dieser Version das Standardisierte OASIS OpenDocument format genutzt wird. M$ wird diese Format nur lesend unterstützen, aber das kann uns ja wurst sein.

Mit OpenOffice 2.xx kann man dann auch HTML (daraus dann->CHM) und PDF exportieren.

OASIS OpenDocument ist ein ZIP komprimiertes XML Format und somit auch in 100 Jahren lesbar und mit jedem Editor schreibbar.
Es wird schon von vielen Firmen unterstützt, auch von IBM:
http://de.wikipedia.org/wiki/OpenDocument

Spezifikationen von OASIS OpenDocument:
http://books.evc-cit.info

[Danilo]

(ich hoffe du hast den Artikel auf pureWiki schon geändert

Nein, das ist Eure Sache und interessiert mich nicht.

OpenOffice kann doch DOC lesen und schreiben, auch unter MAC, was ist nun so schlimm an DOC?

Wie ich bereits sagte:

Word-Dateien sind platformübergreifend nicht so stark
verbreitet da es ein geheimes Format von Microsoft ist,
weshalb es auf manchen Platformen keine 100% kompatiblen
Anzeigeprogramme dafür gibt.

Bei OpenOffice gibt es immer mal wieder Formatierungsprobleme,
die das Dokument nicht sehr leserlich machen.

Schuld daran ist Microsoft selbst, denn dieses Unternehmen
zieht es vor geheime Dateiformate zu entwickeln und jegliche
Auskunft darüber zu verweigern. Das ist beim Word-Format
genauso der Fall wie auch bei HTMLHELP (.chm).

Da Microsoft nicht alle großen Betriebssysteme und Platformen
unterstützt, kann man nur versuchen das Format selbständig
zu entschlüsseln und entsprechende Bibliotheken zu schreiben,
was ziemlich am Rande der Legalität ist. Von daher ist ein unfreies
Format dieser Firma von vornherein abzulehnen, wenn man ein
freier Mensch bleiben möchte. Wer sich von MS abhängig macht
ist selbst Schuld.

Nach nun 10 Jahren Interneterfahrung, vor allem im Bereich
der Programmierszene, kann ich aber eindeutig sagen dass
das Word-Format hier keine Rolle spielt. Im DAU-Bereich ist
das sicherlich anders, da dort eh jeder nur Windows hat...
und ein (oftmals) geklautes MS Office dazu. In DAU-Zeitschriften
findet man dann wohl auch immer wieder Verweise auf MS Word
mit Tipps, Anleitungen und diesen Dokumenten.

PDF ist aber im Internet *das* Format für den platformübergreifenden
Dokumentenaustausch, was sicherlich auch durch die bessere
Politik von Adobe kam.
Für PDF gibt es mittlerweile auf allen Platformen entsprechende
Tools, ein paar kommerzielle, unzählige Freie.

PDF hat sich hier schon seit Jahren als Standard im Internet
durchgesetzt.
Ich habe in den letzten 10 Jahren viele viele Tausend Seiten
im Programmierbereich gesehen. Das Word-Format begegnet
mir da vielleicht 5mal im Jahr, genauso wie PostScript (.ps) und
ein paar andere Formate. PDF findet man dagegen aber überall,
ob bei Publikationen aus dem Bereich der Universitäten oder aus
dem Heimbereich.

Word ist im weltweiten Netz absolut unbedeutend.

OASIS OpenDocument ist ein ZIP komprimiertes XML Format
und somit auch in 100 Jahren lesbar und mit jedem Editor
schreibbar.

Das Gleiche gilt auch für das PB-Hilfe-Format, da es eben auch
reiner Text mit ein paar Formatierungstags ist, so wie auch
HTML.

Wichtig ist das man als Grundlage ein offenes Format nimmt.
Von diesem aus kann man dann mit einem eigenen Konverter
in andere Formate wandeln.
Das ist auch das Hauptproblem mit Microsofts Word. Wenn MS
eine neue geheime Version davon entwickelt, müssen sich erst
wieder ein paar Leute hinsetzen und es versuchen zu entschlüsseln.
Das dauert Zeit, wie man die letzten Jahre schon sehen konnte...

Die Frage ob man Word dafür nimmt stellt sich somit dem
klugen Anwender eigentlich garnicht erst, wenn er seine
Freiheit zu schätzen weiß. Wer will kann damit private Briefe
schreiben, für den weltweiten Dokumentenaustausch kommt
es aber nicht in Frage. Das zeigt auch die Realität im Netz, wo
dieses Format und dieses Programm keine Rolle spielen.

[PAMKKKKK]

@Danilo
Danke für dein Flame

[MARTIN]

@Danilo
Danke für dein Flame Wink

Flame hin oder her, er hat verdammt recht.

Wichtig ist das man als Grundlage ein offenes Format nimmt.

Schade dass es noch so viele nicht begriffen haben.

Und wenn man im Internet Word-Dateien findet, ist das meistens ein Hinweis auf einen Total-DAU.

Sorry für offtopic.