Commandref aufteilen?

[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

[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.

[krikan]

Die modular Variante

Code Auswählen Erweitern

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.

[PatrickR]

Guten Abend!

Die modular Variante

Code Auswählen Erweitern

attr global commandref modular
ist bekannt und hilft nicht?

War nicht bekannt und hilft ein Stück weit.

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

[betateilchen]

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.

[rudolfkoenig]

Gibt 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]

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.

[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*

[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]

- ein Programm bauen, was aus allen Modulen die Hilfe (je Sprache) in ein Verzeichnis extrahiert.

Genau das meinte ich mit "Konzept ändern" 

Wenn ich mich um diesen Teil kümmere - übernimmst Du dann den JavaScript part?

[rudolfkoenig]

Ja, gerne.

[betateilchen]

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

Code Auswählen Erweitern



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

und darin jeweils nach folgendem Muster:

01_FHEMWEB.cref

oder

FHEMWEB.cref



irgendwie so...

[rudolfkoenig]

Keine speziellen Wuensche, dein Vorschlag ist OK.

[betateilchen]

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:

Code Auswählen Erweitern


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

Code Auswählen Erweitern


    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

[nils_]

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:

Code Auswählen Erweitern

<!-- INSERT_DOC_FROM: www/pgm2/fhemweb.*.js -->

weil laut

Code Auswählen Erweitern

$ 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...)

[betateilchen]

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)

[nils_]

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

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 

[betateilchen]

Für den Notizzettel...

Code Auswählen Erweitern


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


[betateilchen]

Was ich noch nicht verstehe, ist die if() Abfrage
...
die ich erstmal auskommentieren musste, damit überhaupt was passiert.

ah... ich habs kapiert

Code Auswählen Erweitern


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


[rudolfkoenig]

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.

[betateilchen]

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.

[betateilchen]

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.

[rudolfkoenig]

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

[betateilchen]

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.

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.

[betateilchen]

In meinem Amazon S3 bucket sieht die Struktur jetzt so aus:

Code Auswählen Erweitern


.
├── 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.

[nils_]

kurze frage:
gibt es keine sprachumschaltung mehr DE <-> EN ??

[betateilchen]

Deshalb hatte Rudi oben ZWEI Links gepostet. Einen für englisch, einen für deutsch.

[nils_]

die hab ich schon gesehen, und mir ist auch klar wofür der jeweilige link ist 

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!)

[rudolfkoenig]

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

[betateilchen]

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