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.

[Markus Bloch]

Ich werde in den nächsten Tagen/Wochen einen Patch erstellen.

Viele Grüße

Markus

[Markus Bloch]

Kurze Frage: Wie ist das momentan mit commandref_join.pl geregelt? Wird commandref_join.pl auf dem Server fhem.de ausgeführt und das Ergebnis per update verteilt, oder ist es nachwievor so, dass commandref_join.pl auf jedem System lokal aufgerufen wird, nach einem Update?

Ich meine mich zu Erinnern, dass es da etwas hin und her ging, da sich viele User gewundert haben, weil es teilweise sehr lange dauert auf bestimmten Systemen.

Aktuell sehe ich, dass "update" nachwievor commandref_join.pl am Ende eines Updates ausführt. Sollte das nachwievor so bleiben, muss ich die gesamten Module 2x öffnen und einlesen um nicht so viel RAM zu verbrauchen. Normalerweise würde ich momentan alle Module einmal einlesen. In dem Zuge direkt die Modulübersicht ausprinten und die eigentliche Doku in einer Variable zwischenspeichern, da ja noch die Helper-Modul-Tabelle zuerst ausgegeben werden muss und anschließend die gesamte Doku + Rest aus commandref_frame.

Wenn ich die Module 2x einlese wird zwar weniger RAM verbraucht, dauert aber dafür länger. Da die commandref nicht mehrere MB groß ist, würde ich daher die Module einmalig einlesen wollen mit allen Inhalten und dann daraus in einem Rutsch alle Dateien erzeugen wollen. Der RAM-Mehrverbrauch sollte auch auf kleinen Systemen keine Probleme darstellen, da wir hier von einem Memory Footprint von max 1-2MB reden.

Ist das so in Ordnung?

Gruß
Markus

[rudolfkoenig]

commandref_join.pl wird auf meinem Server um 7:45 ausgefuehrt, und die Datei auf fhem.de hochgeladen. Sie wird aber von den Benutzern nicht heruntergeladen, um das fhem.de Traffic etwas zu schonen, sondern am Ende des update Vorgangs von jeder FHEM-Installation erneut erstellt. Es sei denn der Benutzer hat das durch diverse Massnahmen unterbunden, dann gibt es aber auch keinen aktuellen commandref.html auf dem System. Wer nur die Hilfe im Detailmodus verwendet, den sollte das nicht stoeren.

Wg. alles in RAM: aktuell haben wir ca 10MB an Modulen, und Perl braucht ca 6x soviel, wenn das im Speicher ist, jedenfalls war das beim Ausliefern von Log-Dateien ueber FHEMWEB vor das Einfuehren von Streaming der Fall.

Da ich in der Vergangenheit mit solchen Patches Probleme hatte, schlage ich vor, dass ich das diesmal selbst erstellen werde.

[Talkabout]

Hallo zusammen,

um die Größe der Commandref-Seite zu reduzieren wäre auch ein Ansatz über AJAX möglich. Dabei würde man die Commandref-Seite vorerst "nur" mit dem Modul-Namen+Kurzbeschreibung anzeigen. Dazu hätte man dann einen Link "mehr...", der den restlichen Content dynamisch nachlädt. Vorteile dieser Methode:

- der Umbau wäre nicht so gross
- die Grundstruktur würde sich nicht ändern
- Suche über Browser weiterhin möglich
- die Größe der initialen Seite wäre wesentlich kleiner

Mir geht es in den meisten Fällen so, dass ich tatsächlich nur ein paar der verfügbaren Module sehen will. Das wäre damit gut möglich.

Gruss

[Markus Bloch]

@Rudi: Ich weis leider nicht, wie du es dir nun genau vorstellst, aber lass es mich wissen, wenn ich dir etwas an Arbeit abnehmen kann. Du musst nicht alles alleine machen

Gruß
Markus

[rudolfkoenig]

Hat etwas laenger gedauert, aber jetzt habe ich es implementiert.

- ueber "attr global commandref" kann man mit "full" die alte Version (Voreinstellung) und mit "modular" die Neue einstellen, das wird auch beim update respektiert. Die neue Version wird mit contrib/commandref_modular.pl erzeugt, bei mir deutlch schneller als mit commandref_join.pl

- die modulare Version enthaelt, wie vorgeschlagen, eine Auflistung mit Kurzbeschreibung am Anfang, die Moduldokumentation wird per JavaScript und help dynamisch geladen.

- beide Versionen haben ein "Scroll to top" bekommen, das "Load complete doc" ist sinnvollerweise nur beim Modularen vorhanden.

- nur beim Modularen gibts das Feature "Load german doc for XXX", damit kann man die jeweils andere Fassung anschauen. Das gilt nur fuer die ladbaren Texte.

- ich bitte Euch, Eure Module mit "=item summary XXX" bzw. "=item summary_DE YYY" zu ergaenzen, damit die Tabelle sinnvolle Kurzbeschreibungen enthaelt, gerne beide selbst dann, wenn die deutsche Dokumentation nicht gepflegt wird. Ich habe es bei meinen Modulen gemacht, als Beispiel siehe 91_notify.pm

Das Ganze steht ab sofort per update zur Verfuegung, da ich da auch Anpassungen vornehmen und testen musste.

[Markus Bloch]

Wow, super! Vielen Dank!

Ich habe meine Module soeben mit einer Summary versehen.

Gruß
Markus

[Icinger]

Meine sind ebenfalls schon geupdatet

lg, Stefan

[betateilchen]

ich würde es begrüßen, wenn die commandref beim Klick aus einem laufenden FHEM-Frontend in einem neuen Tab/Fenster geöffnet wird, weil es (abgesehen vom Zurück-Button im Browser) keinen "Weg zurück" zum laufenden FHEM gibt, in dem man sich gerade befand.

[betateilchen]

ueber "attr global commandref" kann man mit "full" die alte Version (Voreinstellung) und mit "modular" die Neue einstellen

Das Ganze funktioniert aber nicht, wenn man versucht, das Attribut über das Dropdown im Frontend auszuwählen. Es wird zwar getan, was dem Attribut entspricht (also commandref_join bzw. commandref_modular ausgeführt) aber das Attribut selbst wird nicht gesetzt.

[Loredo]

Meine sind ebenfalls schon geupdatet

Dito!

[DeeSPe]

Hab mein eines bescheidenes Modul auch um die summary ergänzt.
Sind ja bald die 12000 commits voll. Hab aber auch mit einem Fehl-commit dazu beigetragen. Sorry... 

Gruß
Dan

[Loredo]

<comfortMode>
Man könnte commandref_modular.pl auch noch mit Ausführungsrechten versehen 
</comfortMode>

[betateilchen]

@Loredo
Wenn Du das brauchst, kannst Du das bei Dir ja gerne tun.
Als Standard möchte ich die Ausführungsrechte lieber nicht haben.
Meinen Komfort schränkt das Fehlen des x-Flagsin keiner Weise ein.

[Loredo]

Ich fragte mich halt, weshalb commandref_join.pl es verdient hat out of the Box ausführbar zu sein, commandref_modular.pl jedoch nicht.

[betateilchen]

weshalb commandref_join.pl es verdient hat

Vermutlich ein Versehen 

[fhainz]

Das Ganze funktioniert aber nicht, wenn man versucht, das Attribut über das Dropdown im Frontend auszuwählen. Es wird zwar getan, was dem Attribut entspricht (also commandref_join bzw. commandref_modular ausgeführt) aber das Attribut selbst wird nicht gesetzt.

Kann ich bestätigen. Hatte das selbe Problem auch.

[rapster]

- Auch die Anker-Links in der Modularen Commandref funktionieren noch nicht.
- Die Short-Description vom Modul 74_Unifi wurde geladen, die von 70_VolumeLink nicht.
  Sowohl DE auch auch EN.

[Markus Bloch]

- Die Short-Description vom Modul 74_Unifi wurde geladen, die von 70_VolumeLink nicht.
  Sowohl DE auch auch EN.

siehe Anhang

Gruß
Markus

[rapster]

Danke, da bin ich auf den Kopf gefallen

[rudolfkoenig]

Vermutlich ein Versehen

Richtig. svn nimmt wohl die Berechtigung beim Einchecken. Und ich weiss noch nicht, wie man das nachtraeglich aendert.

Das Ganze funktioniert aber nicht, wenn man versucht, das Attribut über das Dropdown im Frontend auszuwählen.

Danke fuer den Hinweis, habs gefixt.

ich würde es begrüßen, wenn die commandref beim Klick aus einem laufenden FHEM-Frontend in einem neuen Tab/Fenster geöffnet wird

Habs gemacht.

Die Short-Description vom Modul 74_Unifi wurde geladen, die von 70_VolumeLink nicht.

Kein Wunder, da steht auch +=item statt =item. Kurzbeschreibung sollte bitte kurz sein (Vorschlag: <80Char). Wiederholung des Modulnamens ist kontraproduktiv (steht ja links direkt daneben), und sie muss auch nicht vollstaendig sein, der Benutzer kann notfalls den Link aufrufen.

[Markus Bloch]

Anbei noch einen kleinen Patch um die Sortierung der Module Case-insensitiv zu machen. So ist es auch in der alten commandref.

Code Auswählen Erweitern

Index: contrib/commandref_modular.pl
===================================================================
--- contrib/commandref_modular.pl       (revision 11986)
+++ contrib/commandref_modular.pl       (working copy)
@@ -88,7 +88,7 @@
       }
       print OUT "<table class='block summary class_$type'>\n";
       my $rc = "odd";
-      for my $m (sort keys %modData) {
+      for my $m (sort {uc($a) cmp uc($b)} keys %modData) {
         next if(!$modData{$m}{type} || $modData{$m}{type} ne $type);
         my $d = $modData{$m}{"summary$sfx"};
         if(!$d) {


Gruß
Markus

[Markus Bloch]

Kurzbeschreibung sollte bitte kurz sein (Vorschlag: <80Char). Wiederholung des Modulnamens ist kontraproduktiv (steht ja links direkt daneben), und sie muss auch nicht vollstaendig sein, der Benutzer kann notfalls den Link aufrufen.

Das riecht für mich nach einer Erweiterung des pre-commit Hook. Könnte ich gerne bauen. Ja/Nein/Vielleicht/Toastbrot?

[betateilchen]

Ja/Nein/Vielleicht/Toastbrot?

Ja.

[betateilchen]

Richtig. svn nimmt wohl die Berechtigung beim Einchecken. Und ich weiss noch nicht, wie man das nachtraeglich aendert.

Du kannst einfach die property ändern. Bei mir im svn-client muss ich dazu nur eine checkbox ändern und neu einchecken.

[rudolfkoenig]

Das riecht für mich nach einer Erweiterung des pre-commit Hook. Könnte ich gerne bauen.

Gerne. Wollte ich auch machen, da war mir aber bei der Menge der Aenderungen doch zu viel auf einmal.
Weiss jemand, wie man Dateien nach sourceforge kopiert? Ich finde copy&paste doof.

- Auch die Anker-Links in der Modularen Commandref funktionieren noch nicht.

Erstens fuegt help ein _target="blank" ein, das muesste ich noch rueckgaengig machen, und zweitens sollte commandref_modular.pl auch die Liste von Anker in commandref abspeichern, damit der Klick auf dem Link das richtige Modul laedt. Kann aber noch dauern, es sei denn, es faengt an zu regnen

Anbei noch einen kleinen Patch um die Sortierung der Module Case-insensitiv zu machen. So ist es auch in der alten commandref.

Habs eingecheckt.

[Loredo]

- Auch die Anker-Links in der Modularen Commandref funktionieren noch nicht.

Ich habe im Chrome Browser festgestellt, dass man manchmal zweimal auf den Link klicken muss, damit er zur Sprungmarke findet. Vermutlich weil beim ersten Klick die Sprungmarke noch nicht da ist...

[Markus Bloch]

Anbei der Patch für pre-commit Hook. Folgende Änderungen sind enthalten:

- Wenn die Summary Description länger als 80 Chars ist (ohne Leerzeichen am Anfang/Ende) erscheint folgende Meldung:

Code Auswählen Erweitern

*** trunk/fhem/FHEM/71_YAMAHA_AVR.pm: EN: summary is longer than 80 chars on line 2095

- Wenn keine englische Summary Description enthalten ist, erscheint folgende Meldung:

Code Auswählen Erweitern

*** trunk/fhem/FHEM/71_YAMAHA_AVR.pm: EN: No summary description found


Getestet habe ich das ganze wie immer mit einer lokalen Spiegelung des Repository.

Gruß
Markus

[rudolfkoenig]

Anbei der Patch für pre-commit Hook.

Habs eingecheckt, aktiviert und kurz getestet.
Kopieren nach sourceforge kann man mit scp, nachdem man sf-help aufgerufen und gelesen hat.

[rudolfkoenig]

Habe eine neue Version von fhemdoc_modular.js/commandref_modular.pm eingecheckt, damit cross-Modul-Links (wie z.Bsp. <a href="#disable">) funktioniert.

[Markus Bloch]

Funktionieren damit auch Links die auf Attribute in anderen Modulen verweisen? <a href="#disable"> bedeutet ja nicht "lad das Modul disable". Typischer Fall ist ja hier immer <a href="#dummy">

Ich habe mir die Änderungen angeschaut, bin mir aber nicht sicher, ob dies abgedeckt ist.

Gruß
Markus

[rudolfkoenig]

Dann solltest es probieren, Klick auf disable klappt bei mir verlaesslich. Musste etwas betruegen, da etliche Module disable mit <a name="disable"> definieren: ich uebernehme die erste Definition, un das ist im at Modul, was mir gehoert

Btw: manche Module verwenden das # mAn falsch, insb. in CUL_HM und HMInfo sind die meisten Namen mit # definiert, und das ist eigentlich nicht im Sinne der Erfinders: name gehoert ohne #, href mit #. @Martin: bitte fixen
Ich habe mich selbst bei dem Unsinn auch ertappt, und habe 3 Module korrigiert

[Markus Bloch]

Top! Funktioniert 

[UliM]

Hallo,
schon seit einiger Zeit finde auch ich, dass das Inhaltsverzeichnis der commandref immer unübersichtlicher wird.
Möchte dazu einen Vorschlag zur Diskussion stellen und bin bei der Suche nach Vorhandenem auf diesen thread gestoßen.

@Markus: Was ist denn daraus geworden? Soll hier noch was passieren, wie soll es aussehen, was müssen einzelne developer beitragen?

Über das (soweit ich gelesen habe) bereits Vorgeschagene hinaus möchte ich zur Diskussion stellen, die Module zu kategorisieren.
Helper / Nicht-Helper gibt's ja schon, das scheint mir angesichts der Anzahl der Module aber mittlerweile etwas knapp.
Ich möchte gerne 2 Dimensionen vorschlagen mit zB diesen initialen Wertelisten:
1. Übertragungsweg: Funk, dediziertes Kabel/Bus, LAN/WLAN, Webservice - auf dieser Ebene würde auch die Kategorie Helper passen
2. Anwendungsgebiet:  Messen, Schalten, Regeln, Multimedia, ClimateControl, EnergyControl, GUI-representation (für readingsProxy etc)
In beiden Dimensionen sollen Mehrfachnennungen möglich sein.
Initle Befüllung der Parameter könnte ich übernehmen an hand Analyse vorhandener Threads im Forum in den entspr. Themengebieten.
Als Nutzen erwarte ich, dass vor allem Anfänger sich leichter einen Überblick verschaffen können welche Anwendungsgebiete fhe abdeckt, und welche Modue dafür jeweils vorhanden sind.
Welche Dimensionen mit welchen Werten am Ende verwendet warden sollen, kann man ja gemeinsam erarbeiten, im ersten Schritt geht's mir um das "ob", noch nicht um das "wie".

Erste Frage an Markus als Thread-Eröffner: passt das hier rein oder soll ich nen separaten Thread aufmachen?

Gruß, Uli

[Loredo]

Ein sehr guter Vorschlag.

Lässt sich in dem Atemzug auch noch über die Formatierung nachdenken? Auch wenn das bedeutete, dass man jedes Modul dafür anfassen müsste, fände ich es besser die Doku in Markdown Format zu hinterlegen. Ich gebe zu die Formatiererei ist aktuell so aufwändig, dass dies auch ein Grund ist die Doku eher knapp zu halten oder nicht gut zu pflegen. Etwas wie Markdown würde mir da wirklich sehr helfen, vielleicht geht es ja auch anderen so?


Gruß

Julian

[rudolfkoenig]

Was ist denn daraus geworden? Soll hier noch was passieren, wie soll es aussehen, was müssen einzelne developer beitragen?

Man kann fuer die eigene FHEM-Installation die Anzeige/Generierung des commandrefs umstellen auch modular.
Leider verwendet das Feature FHEM bzw. das help Befehl, funktioniert also nicht auf http://fhem.de/commandref.html.
Dazu muessten wir noch was ueberlegen, ist bei mir unten auf der TODO Liste. Falls jemand vorpreschen moechte, nur zu.

Zu deiner weiteren Kategorisierung habe ich keine fertige Meinung.
Nur die Angabe hilft nicht, man braeuchte auch eine geaenderte Darstellung.

fände ich es besser die Doku in Markdown Format zu hinterlegen

Und ich haette gerne FHEM als node.js Projekt umgebaut, waere deutlich schneller, und das leidige blockieren Thema waere auch weg. Sorry, das war unhoeflich, aber ich finde deinen Vorschlag sehr aufwendig umzusetzen, insb. die Tests, dass es in allen Browsern mit allen Styles funktioniert. Doku & SVN-Hooks sind auch nicht zu vergesessen. Und dann muessen alle Modulautoren ueberzeugt werden, es gibt bestimmt welche, die lieber dieses eingeschraenkte HTML machen. Aber falls du fuer die Umstellung fertige Skripte hast, und das Ergebniss deutliche Vorteile hat, dann koennen wir das zur Diskussion stellen.

[Loredo]

Sorry, das war unhoeflich

Sehr.
-> /dev/null

[UliM]

Nur die Angabe hilft nicht, man braeuchte auch eine geaenderte Darstellung.

Stimmt. Ich würd mir etwas vorstellen was neumodisch "tabs" heisst.
Also als default-Darstellung "Everything" wie bisher, alternativ (nach klick) nach Kategorie A (Uebertragungsweg / connection type) oder B (Anwendungsgebiet / usage area) sortiert/gegliedert. M.E. einzig fraglicher Punkt ist Darstellung bei Mehrfachzuordnung in einer Kategorie.

Voraussetzung sind aber sinnvolle Kategorien und Werte, das ist m.E. der Dreh- und Angelpunkt.

Rudi, wenn Du kein Veto einlegst, würde ich mal nen konkreten Vorschlag machen.
Wäre eine Umsetzung dann über zusätzliche POD-Parameter möglich?

Gruß, Uli

[rudolfkoenig]

Rudi, wenn Du kein Veto einlegst, würde ich mal nen konkreten Vorschlag machen.

Nur zu. ich schlage "=item category XX,YY,ZZ" vor, wobei die bisherigen "=item command", "=item device" und "=item helper" noch beruecksichtigt werden, damt nicht alles umgebaut wird.

Wofuer willst du es einbauen? commandref_join.pl oder commandref_modular.pl? Ich sehe die Zukunft in commandref_modular.pl, da fehlt aber noch die "statische" Unterstuetzung, damit es ohne fhem.pl auf fhem.de laufen kann.

[UliM]

ich schlage "=item category XX,YY,ZZ" vor, wobei die bisherigen "=item command", "=item device" und "=item helper" noch beruecksichtigt werden, damt nicht alles umgebaut wird.

Wenn es 2 Dimensionen gibt, aber nur einen identifier "category", dann müssten die Werte Tupel sein:
=item category connection:WLAN,LAN;usage:Multimedia,ClimateControl
Geht das?

Würde bevorzugen
=item connection WLAN,LAN
=item usage Multimedia,ClimateControl
Oder geht nur genau ein einziges tag?

Wofuer willst du es einbauen? commandref_join.pl oder commandref_modular.pl? Ich sehe die Zukunft in commandref_modular.pl, da fehlt aber noch die "statische" Unterstuetzung, damit es ohne fhem.pl auf fhem.de laufen kann.

Na wenn Du da die Zukunft siehst, würde ich's an commandref_modular.pl versuchen

M.E. sollte die neue Darstellung primär in der commandref auf fhem.de platziert werden.

Gruß, Uli

[rudolfkoenig]

Oder geht nur genau ein einziges tag?

Tags gibts einerseits beliebig viele (weil =item von mir enteignet wurde), andereseits sollten wir fuer einen Zweck nicht beliebig viele erfinden, da weiss man naemlich nicht mehr, was wozu ist. Und ich habe den Verdacht, dass du mit connection und usage nicht am Ende bist. Vorschlag: mehrere =item category Zeilen, dann kannst du den Trenner auch sparen.