GEOS Doku nicht mehr auf Github.io?

    • New

    Hallo Marcus,

    danke dass du dich um die Doku kümmerst. Das finde ich enorm wichtig! Etwas ist mir beim Stöbern aufgefallen: Die Groß/Kleinschreibung der Routinennamen stimmt nicht, sowohl in der Assemberreferenz als auch in der C-Referenz


    Gibt es eigentlich schon eine Entscheidung, dass nur noch eine Doku weiter gepflegt wird? Inhaltlich hat die Doku nämlich noch ein paar Lücken resp. Fehler. Da wäre es unnütze Arbeit, Dokus upzudaten, die dann kurzfristig entfernt werden.

    Rainer

    Es gibt 10 Arten von Menschen - die einen wissen was binär ist, die anderen nicht.

    • New

    Soweit ich mich erinnern kann, ist Markus da mit den Entwicklern des Doku-Tools dran.

    Die Diskussion bezüglich ASCII vs HTML vs MD hatten wir auch schon einmal angestossen, bin mir jetzt aus dem Effeff auch nicht mehr sicher, ob wir uns da auf ein definitives Format entschieden haben. Generell wird heute Markdown an ganz vielen Orten verwendent, da man damit Bilder, Tabellen, Links etc. wie bei HTML einbinden kann. Gegenüber HTML sehe ich in Markdown den Vorteil, dass es strukturierter und diff-barer ist. Eine ASCII Version liesse sich aus der Markdown oder HTML-Version generieren. Bei der Generierung einer HTML- / Markdown-Version aus der ASCII-Version wären dann aber zum Beispiel die Bilder eine Herausforderung.

    Übrigens können mittlerweile viele Editoren für Programmierer oft auch Markdown rendern. Und es gibt auch Tools für die Konsole, nur bekommt man da natürlich keine (vernünftigen) Bilder angezeigt...

    • New

    Ich hab mal ein bisschen die beiden anderen Formate (ASCII, HTML) mit Markdown verglichen, um den aktuellen Status zu haben und zumindest einen theoretischen Plan zu formulieren:

    • ASCII ist vermutlich die Grundlage, die John Howard verwendet hat, um die Markdown-Version zu erstellen:
      • Aufteilung in Dateien und Zeilenumbrüche sind (stichprobenweise) identisch, nur eben mit Markdown-Formatierung, Inline-Grafiken, Links statt Seitennummern usw. formatiert. Das muss eine Heidenarbeit gewesen sein...
      • Es ist noch ein Zoomer-spezifisches Kapitel enthalten, das noch kein Markdown-Gegenstück hat.
      • Außerdem gäbe es noch ein paar kleine Abschnitte von "historischem" Interesse, z.B. Credits (Namen der Doku-Autoren und beteiligen Entwickler) und Copyrights. Evtl. sind die es wert, erhalten zu bleiben.
    • HTML hat viele technische Übereinstimmungen, ist aber anders organisiert und enthält vor allem Communicator-spezifische Ergänzungen
      • Effektiv ist das die Dokumentation des Nokia 9000-SDKs, vermutlich stellenweise überarbeitet (1994 bis 1997)
      • Viele Abschnitte sind identisch mit dem Text der Markdown-Dokumentation - es gibt jeweils ein "combo.htm"-File, das alle HTML-Files eines Verzeichnisses zusammenfasst und das oft z.B. einem Oberkapitel in "Concepts" entspricht.
      • Nokia 9000-spezifiche Ergänzungen sind teilweise als getrennte Sektionen eingefügt (z.B. alles unter "Nokia9000", als auch alphabetisch in die Referenzen einsortiert (z.B. API-Routinen für Access Points und "Foam", also die Nokia-spezifischen APIs)

    Meine Einschätzung wäre daher: ASCII kann fast komplett weg, wenn man Zoomer-Teil und die Credits vorher noch irgendwo unter Markdown unterbringt, damit die Info nicht verlorengeht.

    HTML aus dem Nokia 9000 benötigt etwas sorgfältigere "Textarbeit", wenn man es retten will: erst mal die combo-Files so sortieren, dass die Struktur der Markdown-Doku entspricht, dann HTML>Markdown-Konverter, und dann die Unterschiede in Markdown einpflegen: die komplett plattform-spezifischen Abschnitte ziemlich en-bloc, und dann irgendwie (mit KI-Hilfe?) einen intelligenten Abgleich der überlappenden Teile machen.

    Der letzte Punkt dürfte dabei der aufwendigste sein, je nachdem, wie viele Korrekturen Geoworks bis zum Erscheinen des Nokia 9000-SDKs in die HTML-Version eingebaut hat und an wie vielen Stellen man einzelne Routinen, Structs usw. einsortieren müsste.

    • New

    mgroeber Herzlichen Dank für Deine Zusammenfassung. Das hört sich alles ganz plausibel an.

    jpolzfuss Danke für die Ergänzung.

    Eventuell sollten wir uns alle ein bisschen herumhören, was andere Doku-Teams zum Zusammenführen / Auditen verschiedener Stände verwenden. Da muss es doch sicher spezielle Diff- / Merge-Tools für solche Arbeiten geben. Gut möglich, dass die dann sogar Open-Source sind. Auch im akademischen Bereich ist das doch immer ein grosses Thema.