Modulare Commandref

[Dr. Boris Neubert]

Hallo,

wegen der vorgesehenen neuen Grundeinstellung, dass die Commandref modular ist, habe ich mir diese nochmal angesehen.

Eine modulare Hilfe ist besser als diese riesige monolithische Hilfe.

Meiner Meinung nach gibt es aber noch Verbesserungsbedarf:
- Beim Einblenden der Hilfe zu einem Modul bleiben die statischen Inhalte der Webseite erhalten. Mich irritiert das. Ich fände es besser, wenn auch die allgemeinen Abschnitte, die als statische Links voran- und hintenangestellt sind, modularisiert würden.
- Bei Auswahl von Weather erscheint noch ein Hinweis "Module: 46_TRX_WEATHER.pm Maintainer: KernSani Forum: RFXTRX" darüber. Das ist nicht gewollt.
- Unterhalb von der Überschrift "Device modules" steht ein einsames "global".
- Ceterum censeo... Helper modules gehört abgeschafft. Oder es überzeuge mich jemand, dass ein Anwender weiß, ob er in Device modules oder Helper modules nach einem Gerät suchen muss.

Grüße
Boris

[Beta-User]

Anderere Aktionspunkte, von denen ich nicht weiß, wie viele Module sowas - ggf. mit unterschiedlichem Schwerpunkt - betrifft:
- Wenn man Shelly in der modularen Variante anklickt, kommt man auf den  Hinweis, dass "Absichtlich keine deutsche Variante existiert." MAn. ist ein solcher Hinweis überflüssig, ich kann zwar verstehen, dass man die Rückfrage leid ist, ob es Absicht sei, würde mir aber trotzdem wünschen, dass man  gleich auf der betreffenden englischen Seite landet;

- Das "klicken", um auf die englische Variante zu kommen klappt aber in dem Fall auch nicht (genausowenig übrigens wie bei "help", wo man allerdings woanders landet als in einer loop)...
Der Link ist in dieser Form hinterlegt:

Code Auswählen Erweitern

<a href="commandref.html#Shelly">Shelly</a>
Stressfrei wäre wohl

Code Auswählen Erweitern

<a href="#Shelly">Shelly</a>



Betrifft zwar nicht speziell Modular, aber wer sowieso eine Umstellung auf "id" machen möchte, könnte das gleich auch noch gegenchecken; wer dazu Fragen hat, findet hoffentlich ausreichend Material in https://forum.fhem.de/index.php/topic,120779.msg1166266.html#msg1166266 bzw. dem ganzen Thread.

PS an "den einen" hier mitlesenden User: Diese Umstellung auf "id" ist nicht wirklich schwer und eher eine Fleißaufgabe. Vielleicht bietest du einem Maintainer deiner Wahl an, ein oder zwei seiner Module entsprechend durchzusehen und lieferst einen "patch" (auf jedem linux-System per diff -u zu erstellen) (oder einfach die komplette commandref) .

[rudolfkoenig]

Ich fände es besser, wenn auch die allgemeinen Abschnitte, die als statische Links voran- und hintenangestellt sind, modularisiert würden.

Ich faende es auch besser, ein Umbau ist aber gar nicht so einfach.

- Bei Auswahl von Weather erscheint noch ein Hinweis "Module: 46_TRX_WEATHER.pm Maintainer: KernSani Forum: RFXTRX" darüber. Das ist nicht gewollt.

Scheinbar doch: "help WEATHER" liefert das zurueck. Bestellt habe ich es zwar nicht, schlecht finde ich es trotzdem nicht.

- Unterhalb von der Überschrift "Device modules" steht ein einsames "global".

Stimmt, weiss aber nicht, wo es besser hinpassen wuerde.

Helper modules gehört abgeschafft.

Ich wollte mehrere Abschnitte bauen, und habe mit helper, command, device angefangen. Haenge nicht wirklich dran, wenn Mehrere sich fuer eine Abschaffung aussprechen.

würde mir aber trotzdem wünschen, dass man  gleich auf der betreffenden englischen Seite landet;

Das passiert automatisch, wenn man keine deutsche Doku einbaut.
Und bei mir funktioniert "Englische Doku für Shelly laden" ohne Probleme, auch fuer help.

[Beta-User]

Hauptsystem ist einigermaßen aktuell, version meldet für 98_help.pm: 24900, global steht auf language DE.

Help shelly liefert den Hinweis, dass keine deutsche Dokumentation existieren würde, was nicht ganz richtig ist, denn dieser Hinweis IST die commandref-de, deine (zutreffende) Bemerkung paßt daher eben auf dieses Variante nicht...

Das passiert automatisch, wenn man keine deutsche Doku einbaut.

Jedenfalls taucht bei help shelly ein Link auf, der dahin verweist:

Code Auswählen Erweitern

http://<server>:8083/commandref.html#Shelly
Klicke ich darauf, lande ich auf der Seite, die ich via defaultRoom als Startseite für FHEMWEB definiert habe...
Kann natürlich sein, dass das System an irgendeiner Stelle verbogen ist oder der Browser (ff) da was falsch versteht .

Und bei mir funktioniert "Englische Doku für Shelly laden" ohne Probleme, auch fuer help.

Wenn man die englische Seite direkt ansteuert (help shelly EN) ist das kein Problem.

Beim Klick auf commandref im Menü und anschließender Auswahl von Shelly aus der Modulliste lande ich auf

Code Auswählen Erweitern

http://<server>:8083/fhem/docs/commandref_DE.html#Shelly
Das ist wieder die Hinweisseite, dass es keine de-Doku gibt, und der angeboten Link ist wieder der mit dem _DE-Zusatz....

Falls das irgendeinen Unterschied macht: global-Doku steht bei mir schon ewig auf modular.

Nachtrag: Evtl. sollte man die mit dem Hinweis "Keine deutsche Hilfe gefunden!" (der z.B. kommt, wenn man help WeekdayTimer aufruft, der in der Tat (absichtlich! & wirklich) keine hat) möglicherweise verbundene Erwartungshaltung, es müsse eine geben irgendwie anders formulieren. Mir fällt dazu auf die Schnelle aber auch nichts sinnstiftendes ein...

Ad Vor- und Nachspann etc.:
- Ich fände ein Vorziehen von "global" überlegenswert;
- Wer nur den Text zum Modul haben will, kann "help" aufrufen;
- Grade für Anfänger finde ich es nicht unbedingt optimal, wenn die allgemeine Einbettung verloren ginge;
- evtl. wäre eine Voreinstellung denkbar, dass man das Laden des Rahmens unterbinden kann?

Bzgl. helper etc meine 2ct: Die Unterscheidung ist schon irgendwie - na ja - .... Aber alles in einem Wust ist auch nur bedingt hilfreich. Commands getrennt ist m.E. in jedem Fall weiter sinnvoll. Vielleicht könnte man die Bitte, alle Module im Hinblick auf commandref nochmal anzusehen erweitern dahingehend, dass die Verschlagwortung für den Installer möglichst nachgezogen wird. (Ich habe das zwar bei meinen Modulen vor längerem gemacht, aber auch nicht die vertiefte Idee, was damit genau passieren soll).

[Dr. Boris Neubert]

Scheinbar doch: "help WEATHER" liefert das zurueck. Bestellt habe ich es zwar nicht, schlecht finde ich es trotzdem nicht.

Nee, das scheint ein Bug in 98_help.pm zu sein:

Code Auswählen Erweitern

  my ($err,@text) = FileRead({FileName => "$modPath/MAINTAINER.txt", ForceType => 'file'});
  foreach my $l (@text) {
    @line = split("[ \t][ \t]*", $l,3);
    $found = ($l =~ m/.._$mod.pm/i);
#    $found = ($l =~ m/_$mod/i);
    last if ($found);
  }

Das Module ist 59_Weather.pm und der Match findet 46_TRX_WEATHER.pm. Folgende Änderung in Zeile 268 löst das Problem:

Code Auswählen Erweitern

    $found = ($l =~ m/\d\d_$mod.pm/i);

Udo, liest Du mit?

Viele Grüße
Boris

[Beta-User]

Nachtrag: Evtl. sollte man die mit dem Hinweis "Keine deutsche Hilfe gefunden!" (der z.B. kommt, wenn man help WeekdayTimer aufruft, der in der Tat (absichtlich! & wirklich) keine hat) möglicherweise verbundene Erwartungshaltung, es müsse eine geben irgendwie anders formulieren. Mir fällt dazu auf die Schnelle aber auch nichts sinnstiftendes ein...

Vielleicht ein paar Gedanken dazu (falls es hier zu OT ist, können wir das gerne abtrennen):

Es gibt einige Module, die hinsichtlich der Doku zweigleisig fahren - englische Commandref, deutsche Doku via Wiki. Im Prinzip ist das ja ok, nur dass die Wiki-Doku halt nicht offline verfügbar ist und nicht unter der vollen Kontrolle des Maintainers steht.
Von Wiki steht aber aaO. nichts (in dem konkreten Fall ist es auch noch eine Baustelle).
Eventuell wäre es möglich, den Help-Text zu modifizieren, entweder, indem man ein entsprechendes "flag" setzt

Code Auswählen Erweitern

=item wiki_DE Modul_Shelly
das dann v.a. help verstehen müßte und in einen entsprechenden Text+Link ins Wiki umsetzen könnte (unabhängig davon, wie man allgemein zum Thema Wiki steht), oder indem man die DE-Commandref eben auf "ein Wort" beschränkt (was dann help und commandref_.*.pl verstehen müßten, dass damit gerade keine DE-commandref geliefert wird, sondern es sich um einen Link ins Wiki handelt).

Wollte das nur mal in den Raum werfen, gibt sicher bessere Ideen.

[rudolfkoenig]

Ich bin fuer ein Link im englischen Doku aufs Wiki, ob vorne oder hinten ist mir egal aber sinnvollerweise gleich.
Das kann man selbst fuer "vollstaendige" Dokus machen, nach dem Motto: mehr Details/Beispiele/etc gibts <hier>.

[Beta-User]

Ich bin fuer ein Link im englischen Doku aufs Wiki, ob vorne oder hinten ist mir egal aber sinnvollerweise gleich.
Das kann man selbst fuer "vollstaendige" Dokus machen, nach dem Motto: mehr Details/Beispiele/etc gibts <hier>.

Finde ich einen guten Vorschlag.

Es fragt sich nur, warum sich einige Varianten von dem finden was ich als "der Maintainer mag den Standardtext nicht" interpretieren würde, wenn man über die Commandref_join drüberfliegt. Weiteres Beispiel:

Eine deutsche Beschreibung ist aktuell nur im WIKI verfügbar.
Wiki MediaList

Oder (auch als Diskussionsbasis):

Deutsche Dokumentation im Wiki vorhanden, die englische Version gibt es hier: OWX

Wobei die Deutsche Dokumentation vermutlich nicht direkt eine Übersetzung der englischen Version ist. Vielleicht wäre sowas in der Art hier eine Option:

In deutsch ist eine Dokumentation im Wiki verfügbar. Englische commandref: OWX

Zu den Testbedingungen noch:
Interessanterweise funktionieren die Links (einschließlich Shelly) auf meinem Testsystem (im Unterschied zum Hauptsystem) aus der commandref heraus, aber (soweit erkennbar nur) Shelly weigert sich auch auf diesem System hartnäckig, aus help heraus die commandref zu öffnen)

[betateilchen]

Udo, liest Du mit?

jetzt ja, ich war ein paar Tage in Urlaub...

Nee, das scheint ein Bug in 98_help.pm zu sein:

Das ist kein wirklicher Bug, das ist ein Problem von fehlenden Konventionen zur Namensgebung von Moduldateien.

Das Module ist 59_Weather.pm und der Match findet 46_TRX_WEATHER.pm. Folgende Änderung in Zeile 268 löst das Problem:

Jede Änderung der regexp an dieser Stelle löst ein bestimmtes akutes Problem (zu dessen Lösung eine Änderung vorgeschlagen wurde) und schafft gleichzeitig 2-3 neue Probleme an anderer Stelle. Eine wirklich sinnvolle Lösung habe ich dafür noch nicht gefunden, obwohl die Stelle schon mehrfach angepasst wurde.

Deine vorgeschlagene Änderung werde ich mal einbauen, dann hole ich mir eine Tüte Popcorn und warte, bis sich der Nächste meldet, der dann ein Problem mit der Namensauflösung hat.