Dokumentationen verfassen

[Christian]

Hi,

weiß einer wie ich große Dokumentationen verfasse?? Beispiel SelfHTML, wie ist das technisch realisiert??
Oder php.net oder mysql.com ....

Ich kann mir vorstellen, dass die Texte in einer Datenbank abgelegt werden, und dann mit einem Programm ausgelesen werden und zu einer Dokumentation zusammengefügt werden. Ich kann mir nicht vorstellen, das das alles als statische HTML-Seiten geschrieben wird, da die Wartung und Pflege dann sehr schwer fällt.

Hat da jemand genauere Infos?

Christian

[Rouven]

Hi,

wenn du als Beispiel das JDK (also die Java-Dokumentation) nimmst, dafür gibt es im JDK ein kleines Konsolenprogramm, dem gibst du den Pfad zu deinen Quelltexten an und dann erstellt er daraus eine Funktionsreferenz. Da gibt es dann noch so kleine technische Feinheiten wie Kommentare die mit ** anfangen und irgendwelche Tags, so dass man seinen Quellcode bereits so kommentiert, dass dieser Interpreter hinterher was damit anfangen kann und das nimmt er dann alles in seine Hilfe mit auf, Resultat sind dann Autoreninformationen, Parameterinformationen und solche Sachen.
Ist eine recht faszinierende Sache.

MfG
Rouven

[Christian]

Hi,

wenn du als Beispiel das JDK (also die Java-Dokumentation) nimmst, dafür gibt es im JDK ein kleines Konsolenprogramm, dem gibst du den Pfad zu deinen Quelltexten an und dann erstellt er daraus eine Funktionsreferenz.

Frage war eher: WIE ?? Und in welcher Form liegen diese Quelltexte vor? Sind diese bereits HTML formatiert?? Wie werden diese dann verknüpft...?? Wie sind z.B. die Überschriften, die Beispielcodes abgelegt?? Nicht in Datenbanken?

Da gibt es dann noch so kleine technische Feinheiten wie Kommentare die mit ** anfangen und irgendwelche Tags, so dass man seinen Quellcode bereits so kommentiert,

Mit Quellcode meinst du also o.g. Quelltexte? Woher weiß der Interpreter wie er diese Text zu verlinken hat??

Christian

[Michael Schröpl]

Hi Christian,

Mit Quellcode meinst du also o.g. Quelltexte? Woher weiß der Interpreter wie er diese Text zu verlinken hat??

wenn der entsprechende Interpreter die Programmiersprache selbst so weit versteht, daß er
 a) Modul-APIs und
 b) Funktionsaufrufe solcher APIs
automatisch erkennen kann, dann kann er auch "Code generieren" - im vorliegenden Fall dann eben Dokumentations-Code ("HTML-Module") statt Objekt-Code ("Maschinencode-Module").
An jede Aufrufstelle automatisch einen Link (nach derjenigen Stelle, wo die aufgerufene Funktion im Detail beschrieben ist) zu setzen, wenn in einem vorhergehenden Durchgang sämtliche Link-Ziele aufgesammelt wurden, ist kein prinzipielles Problem.

Ein solcher Interpreter wird also sicherlich einen gewissen Teil von Programmcode des normalen Compilers enthalten - in gewisser Weise ist es ja auch ein "Compiler", nur eben für eine ungewöhnliche "Plattform" ... nämlich für den Browser statt für den Programm-Linker.

Viele Grüße
      Michael

[Thomas J.S.]

Hallo,

Frage war eher: WIE ?? Und in welcher Form liegen diese Quelltexte vor? Sind diese bereits HTML formatiert?? Wie werden diese dann verknüpft...?? Wie sind z.B. die Überschriften, die Beispielcodes abgelegt?? Nicht in Datenbanken?

Wenn du keine Java-Doku erstellen willst, kanns du diesen Weg vergessen. Der ist genau darauf ausgerichtet Java-Dokus zu schreiben.
http://java.sun.com/j2se/javadoc/

Mit Quellcode meinst du also o.g. Quelltexte? Woher weiß der Interpreter wie er diese Text zu verlinken hat??

Mit Quellcode meinte er den Java-Programmcode.

Grüße
Thomas

[Thomas J.S.]

Hallo,

Ich kann mir vorstellen, dass die Texte in einer Datenbank abgelegt werden, und dann mit einem Programm ausgelesen werden und zu einer Dokumentation zusammengefügt werden.

Üblich ist bei vielen großen Dokumentationen, dass die Texte in SGML- oder XML-Dateien abgelegt werden und dann mit DSSSL in verschiedene Ausgabeformate umgewandelt werden. (Stichwort z.B. DocBook)

»»Ich kann mir nicht vorstellen, das das alles als statische HTML-Seiten geschrieben wird, da die Wartung und Pflege dann sehr schwer fällt.

SELFHTML ist aber so geschrieben worden.

Es ist auch eine Frage der Planung und "selbst Organisation" wie man Dokumentationen angeht und anlegt.

Grüße
Thomas

[Michael Schröpl]

Hi Christian,

Oder php.net oder mysql.com ....

bei Dokumentationen über große Programmsysteme gibt es diverse auf diesen Zweck zugeschnittene Konzepte.

Eines davon - schon recht alt, aber als Beispiel gut zu gebauchen - ist das Konzept "Web" von Donald Knuth. (Nein - mit dem World Wide Web hat das nichts zu tun.)
Die 'Quelltexte' eines solchen Systems enthalten nicht nur Anweisungen einer entsprechenden Programmiersprache, sondern gleichzeitig die Dokumentation der entsprechenden Funktionseinheiten (Module etc.).
Aus den entsprechenden Dateien werden dann mit separaten Tools die einzelnen 'Varianten' überhaupt erst mal generiert - einerseits der dann reine Programmquelltext, andererseits die hochwertig aufbereitete Dokumentation.
Bei Knuth's "Web" heißen diese Tools "tangle" und "weave" - und die generierte Dokumentations-Form ist natürlich TeX (was aber nur am konkret verwendeten Tool liegt - heute könnte es fast genauso gut HTML sein).
Perl unterstützt anscheinend ein ähnliches Konzept mit seinen PODs (und wahrscheinlich noch einiges mehr, das ich selbst gar nicht kenne).

Sinn der Sache ist, daß derjenige die _inhaltliche_ Seite der Dokumentation übernimmt, der versteht, was er schreibt - während die technische Seite der Präsentation davon stark abgegrenzt wird und Layout-Spezialisten (oder eben sogar Programmen) überlassen werden kann.
Außerdem steht dann die Dokumentation insbesondere dort, wo man sie braucht, wenn man das Programm ändern muß - nämlich im Programm selbst. Und derjenige, der das Programm pflegt, braucht kein separates Werkzeug für die Erstellung der Dokumentation ...
Hast Du schon mal einen Umzug einer Firma auf ein anderes Betriebssystem mitgemacht? Es gab auch schon vor Windows Dokumentationen ... in Formaten, die Du Dir heute gar nicht mehr vorstellen kannst. Und wenn sich die Dokumentationsplattform ändert, die Entwicklungsplattform aber nicht, wer portiert dann die vielen hundert Dateien der Dokumentation auf das neue Dateiformat?

Ich kann mir vorstellen, dass die Texte in einer Datenbank abgelegt werden, und dann mit einem Programm ausgelesen werden und zu einer Dokumentation zusammengefügt werden.

Auch das kann man sicher tun. Ersetze Datenbank durch XML, Edifact oder beliebige weitere Meta-Formate, dann hast Du weitere Möglichkeiten.

Ich kann mir nicht vorstellen, das das alles als statische HTML-Seiten geschrieben wird, da die Wartung und Pflege dann sehr schwer fällt.

Hier ist mir der kausale Zusammenhang dieser beiden Aussagen nicht zwingend klar.

Eine saubere Trennung zwischen Inhalt und (einheitlichem) Layout ist gerade bei Verwendung von CSS einerseits und der Generierung von HTML-Dokumenten (SSI, PHP, Makro-fähige Editoren etc.) andererseits sehr wohl möglich.
Was dafür allerdings notwendig ist, das ist die Beherrschung sowohl der inhaltlichen als auch der präsentationstechnischen Skills durch dieselbe Person, da beide in derselben Abstraktionsebene ausgedrückt werden - nämlich im Quelltext.
Andererseits kann man durchaus immer noch Teile der Funktionalität auslagern - beispielsweise kann ein Spezialist die Pflege aller CSS-Definitionen übernehmen, während die Autoren lediglich HTML und die für dieses Projekt vorgegebenen Klassennamen verwenden können müssen ...

Es gibt viele Wege, die hier zum Ziel führen - weil es viele verschiedene Ziele gibt. Diese hängen nicht unwesentlich von den bereits verfügbaren Skills der teilnehmenden Personen ab.

Viele Grüße
      Michael

[norbert =:-)]

Hallo Christian!

Ich kann dir nur XML ans Herz legen - Du überlegst Dir einmal alle notwendigen Elemente der Doku und kannst dann alles mögliche damit anstellen (in HTML konvertieren, als Text ausgeben, und, und, und). Und wenn Du dir die Anforderungen gut überlegt hast, ändert sich die Datei so gut wie nicht mehr - Erweiterungen natürlich jederzeit möglich.

Ich selbst erstelle so zB Webseiten, die Aufgrund der vorgegebenen, eingeschränkten Möglichkeiten kein PHP o.ä. zulassen - so kann ich einerseits auf programmiertechnische Grundlagen zurückgreifen (Schleifen, Abfragen, Includes,...) und trotzdem statische Seiten erzeugen.

Wenn Du eine Demo sehen willst, musst Du nochmal posten - ich lade mein aktuelles Projekt dann kurz ins Netz.

mfg

norbert =:-)

[Christian]

Hi,

Ich kann dir nur XML ans Herz legen - Du überlegst Dir einmal alle notwendigen Elemente der Doku und kannst dann alles mögliche damit anstellen (in HTML konvertieren, als Text ausgeben, und, und, und). Und wenn Du dir die Anforderungen gut überlegt hast, ändert sich die Datei so gut wie nicht mehr - Erweiterungen natürlich jederzeit möglich.

kannst du das näher erläutern??

also ich stelle mir dein konzept etwa so vor:

<thema>
<title>Wie erstelle ich eine Doku</title>
<beschreibung>viel text</beschreibung>
<beispiel>beispiel</beispiel>
<erlaeuterung>text<erlaeuterung>
<sieheauch>verweis auf links</sieheauch>
<beachtensie>bemerkungen</beachtensie>
</thema>

wie lese ich das dann aus?? Alle <beispiel>e sollen z.B. einem bestimmten Format entsprechen. eingerückt und besondere Schrift.

wie mach ich das dann?

letzt endlich soll dann html rauskommen.

wie ist es wenn ich innerhalb von xml-tags html verwenden will:

<beachtensie>bemerkungen</beachtensie>

bemerkungen soll z.B. einige kleine Formatierungen oder Verweise haben. iSt das auch möglich?

Meine ganzen Dokus möchte ich auf eine ähnlich einfache Weise so ablegen können (bisher hatte ich die mit ner Datenbank). Aber du kannst mich gerne auch von den Vorteilen von XML überzeugen. Dann will ich mir ein kleinen Programm schreiben, das die ganzen XML-Dateien abgrast und daraus HTML generiert. Und alles schön verlinkt.
Programmiersprache???

Ich selbst erstelle so zB Webseiten, die Aufgrund der vorgegebenen, eingeschränkten Möglichkeiten kein PHP o.ä. zulassen - so kann ich einerseits auf programmiertechnische Grundlagen zurückgreifen (Schleifen, Abfragen, Includes,...) und trotzdem statische Seiten erzeugen.

Das geht doch mit XSL oder ?? xsl:blabla...</xsl:blabla> oder so ähnlich

Wenn Du eine Demo sehen willst, musst Du nochmal posten - ich lade mein aktuelles Projekt dann kurz ins Netz.

gerne

Gruß
Christian

[norbert =:-)]

Hallo Christian!

Dein Ansatz ist absolut korrekt - wie du das dann konvertierst, ist eigentlich zweitrangig - du musst es dir aber schon ansatzweise überlegen ...

Auf http://www.imalyzer.com/de/index.xml hast du einige xml-Dateien (mit IE öffnen - derzeit der einzige, der XML/XSL unterstützt) - es funktionieren nur die ersten vier Menüpunkte und die E/D-Umschaltung. Du siehst also einige wenige XML-Tags im Quellcode.

In HTML übersetzt (inkl. aller Menüs, usw.) wird das ganze durch http://www.imalyzer.com/online.xsl - also einer XSL-Datei. In der selben Art kannst du auch andere Formate umsetzen.

Solltest Du mehr Infos brauchen, schau ich morgen nochmal rein - ansonsten viel Spaß beim stöbern ...

mfg

norbert =:-)

[Christian]

Hallo Christian!

Dein Ansatz ist absolut korrekt - wie du das dann konvertierst, ist eigentlich zweitrangig - du musst es dir aber schon ansatzweise überlegen ...

Hm, in deinem Projekt wird es ja nicht wirklich konvertiert... du brauchst ja immer noch einen XSL-fähigen Browser. Ich möchte aber reinen HTML-Code haben, so dass die Doku auf jedem Browser läuft.

Ich glaube ich mach das doch mit DBs. Muss mir mal ein Konzept überlegen.

In HTML übersetzt (inkl. aller Menüs, usw.) wird das ganze durch http://www.imalyzer.com/online.xsl - also einer XSL-Datei. In der selben Art kannst du auch andere Formate umsetzen.

wie gesagt ich möchte HTML-Dateien haben, keine XML-Dateien die durch XSL übersetzt werden.

Aber vielen Dank für deine Mühe! XML/XSL scheint ja sehr interessant zu sein.

Ein Grund mehr FÜR IE!

BTW: Wieso gestaltest du deine Seiten damit, wenn die nur im IE funzen??

Christian

[norbert =:-)]

Hallo Christian!

Natürlich kannst Du das auch in HTML-Dateien speichern - zB mit dem Kommandozeilentool MSXSL von MS und vielen anderen. Ich erstelle ja auch keine Produktseiten als XML-Dateien! Ich wollte nur Demonstrieren, dass Du einfach lokal arbeiten und mit dem Browser testen kannst, wie das spätere Ergebnis ausssieht.

Als Beispiel - auch http://www.divina.at/ wurde mittels XML erstellt - hervorragend geeignet (gleiche Grundstruktur aller Seiten) und jetzt sind es HTML-Dateien ;-)

Wenn ich fertig bin, wird alles konvertiert und als HTML hochgeladen. Zur Bearbeitung habe ich ein selbstentwickeltes Programm (komfortable Anzeige und Manipulation der Baumstruktur), mit dem ich die Files auch gleich konvertieren kann.

Es lohnt in jedem Fall, sich mit XML auseinander zu setzen!

mfg

norbert =:-)

[Thomas J.S.]

Hallo Christian,

Ich möchte aber reinen HTML-Code haben, so dass die Doku auf jedem Browser läuft.

Du kommst nicht darum herum dir etwas über XML (XML/XSL-Parser etc.) anzulesen!

Fang am besten mit [link.http://selfhtml.teamone.de/xml/index.htm] an.

Grüße
Thomas

[Johannes Zeller]

Hallo Christian

Dein Ansatz ist absolut korrekt - wie du das dann konvertierst, ist eigentlich zweitrangig - du musst es dir aber schon ansatzweise überlegen ...

Hm, in deinem Projekt wird es ja nicht wirklich konvertiert... du brauchst ja immer noch einen XSL-fähigen Browser. Ich möchte aber reinen HTML-Code haben, so dass die Doku auf jedem Browser läuft.

Dann brauchst du einen XSL-Prozessor, mit dem du die Seiten in statisches HTML konvertieren kannst. Du kannst das ganze auch serverseitig vor jedem ausliefern machen, aber das geht nur auf kosten der Perdormance.

Ein Grund mehr FÜR IE!

BTW: Wieso gestaltest du deine Seiten damit, wenn die nur im IE funzen??

Der IE ist der einzige Browser, der bei XML-Dateien die Datenstruktur anzeigt. Andere Browser wie Opera zeigen nur die Inhalte der einzelnen Elemente an, haben aber kein Problem mit XML, dass mit Anweisungen in CSS oder XSLT angezeigt werden soll.

Schöne Grüße

Johannes

[Thomas J.S.]

Hallo Nordert,

(mit IE öffnen - derzeit der einzige, der XML/XSL unterstützt) -

Stimmt nicht ganz. Mozilla kann es auch, aber dazu muss man HTML als HTML kennzeichen:

Warum so?
<xsl:output method="xml" indent="yes" encoding="ISO-8859-1" omit-xml-declaration="yes" />

So versteht es IE und Mozilla und ist dazu auch noch richtig.
<xsl:output method="html" indent="yes" encoding="ISO-8859-1" />

Schöne Grüße
Thomas

[norbert =:-)]

Hallo Thomas!

Stimmt nicht ganz. Mozilla kann es auch

Tatsächlich. Arbeite schon länger mit MSXML, IE und Co und habe mich daher nicht weiter gekümmert - aber jetzt, wo du es erwähntest, hab ich getestet und war begeistert.

aber dazu muss man HTML als HTML kennzeichen:

Daran liegts wohl, dass die Seiten in Mozilla nicht ganz so toll aussehen. Aber eigentlich wollte ich ja nur eine "Vorschau" zum Endergebnis haben - und da dies mit MSXSL generiert wird, ist auch der IE das Mittel meiner Wahl.

Warum so? ... So versteht es IE und Mozilla und ist dazu auch noch richtig.

Stimmt eigentlich - nur der IE (oder eben MSXSL) generiert automatisch einen Meta-Tag mit einem CharSet, das mir aber Probleme mit den Umlauten bereitet - und auf die möchte ich auch in den Tags nicht verzichten - ist also so eine Art Workaround und für meine Zwecke ganz ok, da die XML-Files ohnehin nur intern verwendet werden ;-)

mfg

norbert =:-)

[Thomas J.S.]

Hallo Norbert,

Aber eigentlich wollte ich ja nur eine "Vorschau" zum Endergebnis haben - und da dies mit MSXSL generiert wird, ist auch der IE das Mittel meiner Wahl.

Meinst du den Command Line Tool "MSXSL.EXE"?

Stimmt eigentlich - nur der IE (oder eben MSXSL) generiert automatisch einen Meta-Tag mit einem CharSet,

Normalerweise, wenn man in der XML- und in der XSL-Datei plus in xsl:output die richtige Charsetangabe macht, dürfte es nirgendwo Probleme mit den Umlauten geben. Wenn der msxsl.exe trotz dieser 3 Angaben noch was eigenes produziert, ist das ein Bug im Programm.

Ich habe das jetzt mal schnell ausprobiert bei mir:
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="html" indent="yes" encoding="ISO-8859-1" />
<xsl:template match="/"
....

in der generierten HTML-Datei steht nun die Zeile:
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> (wobei der msxsl.exe indent="yes" ignoriert)

Schöne Grüße
Thomas

[norbert =:-)]

Hallo Thomas!

Meinst du den Command Line Tool "MSXSL.EXE"?

Yo.

Ich habe das jetzt mal schnell ausprobiert bei mir:

...

in der generierten HTML-Datei steht nun die Zeile:
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> (wobei der msxsl.exe indent="yes" ignoriert)

War bei mir eben nicht der Fall - vielleicht hab ich aber noch eine "Buggy"-Version - werde mal die neueste Version runterladen.

Vielen Dank für diese Info!

mfg

norbert =:-)