commandref-Darstellung

[Damian]

Ich möchte hier den Vorschlag aufwerfen in der Commandref pro Modul eine eigene Seite zu generieren.

Die Commandref hat inzwischen eine Länge von über 200 Papierseiten und es werden täglich mehr. Abgesehen von längeren Ladezeiten ist es nicht möglich nach Stichwörtern innerhalb eines Moduls sinnvoll zu suchen, weil dann immer die komplette Commandref von Anfang an durchsucht wird, bis man irgendwann an der gesuchten Stelle des jeweiligen Moduls landet. Das Stichwort "disable" hat z. B. 59 Treffer in der deutschen Version.

Gruß

Damian

[rudolfkoenig]

"Device Specific Help" auf der FHEMWEB Detail-Seite zeigt jetzt schon nur die Hilfe fuer das aktuelle Modul an.

Wir koennen auch den Rest anpassen, allerdings muss dafuer einiges umgebaut werden:
- etliche Querverweise, die davon ausgehen, dass es sich um eine Seite handelt muessen angepasst werden
- man muss eine Moeglichkeit fuer die Suche ueber alle Dokumente implementieren, sowohl fuer FHEMWEB, wie auch fuer http://fhem.de.
- updatefhem muss angepasst werden

Falls jemand fuer all das Patches bereitstellt, und auch sonst keine Gegenargumente kommen, waere ich bereit es zu impementieren.

[Markus Bloch]

Hallo Rudi,

- man muss eine Moeglichkeit fuer die Suche ueber alle Dokumente implementieren, sowohl fuer FHEMWEB, wie auch fuer http://fhem.de.

In FHEM selbst würde ich das in den help Befehl integrieren, welche eine Link-Liste der Module mit dem Stichwort liefert. In der Form von "help search <term>". Die Frage ist, muss das umbedingt auch auf fhem.de zur Verfügung stehen? Bisher hat Google alles gefunden, auch auf Unterseiten.

Die Unterteilung der Commandref in Unterseiten pro Modul finde ich super. In der Commandref würde ich mir dennoch eine kurz und knappe Erklärung zu dem Modul liefern. Quasi eine Tabelle mit dem Modulnamen, einer Kurzbeschreibung, sowie einem Link zur detaillierten commandref.

z.B.

Code Auswählen Erweitern


+----------------+--------------------------------------------------------------------------------------------+
| Modulname      | Kurzbeschreibung                                                                           |
+----------------+--------------------------------------------------------------------------------------------+
| YAMAHA_AVR     | Steuerung von AV-Receivern des Herstellers YAMAHA (RX-Vxxx-Serie / Avantage-Serie)         |
|                |                                                                                            |
| FB_CALLMONITOR | Generierung von Anruf-Events einer AVM FritzBox Fon (verschiedene Modelle)                 |
+----------------+--------------------------------------------------------------------------------------------+


Dazu würde ich vorschlagen im POD einen weiteren Abschnitt einzubauen (jeweils deutsch/englisch) der diese Kurzbeschreibung beinhaltet. Sollte dieser nicht vorhanden sein, steht dann auch nichts an Kurzbeschreibung in der Tabelle. Das würde es meiner Meinung nach neuen Usern erleichtern einen kurzen Überbblick über die Vielzahl an Modulen zu bekommen, die nicht immer einen treffenden Namen haben.

Sollte dies so akzeptiert werden, würde ich entsprechende Patches erstellen, sowie anbieten entsprechende Kurzbeschreibungen in allen Modulen nachzupflegen.

Viele Grüße

Markus

[Markus Bloch]

Hallo zusammen,

hier mal mein erster Wurf, welcher lediglich mittels commandref_join.pl die Doku aus den Module rausholt und entsprechend als HTML-Dateien ablegt, sowie die commandref.html entsprechend mit einer Liste der Module + Kurzbeschreibung erstellt.

Da bisher die Helpermodule direkt in der commandref_frame.html/commandref_frame_DE.html als Links gepflegt worden sind, lies sich dieses Schema nicht so ohne weiteres auf eine Tabelle übertragen. Dazu wurde im POD-Teil ein neuer "Schalter" eingefügt, den jedes Helper-Modul setzen muss um in der commandref auch unter "Helper-Module" geführt zu werden. Insgesamt gibt es folgende neuen POD-Marker:

• #helpermodule - Hieran erkennt commandref_join.pl ob dieses Modul als Helper-Modul zu führen ist (gilt für alle Sprachen)
• #begin brief_description / #begin brief_description_DE - Beginn der Kurzbeschreibung für die Modul-Tabelle in commandref.html/commandref_DE.html.
• #end brief_description / #endbrief_description_DE - Beginn der Kurzbeschreibung für die Modul-Tabelle in commandref.html/commandref_DE.html.

Also bspw:

Code Auswählen Erweitern


=pod
=helpermodule

=begin brief_description
Controls an ACME Toaster via USB.
=end brief_description

=begin brief_description_DE
Steuert einen ACME Toaster über USB.
=end brief_description_DE

=begin html
.......
=end html



Im Anhang findet ihr ein paar Bilder, sowie meine commandref_join.pl sowie eine neue commandref_frame.html/commandref_frame_DE.html sowie modul_frame.html/module_frame_DE.html welche das Grundgerüst für die modulspezifische Seite sind. Ich hab auch meine fertig generierte commandref.html/commandref_DE.html mit angehangen.

Beispielhaft kann man auf den Bildern nun direkt auf einem Blick erkennen wozu die verschiedenen ALLxxxx Module gedacht sind. Vorher waren die Namen nur aufgelistet, aber um zu erfahren, wofür die sind, musste man immer wieder drauf gehen. Dieses Problem hat mich zu Anfangs bei FHEM sehr gestört. So finde ich, ist es einfacher für den User auf die Schnelle zu erkennen, wozu ein bestimmtest Modul gedacht ist. Als Minimum sollte in der Brief-Description in einem Satz stehen: "Welches Gerät von welchem Hersteller man über welche Schnittstelle damit steuern kann".

Wenn das so passt, würde ich entsprechend noch Patches für alles drumherum (help-Modul, update-Modul, Suchfunktion in FHEM,...) erstellen.

Was an Änderungen in allen Modulen zu tun wäre, wenn man diesen Weg geht:
- Flaggen aller Helper-module durch "#helpermodule" im POD Abschnitt sämtlicher Module (aktuell 57 Module)
- Setzen einer Brief-Description (mind. Englisch). commandref_join.pl gibt sonst eine entsprechende Warnung aus (ich finde so etwas sollte man als mandatory nehmen)
- Anpassen von Links (z.B. event-change-reading,event-update-reading) von <a href="#..."> zu <a href="commandref.html#..."> (oder auf das entsprechende Modul-HTML falls modulübergreifend)

Sofern niemand etwas dagegen hat, würde ich anbieten die entsprechenden Änderungen der POD sowie Links von sämtlichen Modulen zu übernehmen.

Bin gespannt, was ihr sagt.

Viele Grüße

Markus

[Wuppi68]

dann würde ich auch vorschlagen die dependicies mit aufzunehmen

also die Module für use und Require

[Damian]

Hallo zusammen,

hier mal mein erster Wurf, welcher lediglich mittels commandref_join.pl die Doku aus den Module rausholt und entsprechend als HTML-Dateien ablegt, sowie die commandref.html entsprechend mit einer Liste der Module + Kurzbeschreibung erstellt.

Da bisher die Helpermodule direkt in der commandref_frame.html/commandref_frame_DE.html als Links gepflegt worden sind, lies sich dieses Schema nicht so ohne weiteres auf eine Tabelle übertragen. Dazu wurde im POD-Teil ein neuer "Schalter" eingefügt, den jedes Helper-Modul setzen muss um in der commandref auch unter "Helper-Module" geführt zu werden. Insgesamt gibt es folgende neuen POD-Marker:

• #helpermodule - Hieran erkennt commandref_join.pl ob dieses Modul als Helper-Modul zu führen ist (gilt für alle Sprachen)
• #begin brief_description / #begin brief_description_DE - Beginn der Kurzbeschreibung für die Modul-Tabelle in commandref.html/commandref_DE.html.
• #end brief_description / #endbrief_description_DE - Beginn der Kurzbeschreibung für die Modul-Tabelle in commandref.html/commandref_DE.html.

Also bspw:

Code Auswählen Erweitern


=pod
=helpermodule

=begin brief_description
Controls an ACME Toaster via USB.
=end brief_description

=begin brief_description_DE
Steuert einen ACME Toaster über USB.
=end brief_description_DE

=begin html
.......
=end html



Im Anhang findet ihr ein paar Bilder, sowie meine commandref_join.pl sowie eine neue commandref_frame.html/commandref_frame_DE.html sowie modul_frame.html/module_frame_DE.html welche das Grundgerüst für die modulspezifische Seite sind. Ich hab auch meine fertig generierte commandref.html/commandref_DE.html mit angehangen.

Beispielhaft kann man auf den Bildern nun direkt auf einem Blick erkennen wozu die verschiedenen ALLxxxx Module gedacht sind. Vorher waren die Namen nur aufgelistet, aber um zu erfahren, wofür die sind, musste man immer wieder drauf gehen. Dieses Problem hat mich zu Anfangs bei FHEM sehr gestört. So finde ich, ist es einfacher für den User auf die Schnelle zu erkennen, wozu ein bestimmtest Modul gedacht ist. Als Minimum sollte in der Brief-Description in einem Satz stehen: "Welches Gerät von welchem Hersteller man über welche Schnittstelle damit steuern kann".

Wenn das so passt, würde ich entsprechend noch Patches für alles drumherum (help-Modul, update-Modul, Suchfunktion in FHEM,...) erstellen.

Was an Änderungen in allen Modulen zu tun wäre, wenn man diesen Weg geht:
- Flaggen aller Helper-module durch "#helpermodule" im POD Abschnitt sämtlicher Module (aktuell 57 Module)
- Setzen einer Brief-Description (mind. Englisch). commandref_join.pl gibt sonst eine entsprechende Warnung aus (ich finde so etwas sollte man als mandatory nehmen)
- Anpassen von Links (z.B. event-change-reading,event-update-reading) von <a href="#..."> zu <a href="commandref.html#..."> (oder auf das entsprechende Modul-HTML falls modulübergreifend)

Sofern niemand etwas dagegen hat, würde ich anbieten die entsprechenden Änderungen der POD sowie Links von sämtlichen Modulen zu übernehmen.

Bin gespannt, was ihr sagt.

Viele Grüße

Markus

Ich finde deine Umsetzung gut. Allerdings werden viele Module zunächst keine Kurzbeschreibung haben, was auf der Hauptseite etwas blöd aussieht. Es fehlt auch noch die globale Suche. Dafür könnte man irgendwo auf der Hauptseite ein Link Alle aufnehmen, damit man die alte Darstellung mit ihren Vor-  und Nachteilen hat, aber dort, wie gewohnt, global suchen kann.

Gruß

Damian

[Markus Bloch]

Ich finde deine Umsetzung gut. Allerdings werden viele Module zunächst keine Kurzbeschreibung haben, was auf der Hauptseite etwas blöd aussieht. Es fehlt auch noch die globale Suche. Dafür könnte man irgendwo auf der Hauptseite ein Link Alle aufnehmen, damit man die alte Darstellung mit ihren Vor-  und Nachteilen hat, aber dort, wie gewohnt, global suchen kann.

Gruß

Damian

Hallo Damian,

wie bereits geschrieben würde ich die Kurzbeschreibungen verfassen und einen großen Patch erstellen, falls die Lösung eingecheckt wird.

Das Thema "Suche" ist recht schwierig. Dazu brauch man Intelligenz auf der Server-Seite, die eine Such-Funktion bereitstellt (sowohl innerhalb von FHEM, also FHEMWEB, als auch auf fhem.de). Dein Vorschlag weiterhin beide Varianten zu erstellen, wo man dann via Link auf die alte, bisherige Variante wechseln kann, würde funktionieren ohne großen Aufwand. Ich persönlich musste noch nie über die gesamte commandref suchen. Wenn ich etwas gesucht habe, dann wusste ich zumindest welches Modul das betrifft (Parameter/Attribute/Readings-Bedeutung).

Viele Grüße

Markus

[Markus Bloch]

dann würde ich auch vorschlagen die dependicies mit aufzunehmen

also die Module für use und Require

Das sehe ich eher als Aufgabe beim Modulentwickler, dies in die Doku zu seinem Modul aufzunehmen. Es gibt Module die brauchen unbedingt bestimmte Zusatzmodule. Andere wiederum prüfen nur ob ein Perl-Modul vorhanden ist, wenn ja, nutzen sie dessen Features, wenn nicht, wird das FHEM-Modul-Feature was dieses Perl-Modul benötigt nicht zur Verfügung gestellt.

Durch parsen von use/require-Statements kommt man so nicht an eine definitive Liste aller wirklich benötigten Abhängigkeiten um ein FHEM-Modul zu nutzen.

btw würde ich das eh nicht auf der commandref.html direkt in der Modul-Tabelle anzeigen wollen. Ist teilweise einfach viel zu viel.

Viele Grüße

Markus

[justme1968]

ich bin etwas hin und her gerissen...

auf dauer sind die einzelnen kurzen seiten vermutlich besser handhabbar und beim update muss auch deutlich weniger neu generiert werden. die tabelle mit den kurzbeschreibungen sind für einsteiger aber sicher sehr nützlich und geben einen guten überblick.

ich vermisse aber das globale suchen. sogar wenn ich weiss um welches modul es geht bin ich mit ⌘F<text> schneller als mit scrollen und klicken. nur dafür dann doch wieder eine lange seite zu erzeugen wäre dann aber blöd.

neben dem wie für die globale suche müsste auch noch entschieden werden wie sich die links innerhalb der aufklappenden device specific help seiten verhalten sollen. in place ersetzen des aktuellen textes oder ersetzen der ganzen seite so das nur noch der text hinter dem link zu sehen ist.

zusätzlich zu #helpermodule braucht es glaube ich noch ein #command sonst tauchen cmdalias,copy,help und etwa 10 andere doppelt auf. ein mal unter commands und dann noch in der tabelle mit den modulen. (wie wäre ein #fhemmoduletype <type>?)

gruss
  andre

ps: das mit dem automatischen erkennen der dependencies wäre zwar schön aber das ist vermutlich schwierig zuverlässig hin zu bekommen da es mehrere module gibt die das use oder require mit eval kapseln um selber fehler abzufangen, zwischen unterschiedlichen implementierungen umzuschalten oder alternativ features dazu zu nehmen oder abschalten.

[rudolfkoenig]

Die Patches loesen von meinem vorherigen drei Punkten keins, und nach etwas nachdenken sehe ich die Vorteile dieser Loesung nicht, oder ich mache mir ein falsches Bild davon, was ersetzt werden soll.

Wenn jemand nur die Hilfe fuer ein Modul sehen will, der kann das von der Detail-Seite haben, das ist im Zweifel ein Klick naeher, und auf der gleichen Seite wie die Eingabefelder. Wenn die komplette commandref.html durch diese Loesung ersetzt werden soll, dann gibt es keine sinnvolle Suche ueber Module hinweg (und ja, das braucht man), und die internen Verlinkungen (auf andere Module/Attribute) funktionieren (erstmal) auch nicht.

Nicht falsch verstehen: ich schneide alte Zoepfe gerne ab, aber dann soll es klare Vorteile geben, und nicht nur ein "Unentschieden".

[Damian]

Die Patches loesen von meinem vorherigen drei Punkten keins, und nach etwas nachdenken sehe ich die Vorteile dieser Loesung nicht, oder ich mache mir ein falsches Bild davon, was ersetzt werden soll.

Wenn jemand nur die Hilfe fuer ein Modul sehen will, der kann das von der Detail-Seite haben, das ist im Zweifel ein Klick naeher, und auf der gleichen Seite wie die Eingabefelder. Wenn die komplette commandref.html durch diese Loesung ersetzt werden soll, dann gibt es keine sinnvolle Suche ueber Module hinweg (und ja, das braucht man), und die internen Verlinkungen (auf andere Module/Attribute) funktionieren (erstmal) auch nicht.

Nicht falsch verstehen: ich schneide alte Zoepfe gerne ab, aber dann soll es klare Vorteile geben, und nicht nur ein "Unentschieden".

naja, mit einem Link alle hätte man den alten Modus. Und egal wie die Lösung aussehen wird, ich habe kaum eine andere Seite im Netz gesehen, die mehr als 200 Druckseiten hätte und demnächst noch viel mehr - es ist also nur Frage der Zeit bis es bei den ersten "buff" macht, weil irgendein Browser seinen Speicherüberlauf hat. Zu der internen Verlinkung kann ich nichts sagen.

Gruß

Damian

[Markus Bloch]

Nunja zum Thema suchen:

Meine Idee wäre ein "help search <Term>" als fhem Befehl zu implementieren. Nachteil wird dabei die Dauer der Suche sein (öffnen sämtlicher Module + durchsuchen) gegenüber einer Suche im Browser.

[Markus Bloch]

Die Patches loesen von meinem vorherigen drei Punkten keins, und nach etwas nachdenken sehe ich die Vorteile dieser Loesung nicht, oder ich mache mir ein falsches Bild davon, was ersetzt werden soll.

Wenn jemand nur die Hilfe fuer ein Modul sehen will, der kann das von der Detail-Seite haben, das ist im Zweifel ein Klick naeher, und auf der gleichen Seite wie die Eingabefelder. Wenn die komplette commandref.html durch diese Loesung ersetzt werden soll, dann gibt es keine sinnvolle Suche ueber Module hinweg (und ja, das braucht man), und die internen Verlinkungen (auf andere Module/Attribute) funktionieren (erstmal) auch nicht.

Nicht falsch verstehen: ich schneide alte Zoepfe gerne ab, aber dann soll es klare Vorteile geben, und nicht nur ein "Unentschieden".

Alternativer Vorschlag:

Die Kernprobleme an der aktuellen commandref aus meiner Sicht ist zu aller erst die Tatsache der schieren Größe. Wenn man sich ein Modul durchgelesen hat und möchte direkt zu einem anderen Modul/Parameter geht das entweder durch Suchen im Browser, oder durch manuelles nach oben scrollen und anschließend aus dem schieren Wust an dicht gedrängten Links den richtigen Link zu erwischen (was auch immer mal wieder daneben geht).

Wie wäre es, wenn man nach jedem Modulabschnitt einen Link "back to top" einfügt, der wieder nach oben zur Modulübersicht führt? Desweiteren würde ich gerne die Modulübersicht in eine Tabelle inkl. Kurzusammenfassung verwandeln (so wie es mein erster Vorschlag von commandref_join.pl macht), damit man einen schnellen Überblick über die Module hat, sowie eine saubere Auflistung inkl. Kurzbeschreibung und nicht einfach nur eine Liste an Links. Der Modullink verweist dann auf den entsprechenden Abschnitt auf der Seite.

Damit würde die Suchfunktionalität erhalten bleiben. Man müsste einmalig die POD-Marker pflegen (was ich nachwievor anbiete zu übernehmen). Newbies/Anfänger wären nicht mehr so "erschlagen" von der Liste der verfügbaren Module, da sie sofort eine Vorstellung haben, worum es grob in dem jeweiligen Modul geht. Tatsache ist, dass die Modulliste eher wächst als schrumpft, daher sehe ich eine solche Kurzbeschreibung als ein großen Vorteil.

Viele Grüße

Markus

[Markus Bloch]

Hier noch ein Beitrag, welcher per PM bei mir gelandet ist.

Hi Markus, da ich nicht als develop eingetragen bin um in dem Thread zu posten hier mal ein vorschlag per PN

Wie wäre es die ganzen Modulabschnitte per JS & CSS (visibility) zu verbergen und mit einem window.onhashchange = function () {} wieder entsprechend 'visible' zu schalten?

Damit würden die ganzen verlinkungen welche Rudi bemängelt hat weiterhin funktionieren, die Seite wäre kleiner und würde auch in Zukunft keine Browser Buffer sprengen, die generelle funktionsweise der Links bleibt gleich und die geplanten Änderungen wären dadurch machbar.

Über einen Link könnte man auch auf einen Schlag alle Abschnitte wieder 'visible' setzen um bequem über alles suchen zu können.

Gruß Claudiu

Das wäre durchaus auch eine gute Idee. Die commandref wird mittels jquery im Browser so umgebaut, dass der entsprechende Abschnitt in der commandref erst dann eingeblendet wird, wenn man auf einen Link klickt + eben einen Link der alle Beiträge sichtbar macht zum suchen per Browser.

Viele Grüße

Markus

[rudolfkoenig]

Vorschlag aus Antwort #12 und #13: habe nichts dagegen, kommt auf TODO.