FHEM Forum

FHEM - Entwicklung => FHEM Development => Thema gestartet von: PatrickR am 21 Mai 2018, 15:49:52

Titel: Commandref aufteilen?
Beitrag von: PatrickR am 21 Mai 2018, 15:49:52
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
Titel: Antw:Commandref aufteilen?
Beitrag von: Amenophis86 am 21 Mai 2018, 17:36:11
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.
Titel: Antw:Commandref aufteilen?
Beitrag von: krikan am 21 Mai 2018, 17:46:52
Die modular Variante
attr global commandref modular
ist bekannt und hilft nicht?

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

Gruß, Christian
Titel: Antw:Commandref aufteilen?
Beitrag 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.
Titel: Antw:Commandref aufteilen?
Beitrag von: PatrickR am 21 Mai 2018, 21:40:51
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
Titel: Antw:Commandref aufteilen?
Beitrag von: betateilchen am 22 Mai 2018, 17:25:52
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.
Titel: Antw:Commandref aufteilen?
Beitrag von: rudolfkoenig am 22 Mai 2018, 19:32:22
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 :)
Titel: Antw:Commandref aufteilen?
Beitrag von: betateilchen am 23 Mai 2018, 02:21:37
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.
Titel: Antw:Commandref aufteilen?
Beitrag von: betateilchen am 23 Mai 2018, 09:08:46
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*
Titel: Antw:Commandref aufteilen?
Beitrag von: rudolfkoenig am 23 Mai 2018, 10:46:10
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.
Titel: Antw:Commandref aufteilen?
Beitrag von: betateilchen am 23 Mai 2018, 11:21:25
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?
Titel: Antw:Commandref aufteilen?
Beitrag von: rudolfkoenig am 23 Mai 2018, 11:27:30
Ja, gerne.
Titel: Antw:Commandref aufteilen?
Beitrag von: betateilchen am 23 Mai 2018, 11:35:20
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...
Titel: Antw:Commandref aufteilen?
Beitrag von: rudolfkoenig am 23 Mai 2018, 11:39:19
Keine speziellen Wuensche, dein Vorschlag ist OK.
Titel: Antw:Commandref aufteilen?
Beitrag von: betateilchen am 24 Mai 2018, 21:46:47
Hallo Rudi,


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 :)
Titel: Antw:Commandref aufteilen?
Beitrag von: nils_ am 25 Mai 2018, 09:01:24
Zitat von: betateilchen am 24 Mai 2018, 21:46:47
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.

liegt das evtl. an der Zeile:
<!-- INSERT_DOC_FROM: www/pgm2/fhemweb.*.js -->

weil laut
$ grep -rn INSERT_DOC_ *
01_FHEMWEB.pm:3974:        <!-- INSERT_DOC_FROM: www/pgm2/fhemweb.*.js -->
01_FHEMWEB.pm:4679:        <!-- INSERT_DOC_FROM: www/pgm2/fhemweb.*.js -->
98_help.pm:187:        if($l =~ m,INSERT_DOC_FROM: ([^ ]+)/([^ /]+) ,) {


ist das nur dort vorhanden (wenn ich das richtig genutzt habe...)
Titel: Antw:Commandref aufteilen?
Beitrag von: betateilchen am 25 Mai 2018, 10:10:08
ja, an der Stelle war ich gestern auch schon, aber irgendwann war die Bahnfahrt dann so nervig, dass ich keine Lust mehr hatte, weiter am Laptop zu arbeiten :)

Inzwischen ist das Thema FHEMWEB in commandref_static auch gelöst. Es war nicht wirklich ein Problem, es wurde durch den rekursiven Aufruf nur eine eingebaute Debug-Meldung mehrfach ausgegeben, was zu meiner Verwirrung beitrug.

Die Sache mit dem Einfügen von Inhalten aus anderen Dateien muss ich noch implementieren. (erledigt)
Titel: Antw:Commandref aufteilen?
Beitrag von: nils_ am 25 Mai 2018, 12:19:54
Zitat von: betateilchen am 25 Mai 2018, 10:10:08
ja, an der Stelle war ich gestern auch schon, aber irgendwann war die Bahnfahrt dann so nervig, dass ich keine Lust mehr hatte, weiter am Laptop zu arbeiten :)
kann ich verstehen.
ich gucke dann auch lieber aus dem fenster ;)

Zitat von: betateilchen am 25 Mai 2018, 10:10:08
Inzwischen ist das Thema FHEMWEB in commandref_static auch gelöst. Es war nicht wirklich ein Problem, es wurde durch den rekursiven Aufruf nur eine eingebaute Debug-Meldung mehrfach ausgegeben, was zu meiner Verwirrung beitrug.
ah ok. ich dachte es gab nen fehler oder sowas... debug-meldungen sind ja erstmal nicht so schlimm  ::) 8)
Titel: Antw:Commandref aufteilen?
Beitrag von: betateilchen am 25 Mai 2018, 21:15:15
Für den Notizzettel...


cref
├── docs
│   ├── commandref_DE.html -> /opt/fhem/docs/commandref_DE.html
│   ├── commandref.html -> /opt/fhem/docs/commandref.html
│   ├── cref -> /opt/fhem/docs/cref
│   ├── cref_DE -> /opt/fhem/docs/cref_DE/
│   └── fhemdoc.js -> /opt/fhem/docs/fhemdoc.js
├── fhem
│   └── icons
│       └── favicon.ico -> /opt/fhem/www/images/default/favicon.ico
├── index.html
├── pgm2
│   ├── fhemdoc_static.js -> /opt/fhem/www/pgm2/fhemdoc_static.js
│   └── jquery.min.js -> /opt/fhem/www/pgm2/jquery.min.js
├── robots.txt
└── www
    ├── images
    │   └── default
    │       └── fhemicon.png -> /opt/fhem/www/images/default/fhemicon.png
    └── pgm2
        ├── dashboard_style.css -> /opt/fhem/www/pgm2/dashboard_style.css
        ├── defaultCommon.css -> /opt/fhem/www/pgm2/defaultCommon.css
        └── style.css -> /opt/fhem/www/pgm2/style.css

10 directories, 12 files
Titel: Antw:Commandref aufteilen?
Beitrag von: betateilchen am 26 Mai 2018, 11:10:33
Zitat von: betateilchen am 24 Mai 2018, 21:46:47
Was ich noch nicht verstehe, ist die if() Abfrage
...
die ich erstmal auskommentieren musste, damit überhaupt was passiert.

ah... ich habs kapiert :)


cat mkstatic.log

Updating '.':
At revision 16779.
upload: docs/commandref.html to s3://commandref.j65.de/docs/commandref.html
upload: docs/commandref_DE.html to s3://commandref.j65.de/docs/commandref_DE.html
                                                                         
Updating '.':
U    FHEM/34_ESPEasy.pm
Updated to revision 16780.
upload: docs/commandref.html to s3://commandref.j65.de/docs/commandref.html
upload: docs/commandref_DE.html to s3://commandref.j65.de/docs/commandref_DE.html
upload: docs/cref/ESPEasy.cref to s3://commandref.j65.de/docs/cref/ESPEasy.cref
                                                                         
Updating '.':
At revision 16780.
upload: docs/commandref_DE.html to s3://commandref.j65.de/docs/commandref_DE.html
upload: docs/commandref.html to s3://commandref.j65.de/docs/commandref.html

Titel: Antw:Commandref aufteilen?
Beitrag von: rudolfkoenig am 27 Mai 2018, 13:22:37
Danke fuer die Vorarbeit.
Ich habe fhemdoc_modular.js angepast, damit es auch mit der statischen Variante zurechtkommt, und habe fhemdoc_static.js entfernt. und commandref_static.pl angepasst, damit fhemdoc_modular.js statt fhemdoc_static.js geladen wird. Ich habe alles ausgerollt auf fhem.de, damit steht
http://fhem.de/commandref_modular.html
bzw.
http://fhem.de/commandref_modular_DE.html
zur Verfuegung.

Wenn es keine groeberen Probleme zeigt, dann werde ich die beiden auch auf fhem.de direkt verlinken.

Titel: Antw:Commandref aufteilen?
Beitrag von: betateilchen am 27 Mai 2018, 17:09:26
Prima.

Parallel werde ich das in meinem Serverumfeld weiter beobachten, mir sind da noch Kleinigkeiten aufgefallen, die ich irgendwann noch beheben möchte, die aber nichts mit der Funktionalität selbst zu tun haben.

Noch ein Hinweis:

Von Zeit zu Zeit (z.B. einmal pro Jahr) sollte man die .pl Datei mit dem Parameter "rebuild" aufrufen. Das sorgt dafür, dass zuerst alle .cref Dateien entfernt und danach alle Texte neu generiert werden. Warum? Weil sonst die .cref Dateien zu Modulen, die nicht mehr im ./FHEM Zweig stehen, nicht entfernt werden. Das Entfernen eines Moduls bekommt nämlich commandref_static.pl nicht ohne weiteres mit.
Titel: Antw:Commandref aufteilen?
Beitrag von: betateilchen am 27 Mai 2018, 17:51:16
Warum funktioniert das auf meinem Server http://commandref.j65.de nicht? *grübel*

es wird die korrekte html-Datei (commandref_modular.html) aufgerufen,
es wird die korrekte fhemdoc_modular.js geladen

Trotzdem sieht man in der js-console, dass nach wie vor versucht wird, einen help Befehl auszuführen, anstatt die cref Datei zu laden.
Titel: Antw:Commandref aufteilen?
Beitrag von: rudolfkoenig am 27 Mai 2018, 20:37:44
Weil fd_mode nur dann auf "static" geschaltet wird, falls der host fhem.de oder commandref.fhem.de ist.
Du koenntest auf deinem Rechner fd_mode in der 6-ten Zeile der Datei fhemdoc_modular.js mit "static" initialisieren.

Weiterhin braucht man fuer die Installation auf dem eigenen Rechner
- die commandref_modular*.html und fhemdoc.js,  in einem Ordner
- jquery.min.js und fhemdoc_modular.js in einem pgm2 Unterordner
- style.cs in www/pgm2

Hmmm. Ziemlicher Chaos, ich muesste da mal aufraeumen :)
Titel: Antw:Commandref aufteilen?
Beitrag von: betateilchen am 27 Mai 2018, 22:01:41
Zitat von: rudolfkoenig am 27 Mai 2018, 20:37:44
Du koenntest auf deinem Rechner fd_mode in der 6-ten Zeile der Datei fhemdoc_modular.js mit "static" initialisieren.

danke, das ändert auf jeden Fall mal das Verhalten dahin, dass tatsächlich versucht wird, eine Datei zu laden.

Zitat von: rudolfkoenig am 27 Mai 2018, 20:37:44
Weiterhin braucht man fuer die Installation auf dem eigenen Rechner
...
Hmmm. Ziemlicher Chaos, ich muesste da mal aufraeumen :)

Man braucht noch mehr Dateien, als in Deiner Liste genannt sind. Die ziemlich verquere Verzeichnisstruktur habe ich weiter oben schon dokumentiert.

In diesem Beitrag https://forum.fhem.de/index.php/topic,87975.msg805513.html#msg805513

sind alle Dateien aufgeführt, die ich bereitstellen musste, um den Aufruf der statischen commandref aus meinem bucket ohne Fehler auf der Konsole ausführen zu können.
Titel: Antw:Commandref aufteilen?
Beitrag von: betateilchen am 27 Mai 2018, 22:06:05
In meinem Amazon S3 bucket sieht die Struktur jetzt so aus:


.
├── cref -> /opt/fhem/docs/cref
├── cref_DE -> /opt/fhem/docs/cref_DE/
├── docs
│   ├── commandref_modular_DE.html -> /opt/fhem/docs/commandref_modular_DE.html
│   ├── commandref_modular.html -> /opt/fhem/docs/commandref_modular.html
│   └── fhemdoc.js -> /opt/fhem/docs/fhemdoc.js
├── fhem
│   └── icons
│       └── favicon.ico -> /opt/fhem/www/images/default/favicon.ico
├── index.html
├── pgm2
│   ├── fhemdoc_modular.js
│   └── jquery.min.js -> /opt/fhem/www/pgm2/jquery.min.js
├── robots.txt
└── www
    ├── images
    │   └── default
    │       └── fhemicon.png -> /opt/fhem/www/images/default/fhemicon.png
    └── pgm2
        ├── dashboard_style.css -> /opt/fhem/www/pgm2/dashboard_style.css
        ├── defaultCommon.css -> /opt/fhem/www/pgm2/defaultCommon.css
        └── style.css -> /opt/fhem/www/pgm2/style.css

10 directories, 12 files


Dass die cref.* Verzeichnisse eine Stufe höher angesiedelt sind, hat technische Gründe. Aber mit dieser Struktur funktioniert nun auch die statisch-modulare commandref bei mir.
Titel: Antw:Commandref aufteilen?
Beitrag von: nils_ am 28 Mai 2018, 08:51:38
kurze frage:
gibt es keine sprachumschaltung mehr DE <-> EN ??
Titel: Antw:Commandref aufteilen?
Beitrag von: betateilchen am 28 Mai 2018, 08:54:13
Deshalb hatte Rudi oben ZWEI Links gepostet. Einen für englisch, einen für deutsch.
Titel: Antw:Commandref aufteilen?
Beitrag von: nils_ am 28 Mai 2018, 09:00:37
die hab ich schon gesehen, und mir ist auch klar wofür der jeweilige link ist  8)

aber es gibt nun keine mehr in der commandref.
und auch selbst eingefügte von den Modulentwicklern führen jetzt vmtl. ins leere. (selbst erstellte sollten dann wohl am besten über kurz oder lang verschwinden!)
Titel: Antw:Commandref aufteilen?
Beitrag von: rudolfkoenig am 28 Mai 2018, 10:11:46
Immerhin kann man (hoechst komfortabel :) ) die gerade sichtbare Moduldokumentation in der anderen Sprache anzeigen lassen.
Und: das ist nix Neues, ist mit "attr global commandref modular" schon seit einem Jahr da, nur halt nicht auf fhem.de
Titel: Antw:Commandref aufteilen?
Beitrag von: betateilchen am 28 Mai 2018, 11:16:50
Zitat von: rudolfkoenig am 28 Mai 2018, 10:11:46
Immerhin kann man (hoechst komfortabel :) ) die gerade sichtbare Moduldokumentation in der anderen Sprache anzeigen lassen.

zu ergänzen: ... sofern es eine Doku in einer anderen Sprache gibt. Ansonsten sieht man den Link zum Umschalten nicht, was durchaus sinnvoll ist :)