Zum Thema Commandref

Begonnen von Damian, 28 Dezember 2021, 19:04:20

Vorheriges Thema - Nächstes Thema

Damian

Programmierte FHEM-Module: DOIF-FHEM, DOIF-Perl, DOIF-uiTable, THRESHOLD, FHEM-Befehl: IF

Benni

#1
Ich bin mir jetzt nicht so sicher ob im Sinne von:

    https://wiki.fhem.de/wiki/SVN_Nutzungsregeln#commandref-Regeln

ein Link auf das wiki ausreichend ist!

Ich finde es halt in sofern schade, dass damit die Offline-Doku für das Modul quasi keine Information mehr enthält.
Vor allem, da FHEM an sich mit "Cloud-Free" wirbt
Gerade DOIF ist ja ein Modul ist, das ansonsten keine Cloud benötigt.
Wenn das Schule macht sind wir bei FHEM demnächst so weit wie bei M$ und anderen, wo jede Doku nur noch Online verfügbar ist.

Man sollte hier vielleicht differenzieren zwischen minimaler Commandref (!) und ausführlicher Doku, mit Beispielen und Trallala.

Auf der anderen Seite haben wir aber auch schon die Fragmentierung in svn und diverse einbindbare git-repositories. Kann man auch so oder so sehen.

gb#

marvin78

Man muss einfach nur lernen zwischen Doku und Beispielsammlung zu unterscheiden. Dann ist klar, was wohin gehört und dann kann man auch Doif endlich richtig dokumentieren.
.

Damian

#3
Zitat von: marvin78 am 30 Dezember 2021, 06:52:27
Man muss einfach nur lernen zwischen Doku und Beispielsammlung zu unterscheiden. Dann ist klar, was wohin gehört und dann kann man auch Doif endlich richtig dokumentieren.
.

Eine DOIF-Dokumentation, die aus Syntaxbeschreibung bestehen würde, würden die wenigsten FHEM-User verstehen. Wenn ich etwas nachschlagen will, dann schlage ich dort nach, wo ich die Syntax nachlesen kann und gleich ein typisches Beispiel ansehen kann um diese zu verstehen, ohne irgendwo im Web nach Anwendungsbeispielen zu suchen. Das ist genauso z. B. beim notify oder at (wo ist die Doku zum Dummy ;) ), deren Doku-Umfang mit Beispielen! in der Commandref dürfte im gleichen Verhältnis zu deren Funktionsumfang stehen, wie die DOIF-Doku zu DOIF-Funktionsumfang.

Abgesehen davon lässt sich Dokumentation im Wiki einfacher erstellen und pflegen, besser strukturieren und wesentlich übersichtlicher gestalten.
Programmierte FHEM-Module: DOIF-FHEM, DOIF-Perl, DOIF-uiTable, THRESHOLD, FHEM-Befehl: IF

Damian

Zitat von: Benni am 29 Dezember 2021, 22:21:59
Ich bin mir jetzt nicht so sicher ob im Sinne von:

    https://wiki.fhem.de/wiki/SVN_Nutzungsregeln#commandref-Regeln

ein Link auf das wiki ausreichend ist!

Ich finde es halt in sofern schade, dass damit die Offline-Doku für das Modul quasi keine Information mehr enthält.
Vor allem, da FHEM an sich mit "Cloud-Free" wirbt
Gerade DOIF ist ja ein Modul ist, das ansonsten keine Cloud benötigt.
Wenn das Schule macht sind wir bei FHEM demnächst so weit wie bei M$ und anderen, wo jede Doku nur noch Online verfügbar ist.

Man sollte hier vielleicht differenzieren zwischen minimaler Commandref (!) und ausführlicher Doku, mit Beispielen und Trallala.

Auf der anderen Seite haben wir aber auch schon die Fragmentierung in svn und diverse einbindbare git-repositories. Kann man auch so oder so sehen.

gb#

Naja, zur Laufzeit wird keine Cloud benötigt. Dokumentation zu irgendetwas ist nicht sicherheitsrelevant und steht heutzutage natürlich im Netz - wo denn sonst :)
Programmierte FHEM-Module: DOIF-FHEM, DOIF-Perl, DOIF-uiTable, THRESHOLD, FHEM-Befehl: IF

martinp876

eine syntaktische Kommandobeschreibung mache ich immer online - im code beiliegend. Somit sehe ich das 3-stufig
1) liste aller Kommandos mit required und optional parameter
=> insbesondere hilfreich für Entites mit vielen Kommandos
=> schneller Überblick über Reihenfolge der Parameter, schreibweise, options - in listenform
=> kurze notes möglich
=> Beschreibung eines Kommandos sollte in 1 Zeile passen
=> da im Code liegend wird dies auch gleich zum Parsen des Inputs genutzt (siehe Vorschlag  https://forum.fhem.de/index.php/topic,125067.0.html)
Insbesonder Module deren entities unterschiedliche Kommandos unterstützen (das trifft sicher 99% der Home-Automation familien) ist eine Kommando-kurzübersicht hilfreich, m.E. Pflicht (incl dedicted attr list)

2)commandref
ist mit mehr prosa versehen - Beschreibung wird eingeblendet. Das MUSS offline funktionieren - oder abgeschafft werden. Online geht hier nicht.

3) Wiki
Hier steht die Handhabung

DOIF ist sicher kein Paradebeispiel für diese Art von Dokumentation. Es ist eher als Meta-sprache angelegt - und ist wohl nur im Wiki zu erklären. Es als Massstab für die Doku zu sehen ist m.E. grundsätzlich ungeeignet.

Damian

Ich werde den Großteil der DOIF-Doku in der Commandref belassen, da inzwischen für die Attribute oder Set-Befehle, eine lokale Hilfe eingeblendet wird und viele Querverweise existieren. Ich habe mich lange Zeit gegen Wiki-Einträge gesträubt, weil dort auch andere, unwissende "Unsinn" verfassen können. Allerdings habe ich positive Erfahrung bei der Beschreibung des komplexen DOIF-Attributes uiTable https://wiki.fhem.de/wiki/DOIF/uiTable_Schnelleinstieg gesammelt - dort traut sich offenbar keiner seinen Senf dazu zu tun - und das ist auch gut so. Auf jeden Fall kann ich aus meiner Erfahrung sagen, dass sich Dokumentation mit diversen Formatierungsmöglichkeiten im Wiki wesentlich einfacher erstellen und pflegen lässt, als es im Sourcecode zu tun.
Programmierte FHEM-Module: DOIF-FHEM, DOIF-Perl, DOIF-uiTable, THRESHOLD, FHEM-Befehl: IF

martinp876

nun habe ich mir DOIF einmal angesehen - bezüglich Doku:
Commandref existiert eigentlich nur in Deutsch. Ich dachte immer die standart-Sprache ist Englisch. Wenn nur eine Sprache existiert sollte man das deutlic machen. Die Fragmente in Englisch kann man geradezu weglassen - oder eben vervollständigen. Da ist man mit einem auto-übersetzer noch besser dran.

Irgend etwas scheint nicht korrekt dokumentiert zu sein - zumindst ich bekomme die Bespiele mit "package ui_Table" nicht zum Laufen. Den einfachen Hinweis, was bei mir nicht installiert ist, habe ich zumindest noch nicht gefunden.

uiTable is ein echt cooles feature - wenn ich es einmal zum Laufen bekomme. Allerdings ist es M.E. völlig falsche aufgehängt. DOIF ist ein "Event 2 trigger" funktion welche auf Basis von Events irgend etwas auslöst.
uiTable ist - so ist es auch beschrieben, ein Web-Frontend. Es hat eigentlich mich DOIF garnichts zu tun. Ich finde es daher exterm schade, dass es nicht so angelegt ist. Für mich sieht es so aus, dass ein Autor sich eine - mit Sicherheit! - coole Funktion/Feature hat einfalle lassen - und es eben einmal in irgend ein gerade greifbares Modul eingebaut, welches gerade in seinem Edditor offen war. Für den System-gedanken halte ich das für nicht hilfreich.
De-fakto bietet DOIF eine reine Visualisierung von beliebigen Enties an.

Sinnvoll wäre, ein eigenes Modul zu erstellen, was ich überall einsetzen kann - oder einen Helper welcher von jeden Device genutzt werden kann.

Damian

#8
Zitat von: martinp876 am 15 Januar 2022, 12:53:56
nun habe ich mir DOIF einmal angesehen - bezüglich Doku:
Commandref existiert eigentlich nur in Deutsch. Ich dachte immer die standart-Sprache ist Englisch. Wenn nur eine Sprache existiert sollte man das deutlic machen. Die Fragmente in Englisch kann man geradezu weglassen - oder eben vervollständigen. Da ist man mit einem auto-übersetzer noch besser dran.

Irgend etwas scheint nicht korrekt dokumentiert zu sein - zumindst ich bekomme die Bespiele mit "package ui_Table" nicht zum Laufen. Den einfachen Hinweis, was bei mir nicht installiert ist, habe ich zumindest noch nicht gefunden.

uiTable is ein echt cooles feature - wenn ich es einmal zum Laufen bekomme. Allerdings ist es M.E. völlig falsche aufgehängt. DOIF ist ein "Event 2 trigger" funktion welche auf Basis von Events irgend etwas auslöst.
uiTable ist - so ist es auch beschrieben, ein Web-Frontend. Es hat eigentlich mich DOIF garnichts zu tun. Ich finde es daher exterm schade, dass es nicht so angelegt ist. Für mich sieht es so aus, dass ein Autor sich eine - mit Sicherheit! - coole Funktion/Feature hat einfalle lassen - und es eben einmal in irgend ein gerade greifbares Modul eingebaut, welches gerade in seinem Edditor offen war. Für den System-gedanken halte ich das für nicht hilfreich.
De-fakto bietet DOIF eine reine Visualisierung von beliebigen Enties an.

Sinnvoll wäre, ein eigenes Modul zu erstellen, was ich überall einsetzen kann - oder einen Helper welcher von jeden Device genutzt werden kann.

Das kann man natürlich sehen, wie man will. Würde FHEM einen internationalen Ruhm erlangen, hätte ich längst den englischen Part ergänzt. Für 3% der FHEM-User war mir seinerzeit der Aufwand für eine ständige Übersetzung neuer Features (und es waren einige) zu hoch.

uiTable sollte mit der aktuellen FHEM-Version funktionieren. Im Verzeichnis pgm2 sollte sich die Datei doif.js befinden.

Naja, uiTable arbeitet ebenfalls ereignisgesteuert, daher wird der größte Programmteil von DOIF: Auswertung von Ereignistriggern mit [<DOIF-Syntax für Ereignistrigger>] benötigt.

An solchen Beispielen: https://wiki.fhem.de/wiki/DOIF/Automatisierung#Beschattungssteuerung_abh.C3.A4ngig_von_der_Zimmertemperatur_und_Sonneneinstrahlung_f.C3.BCr_mehrere_Szenarien_mit_Visualisierung
kann man sehen, dass die Steuerung und Web-Frontend in einem Modul keine schlechte Idee sein muss.

DOIF ist inzwischen mehr als nur eine Alternative zu notify oder at. Bevor man ein Modul für etwas entwickelt, kann man überlegen, ob evtl. eine DOIF-Definition mit Web-Frontend schneller zu einer zufriedenstellenden Lösung für eine Aufgabe führt. Insb. im Perlmodus kann man sich nach Belieben austoben.
Programmierte FHEM-Module: DOIF-FHEM, DOIF-Perl, DOIF-uiTable, THRESHOLD, FHEM-Befehl: IF

Damian

#9
Und zu:

ZitatSinnvoll wäre, ein eigenes Modul zu erstellen, was ich überall einsetzen kann - oder einen Helper welcher von jeden Device genutzt werden kann.

Du kannst, bis auf die SVG-Funktion card, alle SVG-uiTable-Funktionen unmittelbar im devStateIcon eines beliebigen Devices nutzen - da sie nur HTML-Code generieren.

Z. B.

defmod Aussensensor CUL_WS 1
attr Aussensensor devStateIcon {ui_Table::temp_hum_ring(ReadingsVal($name,"temperature",0),ReadingsVal($name,"humidity",0))}


Programmierte FHEM-Module: DOIF-FHEM, DOIF-Perl, DOIF-uiTable, THRESHOLD, FHEM-Befehl: IF

Benni

Zitat von: Damian am 16 Januar 2022, 19:39:17
Du kannst, bis auf die SVG-Funktion card, alle SVG-uiTable-Funktionen unmittelbar im devStateIcon eines beliebigen Devices nutzen - da sie nur HTML-Code generieren.

Z. B.

defmod Aussensensor CUL_WS 1
attr Aussensensor devStateIcon {ui_Table::temp_hum_ring(ReadingsVal($name,"temperature",0),ReadingsVal($name,"humidity",0))}


Aber auch nur, wenn man auch irgendwo ein DOIF hat ;)


Undefined subroutine &ui_Table::temp_hum_ring called at (eval 41651044) line 1.


gb#

Damian

Zitat von: Benni am 16 Januar 2022, 22:10:58
Aber auch nur, wenn man auch irgendwo ein DOIF hat ;)


Undefined subroutine &ui_Table::temp_hum_ring called at (eval 41651044) line 1.


gb#

ja, das Modul muss einmal geladen sein, ein

defmod di DOIF

sollte dann schon reichen.
Programmierte FHEM-Module: DOIF-FHEM, DOIF-Perl, DOIF-uiTable, THRESHOLD, FHEM-Befehl: IF

Beta-User

Könntest du bei Gelegenheit bitte den Anker aus #7620 rausnehmen? Der zerstört nämlich den vermutlich eigentlich erwünschten Link zu dummy (auch in anderen Modulen)...
<a name="setList"></a>

Generell wünschenswert wäre, bei der Überarbeitung der commandref gleich auf die "id"-Verankerung umzustellen, dann passiert sowas nicht mehr ganz so einfach (das betrifft dann aber auch dummy).
Server: HP-elitedesk@Debian 12, aktuelles FHEM@ConfigDB | CUL_HM (VCCU) | MQTT2: MiLight@ESP-GW, BT@OpenMQTTGw | MySensors: seriell, v.a. 2.3.1@RS485 | ZWave | ZigBee@deCONZ | SIGNALduino | MapleCUN | RHASSPY
svn: u.a MySensors, Weekday-&RandomTimer, Twilight,  div. attrTemplate-files

rudolfkoenig

Zitat[...] (das betrifft dann aber auch dummy).
Habe dummy von <a name=""> auf <a id=""> umgebaut.

Beta-User

Zitat von: rudolfkoenig am 01 Februar 2022, 11:44:59
Habe dummy von <a name=""> auf <a id=""> umgebaut.
Danke!
(Du warst etwas schnell, sonst hättest du einen patch bekommen :) ).
Server: HP-elitedesk@Debian 12, aktuelles FHEM@ConfigDB | CUL_HM (VCCU) | MQTT2: MiLight@ESP-GW, BT@OpenMQTTGw | MySensors: seriell, v.a. 2.3.1@RS485 | ZWave | ZigBee@deCONZ | SIGNALduino | MapleCUN | RHASSPY
svn: u.a MySensors, Weekday-&RandomTimer, Twilight,  div. attrTemplate-files