[Vorschlag] 98_help.pm zur Anzeige modulspezifischer Doku

Begonnen von betateilchen, 16 Februar 2015, 18:44:11

Vorheriges Thema - Nächstes Thema

justme1968

@rudi: mit der folgenden änderung in fhemweb.js werden die links in der html doku ersetzt:--- fhemweb.js (revision 8036)
+++ fhemweb.js (working copy)
@@ -149,14 +149,28 @@
         $("#devSpecHelp").remove();
         return;
       }
+
       $("#content").append('<div id="devSpecHelp"></div>');
-      FW_cmd(FW_root+"?cmd=help "+dev+"&XHR=1", function(data) {
-        $("#devSpecHelp").html(data);
-      });
+
+      function
+      setContent(dev) {
+        FW_cmd(FW_root+"?cmd=help "+dev+"&XHR=1", function(data) {
+          $("#devSpecHelp").html(data);
+          $(window).scrollTop($("#devSpecHelp").offset().top-200);
+
+          $("#devSpecHelp").find("a[href]").each(function(){
+            var dev = $(this).attr("href").split("#").pop();
+            $(this).attr("href", "#");
+            $(this).click(function(evt){
+              setContent(dev);
+            });
+          });
+        });
+      }
+
+      setContent(dev);
     });
   });
falls es links auf externe seiten gibt muss man die vermutlich anders behandeln.

schau dir mal an ob du das scrollTop magst. ohne hatte ich das problem das der seite nicht wirklich anzusehen ist das unten plötzlich doku steht.


ich glaube du hast die fhemweb änderungen vergessen damit das ersetzen auf js seite auch funktioniert:--- 01_FHEMWEB.pm (revision 8037)
+++ 01_FHEMWEB.pm (working copy)
@@ -1093,7 +1093,7 @@

   FW_pH "cmd=style iconFor $d", "Select icon";
   FW_pH "cmd=style showDSI $d", "Extend devStateIcon";
-  FW_pH "$FW_ME/docs/commandref.html#${t}", "Device specific help";
+  FW_pO "<div class='devSpecHelp'><a href=\"$FW_ME/docs/commandref.html#${t}\">Device specific help</a></div>";
   FW_pH "cmd=delete $d", "Delete this device ($d)" if($d ne "global");
   FW_pO "<br><br>";
   FW_pO "</div>";



wie wäre jeweils es oben in die doku einen passenden link auf die jeweils andere sprache zu generieren? das umschalten würde dann automatisch über die per ersetzten links gehen.
hue, tradfri, alexa-fhem, homebridge-fhem, LightScene, readingsGroup, ...

https://github.com/sponsors/justme-1968

rudolfkoenig

Zitatmit der folgenden änderung in fhemweb.js werden die links in der html doku ersetzt:
Funktioniert nur fuer die Modul-Links (fuer die anderen kommt eine doofe Fehlermeldung), und das auch nur im devSpecHelp, nicht wenn man "help modul" direkt aufruft. Ich praeferiere eine Ersetzung aller relativen Links (d.h. href="#..." ) durch href="commandref.html#...", durchgefuehrt vom help Modul.

Zitatich glaube du hast die fhemweb änderungen vergessen damit das ersetzen auf js seite auch funktioniert:
Stimmt, habs jetzt eingecheckt.

Zitatwie wäre jeweils es oben in die doku einen passenden link auf die jeweils andere sprache zu generieren?
Gerne, aber dazu muesste fhemweb.js wissen, was die aktuelle Sprache ist.
FHEMWEB.pm koennte "global language" auf der Seite hinterlegen, allerdings muesste help dieses Attribut auch unterstuetzen.

justme1968

die anderen links gehen nicht weil help devspec und ähnliche nicht gehen. absolute links würden hier tatsächlich helfen.

hast du dir das mit dem scrollTop noch mal angeschaut? es ist sehr viel schöner wenn man nach dem ausklappen direkt die hilfe sieht und nicht noch mal nach unten scrollen muss.

apropos links: im darkstyle sind die ganzen links nicht zu erkennen. zumindest im neuen devSpecHelp div könnte man sie jetzt per css sichtbar machen.


wenn das help modul die sprach links einbaut müsste mal language noch nicht mal durch reichen.
hue, tradfri, alexa-fhem, homebridge-fhem, LightScene, readingsGroup, ...

https://github.com/sponsors/justme-1968

betateilchen

Zitat von: rudolfkoenig am 19 Februar 2015, 09:23:28
allerdings muesste help dieses Attribut auch unterstuetzen.

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

betateilchen

#19
Zitat von: justme1968 am 18 Februar 2015, 22:55:23
vermutlich noch niemand. das hat rudi wie oben steht gerade erst eingebaut. in zukunft vermute ich aber einige. zumindest wenn es eine sinnvolle verwendung dafür gibt. das help modul wäre genau so eine...

Das Modul bestimmt nun die Sprache in folgender Reihenfolge:


  • Sprachparameter beim Aufruf übergeben
  • globales Attribut "language"
  • wenn nichts definiert ist: englisch


Wenn in einem Modul keine deutsche Hilfe gefunden wird, geht es mit einem entsprechenden Hinweis automatisch mit englisch weiter:

(http://up.picr.de/21048191pr.png)

Sind damit jetzt alle karierten Maiglöckchen gepflückt?
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

Markus Bloch

Hi betateilchen,

find dein Feature echt super, nur leider funktioniert es bei mir nicht.

Ich würde mich freuen, wenn du in folgender Zeile

Zeile 26:    my @modDir = ("FHEM");

auch AttrVal("global", "modpath","")."/FHEM" mit berücksichtigen könntest. Also:

Zeile 26:    my @modDir = ("FHEM",AttrVal("global", "modpath","")."/FHEM");

oder auch gerne anders.

Momentan stirbt mir FHEM bei jedem Aufruf von help <module> immer wegen dem die() komplett.

Vielen Dank

Gruß
Markus
Developer für Module: YAMAHA_AVR, YAMAHA_BD, FB_CALLMONITOR, FB_CALLLIST, PRESENCE, Pushsafer, LGTV_IP12, version

aktives Mitglied des FHEM e.V. (Technik)

betateilchen

Hallo Markus,

Änderung habe ich gerade eingeckeckt, kannst Du die mal bitte testen?


    my $modPath = AttrVal('global','modpath','.');
    my @modDir = ("$modPath/FHEM");


Viele Grüße
Udo
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

Markus Bloch

Developer für Module: YAMAHA_AVR, YAMAHA_BD, FB_CALLMONITOR, FB_CALLLIST, PRESENCE, Pushsafer, LGTV_IP12, version

aktives Mitglied des FHEM e.V. (Technik)

betateilchen

Zitat von: rudolfkoenig am 18 Februar 2015, 18:41:59
Bemerkungen:
- man koennte einige Abschnitte aus doc/commandref.html anzeigen, wie global, command, devspec, attributes und perl, auch weil man in FHEMWEB im global-Detailansicht "help global" aufgerufen wird. Falls deswegen commandref_frame.html angepasst werden muss,

Ab dem morgigen Update ist dann auch "help global" möglich. Die Informationen lese ich direkt aus den commandref_frame Dateien, weil die sehr viel kleiner sind als die komplette commandref.html.

Zu diesem Zweck habe ich in den frames am Ende von "global" einfach eine html-Kommentarzeile eingefügt. Diese stört nicht bei der Erzeugung der commandref und ich kann sie problemlos als Endekriterium für das Lesen des Abschnitts verwenden.

Wegen "help command": Da habe ich im Moment das Problem, dass nicht alle commands dort aufgeführt sind. Und es werden auch in der "einfachen" help nicht alle verfügbaren Befehle ausgegeben, sondern nur diejenigen, die entweder fest in fhem.pl eingebaut sind oder deren Moduldateien bereits einmal geladen wurden, weil der Befehl schonmal ausgeführt wurde. Irgendwie suche ich da noch eine "gute" Lösung.

Für devspec, attr und perl könnte ich vermutlich ein ähnliches Verfahren wie für "global" implementieren.
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

rudolfkoenig

Haken: commandref_frame*.html ist (noch?) nicht Teil des updates. :)

Vielleicht koennte in diesem Zusammenhang das update von commandref.html ausgebaut werden, und stattdessen commandref_join.pl vom lokalen FHEM-Rechner ausgefuehrt werden. Leider wird commandref_join.pl auch noch nicht mit update verteilt :)

Wenn du mit commands sowas wie help und update meinst, dann wuerde ich zunaechst nach einem Modul mit dem gleichen Namen suchen, und dann den Eintrag in commandref_frame. Befehle, die nicht in der passenden Datei sind, koennten ein Eintrag in %cmds hinterlegen  (SourceModule => "XXX").

betateilchen

Ich hab jetzt erstmal folgende Abschnitte noch mit eingebaut:

attributes, command, commands, devspec, global, perl

Das Lesen auf commendref.html umzubauen, ist kein großer Akt, an die update-Problematik habe ich nicht gedacht.

Zitat von: rudolfkoenig am 20 Februar 2015, 18:51:46
Vielleicht koennte in diesem Zusammenhang das update von commandref.html ausgebaut werden, und stattdessen commandref_join.pl vom lokalen FHEM-Rechner ausgefuehrt werden. Leider wird commandref_join.pl auch noch nicht mit update verteilt :)

Falls Du solch einen Umbau irgendwann umgesetzt hast, kann ich ja wieder problemlos aus den frames lesen :)
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

Benni

Hallo Udo,

hatte eben ein reproduzierbares, Absturz-Erlebnis bei help. Beim Rumprobieren ist mir nach Eingabe von

help webViewControl
FHEM hängen geblieben. (Ja, ich weiß, dass das falsch ist und nix kommen dürfte)

Im Log findet sich danach dann noch folgender Eintrag:

Zitat2015.02.21 08:35:49 1: PERL WARNING: Deep recursion on subroutine "main::CommandHelp" at ./FHEM/98_help.pm line 81.

Es bleibt nur noch der Neustart von FHEM von der shell aus.

Wenn ich allerdings

help blahblah

eingebe passiert das nicht es nicht, ich erhalte lediglich die Meldung, dass das Modul blahblah nicht geladen sei.

Vermutung: er findet oben zwar das geladene Modul WebViewControl, aber es gibt keinen passenden Eintrag in der Hilfe, der dazu gelesen werden könnte.

Gruß Benni.

betateilchen

Das ist ein Sonderfall, den ich nicht bedacht habe:

webviewcontrol ist mit Stand von heute kein offiziell von fhem ausgeliefertes Modul und hat keine Doku.

Die Hilfe geht aber derzeit davon aus, dass jedes in /FHEM/ vorhandendes Modul die Pflichtanforderung erfüllt, eine Doku zumindest in englisch zu besitzen.

Diesen Sonderfall werde ich noch abfangen.
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

betateilchen

Zitat von: betateilchen am 21 Februar 2015, 10:00:53
Diesen Sonderfall werde ich noch abfangen.

erledigt.

Zitat von: rudolfkoenig am 18 Februar 2015, 18:41:59
- help im telnet ist noch ziemlich unverstaendlich, siehe "help at" oder "help notify".

Das liegt aber primär an der Gestaltung der commandref-Texte in den jeweiligen Modulen selbst.
Eines der Hauptprobleme, das die Unleserlichkeit verursacht, sind fehlende <br> tags am Zeilenende, insbesondere in <pre>-Blöcken (z.B. in at)

Ich habe testweise den <pre> Block in 90_at.pm durch einen <code> Block mit <br> an den Zeilenenden, dann werden auch die Beispiele in telnet korrekt dargestellt.

html-formatierte Texte lassen sich nicht ohne weiteres in optisch "schöne" plain-Texte umwandeln. Auch nicht mit zusätzlichen perl Modulen.
-----------------------
Formuliere die Aufgabe möglichst einfach und
setze die Lösung richtig um - dann wird es auch funktionieren.
-----------------------
Lesen gefährdet die Unwissenheit!

rudolfkoenig

Ab sofort wird per update ausgeliefert: contrib/commandref_join.pl, docs/commandref_frame*.html, fhem.cfg.demo, demolog/*

Habe update erweitert, dass beim vorhandensein von commandref_join.pl die commandref.html nicht herunterlaedt, sondern es selbst generiert. Vorteil: eigene und third-party Module werden ins commandref.html integriert, und man laedt bei einem update 2.5MB weniger von fhem.de. Nachteil: Fehlermeldung, falls die eigene Utils.pm keine Doku enthaelt, und commandref_join.pl dauert auf einem Fritzbox schonmal 1-2 Minuten. Habe immerhin "this may take a while" hingeschrieben, bin gespannt, wieviele es ignorieren werden. Habs auf einem Fritzbox und auf einem "richtigen" Rechner getestet.

Ich habe FHEMWEB.pm geaendert, damit das Output von help nicht nachbearbeitet wird. Koenntest du bitte
- jede Zeile mit einem \n abschliessen, damit <pre> ordentlich ausschaut (Beispiel ist help at)
- <html></html> entfernen, ist eh "Unsinn", da diese Tags an die falsche Stelle im Dokument eingebaut werden, und damit von allen Browsern nur ignoriert werden.

ZitatDas liegt aber primär an der Gestaltung der commandref-Texte in den jeweiligen Modulen selbst.
Das meinte ich nicht. Wenn ich z.Zt. "help at" im telnet eingebe, dann kriege ich

<html> Start an arbitrary FHEM command at a later time.



<timespec> format: [+][*{N}]<timedet>


statt

Start an arbitrary FHEM command at a later time.

Define
define <name> at <timespec> <command>

<timespec> format: [+][*{N}]<timedet>


d.h. die eigentliche definition wurde verschluckt. Das waere aber mAn wichtig zu zeigen.