Commandref aufteilen?

Begonnen von PatrickR, 21 Mai 2018, 15:49:52

Vorheriges Thema - Nächstes Thema

PatrickR

Hallo zusammen!

Auf die Gefahr hin, mich in die Nesseln zu setzen, wollte ich mal die Frage in den Raum stellen, ob die Commandref in mehrere Dateien aufgeteteilt werden sollte. Um das Volumen mal plastisch darzustellen: Allein die Dokumentation von DOIF/DOIFTools hat einen Umfang von knapp 30 Seiten A4, die Kurzdokumentation von DOIF 7 Seiten.

Das führt bei mir aktuell verstärkt zu Problemen:
-Unter iOS mit iCabMobile crasht der Browser nach weniger als einer Sekunde
-Chrome unter macOS mit aktivierter Evernote-Web-Clipper-Extension hängt sich beim Laden vollständig auf bis der Browser dann nach ewiger Zeit das Schließen des Tabs anbietet.

Nun kann man natürlich argumentieren, dass das ein guter Anlass ist, seine Browserwahl/-konfiguration zu überdenken, aber angesichts der Tatsache, dass die Commandref sicherlich noch weiter wachsen wird, ist es aus meiner Sicht sinnvoll, über eine Aufteilung zu diskutieren. Meines Erachtens hätte das - gehen wir von einer Unterseite pro Modul aus - auch positive Nebeneffekte wie die einfache Druckbarkeit der Dokumentation von Einzelmodulen.

Patrick
lepresenced - Tracking von Bluetooth-LE-Tags (Gigaset G-Tag) mittels PRESENCE

"Programming today is a race between software engineers striving to build bigger and better idiot-proof programs, and the universe trying to produce bigger and better idiots. So far, the universe is winning." - Rich Cook

Amenophis86

Ich würde den Vorschlag etwas abändern. Vielen geht es darum mittels Suche in den CommandRef etwas zu finden, daher ist es auf einer Seite. Meine ich zumindest. Um dies weiterhin zu ermöglichen könnte man eine CommandRef mit Unterseiten und eine komplett anbieten. Damit wären beide Parteien bedient. Ich persönlich finde sie inzwischen auch zu lang für eine Seite und habe die gleichen Probleme.
Aktuell dabei unser neues Haus mit KNX am einrichten. Im nächsten Schritt dann KNX mit FHEM verbinden. Allein zwei Dinge sind dabei selten: Zeit und Geld...

krikan

Die modular Variante
attr global commandref modular
ist bekannt und hilft nicht?

Alternativ über
https://fhem.de/commandref.html#help

Gruß, Christian

Amenophis86

Gibt es die modulare auch als Version im Internet? Ich nehme fast immer die der FHEM Homepage, da ich bei mir die CommandRef vom Update ausgenommen habe. Dauert mir zu lange und die auf fhem.de ist schneller und aktueller.
Aktuell dabei unser neues Haus mit KNX am einrichten. Im nächsten Schritt dann KNX mit FHEM verbinden. Allein zwei Dinge sind dabei selten: Zeit und Geld...

PatrickR

Guten Abend!

Zitat von: krikan am 21 Mai 2018, 17:46:52
Die modular Variante
attr global commandref modular
ist bekannt und hilft nicht?
War nicht bekannt und hilft ein Stück weit.

Zitat von: Amenophis86 am 21 Mai 2018, 18:19:11
Gibt es die modulare auch als Version im Internet? Ich nehme fast immer die der FHEM Homepage, da ich bei mir die CommandRef vom Update ausgenommen habe. Dauert mir zu lange und die auf fhem.de ist schneller und aktueller.
Sehe ich (bis auf das "aktueller") genau so. Fhemweb als Doku-Browser zu nutzen ist m. E. nicht die erste Wahl.

Patrick
lepresenced - Tracking von Bluetooth-LE-Tags (Gigaset G-Tag) mittels PRESENCE

"Programming today is a race between software engineers striving to build bigger and better idiot-proof programs, and the universe trying to produce bigger and better idiots. So far, the universe is winning." - Rich Cook

betateilchen

Zitat von: PatrickR am 21 Mai 2018, 21:40:51
Fhemweb als Doku-Browser zu nutzen ist m. E. nicht die erste Wahl.

Aber wenn man schon weiß, zu welchem Modul man überhaupt Informationen sucht, kann man mit "help moduleName" doch schon gezielt die Informationen bekommen und sieht genau den commandref Teil zum gesuchten Modul? Das funktioniert sogar dann, wenn man noch gar kein device dieses Moduls instanziiert hat.

Anstatt moduleName kann man übrigens auch einen deviceName verwenden, daraus wird der TYPE ermittelt und die Information aus dem Modul geladen.
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

rudolfkoenig

ZitatGibt es die modulare auch als Version im Internet?
Nein, es fehlt an einem "abgespeckten" FHEM, was die Daten liefern kann, und auch sicher genug ist.Ist auf meiner TODO-Liste ganz weit unten :)

betateilchen

#7
Zitat von: rudolfkoenig am 22 Mai 2018, 19:32:22
Nein, es fehlt an einem "abgespeckten" FHEM, was die Daten liefern kann, und auch sicher genug ist.

Dazu braucht es gar kein FHEM, ein statischer Amazon S3 bucket reicht eigentlich völlig aus:

http://commandref.j65.de

Und ein S3 bucket ist so ziemlich das sicherste, was man derzeit im Internet finden kann, vorausgesetzt, er ist korrekt konfiguriert.


Aber es funktioniert aufgrund ein paar JavaScript Fehlern noch nicht vollständig (einige commands funktionieren, die Module nicht).
Siehe screenshot.




Übrigens ist die commandref, wenn sie modular generiert wird, nicht vollständig (unabhängig, WO sie liegt). Aber das muss ich zu einem anderen Zeitpunkt weiter erforschen.
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

betateilchen

Man müsste das Konzept von commandref_modular ändern, um eine komplett statische, modulare commandref zu erzeugen, die man ebenso einmal pro Tag aktualisiert wie die komplette commandref.

*grübel*
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

rudolfkoenig

Konzept aendern ist uebertrieben:
- ein Programm bauen, was aus allen Modulen die Hilfe (je Sprache) in ein Verzeichnis extrahiert. Als Ausgangspunkt kann man Code aus help.pm klauen :) Dieses Programm wird nach der update-Bereitstellung morgens aufgerufen.
- fhemdoc_modular.js anpassen, dass in der "statischen" Version diese extrahierten Dateien bestellt, und nicht help in FHEM aufruft.

betateilchen

Zitat von: rudolfkoenig am 23 Mai 2018, 10:46:10
- ein Programm bauen, was aus allen Modulen die Hilfe (je Sprache) in ein Verzeichnis extrahiert.

Genau das meinte ich mit "Konzept ändern"  8)

Wenn ich mich um diesen Teil kümmere - übernimmst Du dann den JavaScript part?
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

rudolfkoenig


betateilchen

Die Extraktion würde ich unterhalb von ./docs/ durchführen.
Irgendwelche Wünsche zur Verzeichnisstruktur oder Benennung der einzelnen Dateien?



./docs
./docs/cref_de
./docs/cref_en

und darin jeweils nach folgendem Muster:

01_FHEMWEB.cref

oder

FHEMWEB.cref



irgendwie so...
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

rudolfkoenig

Keine speziellen Wuensche, dein Vorschlag ist OK.

betateilchen

#14
Hallo Rudi,


  • Analog zu commandref_modular.pl wird es eine Datei commandref_static.pl geben.
  • Diese verwendet ein eigenes js-file "../pgm2/fhemdoc_static.js"
  • Bei der Benennung werde ich mich an die in commandref.* übliche Notation mit $sfx halten.

Die Dokumentation wird sich sprachabhängig so aufteilen:


docs/cref/HMUARTLGW.cref
docs/cref_DE/HMUARTLGW.cref


Eine .cref Datei wird nur geschrieben, wenn für eine Sprache auch ein Text gefunden wird.


Was ich noch nicht verstehe, ist die if() Abfrage


    if($protVersion != $fileVersion ||
       !$modData{$mName} || !$modData{$mName}{ts} || $modData{$mName}{ts}<$ts) {


die ich erstmal auskommentieren musste, damit überhaupt was passiert.

Ausserdem habe ich aktuell noch ein Problem mit der commandref von FHEMWEB - irgendwie wird die Schleife zur Generierung mehrere Male pro Sprache aufgerufen und ich weiß noch nicht genau, warum. Das scheint aber nur in diesem Modul zu passieren. (erledigt)





Die beiden Dateien contrib/commandref_static.pl und fhemdoc_static.js habe ich eingecheckt, und bitte um Deine Begutachtung.

Die js-Datei ist momentan einfach eine 1:1 Kopie der fhemdoc_modular.js und müsste dann wohl von Dir weiter bearbeitet werden :)
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!