DWFixed in der HTML-Doku falsch

    In der HTML-Doku wird die Struktur von DWFixed so angegeben:

    Code
    typedef struct {
  word WWF_frac;
  dword WWF_int;
} DWFixed;

    In der CInclude-Datei geos.h heißt es so:

    typedef struct {
    word DWF_frac;
    sdword DWF_int;
    } DWFixed;

    Vom Compiler wird die geos.h - Version akzeptiert, die andere nicht.


    Wilfried

    Guter Fund.

    Da stellt sich natürlich die Frage welches Format der Doku wir weiterhin unterstützen wollen. Ich selber nutze nur noch die Online MarkDown Version.

    Alle drei Formate zukünftig zu pflegen halte ich nicht für sinnvoll, zumal die txt Version beispielsweise nicht die DDK Doku enthält.

    Was meint ihr?


    Jirka

    Es ist auch dein FreeGEOS!

    HTML aus meiner Sicht hat den Vorteil, dass die Suche und die Links problemlos funktionieren. Mit der MarkDown Version werde ich gar nicht warm. Womit kann man die komfortabel betrachten?

    Rainer

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

    Ich nutze nur die Markdwon Version, weil man die direkt aus dem Editor heraus gut betrachten kann. Das schöne an Markdown ist ja, dass es sowohl menschen- als auch maschinenlesbar ist. Auf Dauer 3 Dokumentationen am Leben zu halten halte ich auch für Irrsinn... Markdown ist ein guter Kompromiss zwischen reinem Text und formatiertem Text. Und man könnte jederzeit aus Markdown wieder HTML oder PDF oder sonstwas machen.

    Tja, so verschieden sind die Präferenzen.

    Bye,
    MeyerK

    Da ist eigentlich nichts zu erklären. Ich gucke mir halt den "rohen" Markdown Code an, so wie er von VSCode bei der Suche gefunden wird... falls man die gerenderte Ansicht wünscht, drückt man Ctrl+Shift+V ...

    Bye,
    MeyerK

    Na ja, und Du bist ja meist auch mit Deinem gut geölten Text-Editor unterwegs... (das Ding sollte auf seiner Webseite damit werben, dass eine komplette Programmierumgebung damit erstellt wurde!)

    Bye,
    MeyerK

    Eigentlich sollte genau eine Version der Doku gepflegt werden. Aus dieser können dann automatisiert die verschiedenen Varianten erzeugt werden. Dabei ist zu beachten, dass einerseits alle benötigten Attribute / Styles in der Quell-Doku vorhanden ist und die Erzeugung der weiteren Varianten nicht allzustark verkompliziert wird.

    Reine Text-Dateien so mit Ausführungen zu pflegen, dass dann damit die Styles für MD / HTML / PDF erzeugt werden kann, ist wahrscheinlich relativ umständlich. Die Hauptversion in HTML zu pflegen wäre auch eher unpraktisch. Persönlich würde ich am ehesten MD sehen. Es gibt Viewer dafür oder Editoren, welche den eingebaut haben. Und darin kann man wie bei HTML auch Links und Bilder haben.

    Ich muss zugeben, dass ich von MarkDown noch nichts gehört habe. Wie und wo kann ich darauf zugreifen?

    Bisher benutze ich die pdf- und die html-Versionen der Dokumentation. Die html-Version ist schnell im Zugriff, enthält aber die MSG_GO_...-Messages nicht. Die pdf-Version ist ergiebig in den Inhalten, im suchenden Zugriff aber umständlich.

    Wilfried

    Edited once, last by Wilfried (May 2, 2025 at 1:14 PM).

    Die Markdown Variante der Dokumentation wurde damals wohl von John F. Howard nach der Opensourcisierung beigesteuert, wenn ich das richtig in Erinnerung habe.

    pcgeos/TechDocs/Markdown at master · bluewaysw/pcgeos
    #FreeGEOS source codes. The offical home of the PC/GEOS operating system technology. For personal computing fans. For all developers and assembly lovers. For…
    github.com

    Bye,
    MeyerK

    Ich sehe das auch so, dass auf die Dauer nur eine Version der Doku "von Hand" gepflegt werden sollte (vermutlich am besten Markdown), und die HTML-Doku dann regelmäßig automatisch daraus erzeugt wird. Bevor wir sie überschreiben, sollten wir aber vielleicht noch mal vergleichen, was drinsteht. Dass man die HTML-Variante sogar direkt in Geos lesen kann, ist natürlich ein Argument dafür, das Format beizubehalten (mit minimalem CSS).

    Die Text-Version ist m.E. vermutlich auf Dauer ganz obsolet (weil MD ja sogar im Editor fast so gut lesbar ist wie plain text, bis auf ein paar Sonderzeichen) - wenn wir auch sicher sein können, dass es dort nicht noch Infos gibt, die wir nicht in Markdown haben.

    Übrigens: ich habe unter https://mgroeber9110.github.io/just-the-docs-test/ eine Testversion für Verbesserungen an der Dokumentation aufgesetzt. Im Moment sieht es noch ziemlich ähnlich aus, verwendet intern aber schon die aktuellen Versionen von jekyll und just-the-docs für die Konvertierung. Mein Plan ist, da erst mal Verbesserungen zu testen und dann in wenigen PRs zu sammeln.

    Der Inhalt ist evtl. veraltet, weil ich einen früheren Schnappschuss der Markdown-Files verwende - es geht hier nur um das Format der Webseite, Suchfunktion usw. Ein paar Sachen, die mir aufgefallen sind und die ich mir gerade ansehe:

    • Das Laden großer Seiten friert bei mir für eine Sekunden ein, wenn man zu schnell scrollt, weil im Hintergrund erst mal die Suchfunktion den Index aufbaut. Leider passiert das bei jeder Seite neu. Dafür habe ich auch schon ein Issue bei just-the-docs geschrieben: https://github.com/just-the-docs/just-the-docs/issues/1396
    • Suche nach Stichworten führt immer zum Anfang des Dokuments, anstatt zur Zwischenüberschrift des Kapitels mit dem Begriff.
    • Sortierreihenfolge in der Übersicht stimmt nicht für alle Kapitel, weil lexikalisch und nicht numerisch sortiert wird (1, 10, 11, 2).