[AutoDocViewer] Bugs und Verbesserungen

Alles rund um Anwendungen für Amiga OS4

Moderator: OS4Welt-Team

Benutzeravatar
ZeroG
OS4Welt-Team
Beiträge: 2652
Registriert: 25. September 2009 18:19
Danksagung erhalten: 6 Mal

Re: [AutoDocViewer] Bugs und Verbesserungen

Beitrag von ZeroG »

Also es ist bestimmt nicht Sinn der Sache das irgendwer in den Autodocs was editiert. Entweder man ist Normalo dann ist es nicht sinnvoll die SDK Autodocs zu ändern, oder man ist im OS4-Team und muss den Text im Quelltext ändern und dann das Tool drüberlaufen lassen um wieder Autodocs zu erzeugen.
Benutzeravatar
amifrog
Beiträge: 733
Registriert: 16. Juni 2017 22:58

Re: [AutoDocViewer] Bugs und Verbesserungen

Beitrag von amifrog »

Das Editieren ist ja nur für den temporären Zweck, kurz für den Druck was rauszunehmen oder bevor man es rauskopiert, damit man nicht unnützes im Clipboard hat. Im Prinzip ist es auch eher zufällig, der Textview kann auch als Readonly eingestellt sein, aber so hat man mehr Optionen.:)
Das ist sowieso hinfällig, wenn man keinen Textview mehr hat, sondern ein Listview oder Treeview oder eine Kombination davon, weil diese normalerweise nicht editierbar sind, obwohl man den Listview natürlich auch aus Textfields zusammenbauen kann.
Benutzeravatar
Cyborg
AmigaOS Entwickler
Beiträge: 3461
Registriert: 28. September 2009 11:10
Hat sich bedankt: 12 Mal
Danksagung erhalten: 20 Mal

Re: [AutoDocViewer] Bugs und Verbesserungen

Beitrag von Cyborg »

@ amifrog

Danke für Deine Anmerkungen, hier meine Bemerkungen dazu:

1) Du störst Dich an der Dateiendung, ich finde sie sinnvoll -> bleibt vorerst so.

2) AutoDocViewer parst selbstverständlich bereits die AutoDocs in der Annahme, daß sich der Autor auch an die überlieferten Konventionen hält. Es gibt für die AutoDocs leider keine explizite Formatspezifikation, sondern nur sehr rudimentäre grenzen und Voraussetzungen, wie sie durch das "autodoc"-Tool zum Erstellen der AutoDocs vorgegeben werden. (gerade bei BOOPSI-Gadgets gibt es hier leider Wildwuchs.)

3) Was in der TOC steht, gilt als Sprungmarken und wird auch so behandelt, genauso wird immer nur der ausgewählte Eintrag dargestellt, solange die Formatierung eingehalten wurde. Wo Du hier siehst, daß dies "nicht konsequent" gemacht würde, kann ich nicht nachvollziehen.

4) Das Prefix in der TOC zu entfernen (z.B. "dos.library/") ist zu kurzsichtig. Es ist dazu gedacht, dem Autor die Möglichkeit zur thematischen Gruppierung zu geben. Insbesondere bei Bibliotheken mit mehreren Interfaces wird dies extrem wichtig, siehe z.B. application_lib.doc.

5) Teile eines Kapitels (oder Sektion oder "Funktionsseite") auszublenden, ist nicht sinnvoll bzw. birgt keinen erkennbaren Mehrwert. Die AutoDocs werden meist zum Nachschlagen verwendet, weshalb die Synopsis und Kurzbeschreibung in diesen Fällen das Wichtigste ist. Deshalb kommt dies auch am Anfang. Braucht man mehr Informationen, liest man weiter durch die detaillierte Beschreibung und ggf. Notes und bekannte Bugs.

6) AutoDocs edieren, auch temporär, schlägt in die gleiche Kerbe.


Alles in Allem erscheint mir, daß Du zumindest bei diesem Thema etwas zum klassischen "Overengineering" neigst. Man kann natürlich all das machen, was Du vorschlägst und noch viel mehr Aufwand betreiben. Aber letztlich birgt das alles keinen wirklichen Mehrwert für den Entwickler als Nutzer, der einfach nur eine bestimmte Funktion sucht oder verstehen will, wie und für was sie zu benutzen ist. Informationen auf den Punkt, ohne Schnickschnack, das ist der Sinn der AutoDocs. Aus dem gleichen Grund haben z.B. auch RFCs seit 30 Jahren das gleiche ASCII-Format und benutzen wissenschaftliche Autoren immer noch gerne LaTeX.
.. der SysOp hat immer recht :evil:

PGP Schlüssel verfügbar
Benutzeravatar
amifrog
Beiträge: 733
Registriert: 16. Juni 2017 22:58

Re: [AutoDocViewer] Bugs und Verbesserungen

Beitrag von amifrog »

zu 4) in der application.doc sind wirklich mehrere Interfaces drin, darum entferne ich in der toc nur den gleichen Teil, bis zum ersten /. ;) Also in der Gruppenüberschrift steht application.library, aber die toc behält die führenden application/ bzw.prefsobjects/.

Ich hab wahrscheinlich einfach nur andere Vorstellungen von der Benutzung. Wenn ich einen Eintrag betrachte, dann via See Also auf den Verweis springe, will ich öfters halt nicht nochmal Preface lesen.;)

Edit:
Screenshot (MacOS).
Du hast keine ausreichende Berechtigung, um die Dateianhänge dieses Beitrags anzusehen.
Zuletzt geändert von amifrog am 15. März 2020 03:08, insgesamt 2-mal geändert.
Benutzeravatar
Cyborg
AmigaOS Entwickler
Beiträge: 3461
Registriert: 28. September 2009 11:10
Hat sich bedankt: 12 Mal
Danksagung erhalten: 20 Mal

Re: [AutoDocViewer] Bugs und Verbesserungen

Beitrag von Cyborg »

Das verstehe ich nicht ... wir reden jetzt von AutoDocViewer 1.3, wie im os4depot zu finden? Wenn man dort unter "SEE ALSO" auf einen Funktionsnamen drückt, springt man selbstverständlich direkt zu dieser Funktion und nicht auf ein "preface" oder dergleichen .. und was das mit Deinem Entfernen des Library/Class-Namen im TOC-Pfad zu tun hat, ist mir auch nicht klar :thinking:
.. der SysOp hat immer recht :evil:

PGP Schlüssel verfügbar
Benutzeravatar
amifrog
Beiträge: 733
Registriert: 16. Juni 2017 22:58

Re: [AutoDocViewer] Bugs und Verbesserungen

Beitrag von amifrog »

Ach menno, nicht Preface, das andere, wie in meinem Screenshot. Also z.B. Synopsis, Examples,....
Wenn man zum nächsten Eintrag springt, dann ist dort auch z.B. Examples weggefiltert/gefaltet.
Also würde man z.B. vom ganzen Doc nur die jeweiligen Einträge und deren Examples sehen, keine Synopsis, keine Bugs....
Oder:
Nur die Einträge und Bugs...
Und nein, das hatte nichts mit deinem Punkt 4 zu tun, da fehlte ein Absatz.;)

Edit
Ich bin ziemlich schlecht mit Erklären, vielleicht schraub ich mal ein OS3/MUI Beispiel zusammen.
Zuletzt geändert von amifrog am 12. März 2020 22:46, insgesamt 1-mal geändert.
Benutzeravatar
ZeroG
OS4Welt-Team
Beiträge: 2652
Registriert: 25. September 2009 18:19
Danksagung erhalten: 6 Mal

Re: [AutoDocViewer] Bugs und Verbesserungen

Beitrag von ZeroG »

@Cyborg
amifrog schreibt gerade selber an einem Autodoc Viewer für PC, er bezieht sich da wohl auf sein eigenes Projekt.
viewtopic.php?f=7&t=2378
Benutzeravatar
amifrog
Beiträge: 733
Registriert: 16. Juni 2017 22:58

Re: [AutoDocViewer] Bugs und Verbesserungen

Beitrag von amifrog »

ZeroG hat geschrieben: 12. März 2020 19:54 @Cyborg
amifrog schreibt gerade selber an einem Autodoc Viewer für PC, er bezieht sich da wohl auf sein eigenes Projekt.
Nicht direkt. Ich versuche rauszubekommen, welche Funktionen Sinn machen würden. Ich schau mir die Docs normalerweise mit DOpus' Textanzeiger an. Das ist übel. Mein Ziel ist es, sowenig wie möglich reduntanten Text oder Uninteressantes zu lesen. Ich will nicht scrollen oder blättern wegen Sachen, die sich wiederholen. Ich will keine Anzeige von Wiederholungen, wenn es die Anzeige der Ausnahme auch tut, um die Information zu überliefern.
Cyborg ist da ja schon weiter und weiß daher auf viele dieser Fragen schon die Antwort.
Mein eigenes Tool ist nur ein Hilfsmittel zur Findung. Da ist nix geplant. Alles intern.
Benutzeravatar
Cyborg
AmigaOS Entwickler
Beiträge: 3461
Registriert: 28. September 2009 11:10
Hat sich bedankt: 12 Mal
Danksagung erhalten: 20 Mal

Re: [AutoDocViewer] Bugs und Verbesserungen

Beitrag von Cyborg »

Aha, verstehe. Dann würde ich Dich aber bitten, ein eigenes Thema für Deine Fragen und Gedanken zu machen. Hier geht es ja ganz konkret um "meinen" AutoDocViewer.

Abschließend sei noch zu erwähnen, daß die Kurzbeschreibung, Synopsis und detaillierte Beschreibung genau in dieser Reihenfolge wohl die wichtigsten Informationen im AutoDoc für einen Programmierer darstellen, dicht gefolgt von Beispiel, Bemerkungen/Bekannte Fehler und Querverweise. Die Reihenfolge ist also durchaus sinnvoll, ein Ausblenden von Teilen davon aber sicher (für die überwiegende Mehrheit der Entwickler) nicht.

So und jetzt bitte solche Sachen in Dein eigenes Thema auslagern und hier zurück zu "meinem" AutoDocViewer. Danke :)
.. der SysOp hat immer recht :evil:

PGP Schlüssel verfügbar
Benutzeravatar
ZeroG
OS4Welt-Team
Beiträge: 2652
Registriert: 25. September 2009 18:19
Danksagung erhalten: 6 Mal

Re: [AutoDocViewer] Bugs und Verbesserungen

Beitrag von ZeroG »

@Cyborg
Wäre es vielleicht sinnvoll einen (OS-) Include-Viewer einzubauen? Ist immer so ein Akt da was nachzusehen.
Antworten