Weiterentwicklung commandref, war: Deutsche commandref-Sektion für 99_SUNRISE_EL.pm

[rudolfkoenig]

Ich hab die commandref bei mir gebaut und sie sah gut aus. Anbei ist ein Patch damit du die Änderungen bei dir einspielen und selbst testen kannst.

Danke schoen. Habe noch die Umlaute in HTML-Notation konvertiert (da ich allergisch auf Nicht-ASCII in Programmierdateien bin), alles in <ul> eingeschlossen (damit es genauso ausschaut, wie die anderen Module), kurz bewundert und getestet (mit contrib/commandref_join.pl und contrib/commandref_modular.pl) und eingecheckt.

Ich würde dich (und die anderen) sowieso gerne mehr bei der Doku unterstützen.

Danke fuers Angebot, das freut mich.

[Christoph Morrison]

alles in <ul> eingeschlossen (damit es genauso ausschaut, wie die anderen Module),

Warum eigentlich ul (und ohne li drunter)?

[igami]

Auch wenn das jetzt OT wird:
Ich persönlich tue mich schwer mit der Commandref, da ich keine Ahnung von HTML habe. Ich gucke dann immer nach wie das in den anderen Modulen gelöst wurde.
Im Wiki gibt es ja schon die Guidlines zur Dokumentation. Wäre es nicht sinnvoll diese so zu erweitern, dass man dann für die Standard Abschnitte (Beschreibung, Define, Set, Get, Attribute, Readings, Beispiele) gut formatierte Sektionen hat, die man sich nur noch zusammen Kopieren muss um sie mit Inhalt zu füllen?

Das Aussehen von der deutschen Commandref zu SUNRISE_EL gefällt mir übrigens sehr gut, sodass ich das auch auf meine Module anwenden werde.

[Christoph Morrison]

Ich persönlich tue mich schwer mit der Commandref, da ich keine Ahnung von HTML habe. Ich gucke dann immer nach wie das in den anderen Modulen gelöst wurde.

Du (und jeder andere Maintainer) kann sich gerne an mich wenden wenn er Hilfe bei Dokumentation (und auch Übersetzung) benötigt.

Im Wiki gibt es ja schon die Guidlines zur Dokumentation. Wäre es nicht sinnvoll diese so zu erweitern, dass man dann für die Standard Abschnitte (Beschreibung, Define, Set, Get, Attribute, Readings, Beispiele) gut formatierte Sektionen hat, die man sich nur noch zusammen Kopieren muss um sie mit Inhalt zu füllen?

Gute Idee. Ich werde  gleich mal einen Zugang zum Wiki beantragen und dann einen Draft erstellen.

Das Aussehen von der deutschen Commandref zu SUNRISE_EL gefällt mir übrigens sehr gut, sodass ich das auch auf meine Module anwenden werde.

Danke. Du kannst mich gerne involvieren, wenn du Hilfe brauchst.

[rudolfkoenig]

Warum eigentlich ul (und ohne li drunter)?

Ich will den Text einruecken, damit man beim scrollen das naechste Modul einfacher erfassen kann.
Und dafuer kenne ich nur ul.

Mit deinen vielen Tags ist die Doku zwar schoener formatiert, ich habe nur Angst, dass es manche ueberfordert, und bei der nicht zweckmaessigen Verwendung (z.Bsp. "help Modulname" im Telnet) zu unerwarteten Nebeneffekten fuehrt. Ist aber nur ein Bauchgefuehl, und ich bin dafuer, es zu testen.

Wenn du schon auf diesem Gebiet taetig bist
- mittel/langfristig will ich auf das Format "modular" umsteigen (siehe contrib/commandref_modular.pl bzw. attr global commandref modular), weil commandref inzwischen zu gross ist. Leider funktioniert das noch nicht im standalone mode (d.h. wenn die Seite von http://fhem.de/commandref.html) geladen wird.
- da inzwischen normal ist, telefone fuer alles zu verwenden, sollten wir die Doku auch dafuer optimieren.
- jeder Eintrag sollte einen direkten Link zum Text der anderen Sprache haben (manche Module machen das selbst, das ist doof, da es generisch sein sollte).

Alle Aufgaben sind eigentlich TODO fuer mich, ich wehre mich aber nicht, wenn man mir helfen will.

[Ellert]

...
- mittel/langfristig will ich auf das Format "modular" umsteigen (siehe contrib/commandref_modular.pl bzw. attr global commandref modular), weil commandref inzwischen zu gross ist. Leider funktioniert das noch nicht im standalone mode (d.h. wenn die Seite von http://fhem.de/commandref.html) geladen wird.
...

Ich würde mir wünschen, dass nicht jedes Modul oder jeder Befehl eine Zeile im Inhaltsverzeichnis erhält, das macht die Navigation sehr umständlich (13 Browserseiten)
Könnte die Nutzung des "titel" Attributes eine Lösung sein? Damit könnte die Kurzbeschreibung zu jedem Eintrag bei mouseover angezeigt werden und das Inhaltsverzeichnis wäre trotzdem kompakt. 

[Damian]

Zusätzlich würde ich mir wünschen, wenn es "modular" sein soll, dass ich nach der Auswahl nur die Doku dieses Moduls zu sehen bekomme  inkl. zurück-zum-Menü-Knopf und nicht noch andere Dinge, die mich an dieser Stelle nicht interessieren.

[marvin78]

Dann muss die commandref durchsuchbar werden. Die Browsersuche hilft aktuell sehr, die relevanten Abschnitte zu finden. Mir hilft das sogar deutlich mehr, als ein Inhaltsverzeichnis, welches für mich persönlich fast überflüssig ist.

[Christoph Morrison]

Ich will den Text einruecken, damit man beim scrollen das naechste Modul einfacher erfassen kann.
Und dafuer kenne ich nur ul.

Ich würde einen globalen Style definieren, der - ausschließlich bei Ausgabe auf dem Bildschirm, also nicht beim Druck oder so - section-Blöcke entsprechend ein wenig einrückt und als Container für jeweils ein Modul dient (auf der Einzelseitenausgabe). Ich bin kein Designer, komme eher aus der Strukturierter-Text-im-Verlagswesen-Ecke und möchte auch sicher keine knallbunte CommandRef haben.

Mit deinen vielen Tags ist die Doku zwar schoener formatiert, ich habe nur Angst, dass es manche ueberfordert, und bei der nicht zweckmaessigen Verwendung (z.Bsp. "help Modulname" im Telnet) zu unerwarteten Nebeneffekten fuehrt. Ist aber nur ein Bauchgefuehl, und ich bin dafuer, es zu testen.

Da hast du einen guten Punkt angebracht, den ich ehrlich gesagt gesagt noch gar nicht adäquat bedacht hatte.

- mittel/langfristig will ich auf das Format "modular" umsteigen (siehe contrib/commandref_modular.pl bzw. attr global commandref modular), weil commandref inzwischen zu gross ist. Leider funktioniert das noch nicht im standalone mode (d.h. wenn die Seite von http://fhem.de/commandref.html) geladen wird.

Das hat so seine Nachteile, wie du ja hier im Thread lesen kannst. Mein grober Plan sieht eigentlich vor, POD mehr zu nutzen um z.B. verschiedene Versionen der CommandRef zu erzeugen (Auf einer Seite, jedes Modul auf einer eigenen Seite mit Suchfunktion, etc.), aber auch die Struktur der Ref zu erneuern ohne den Modulmaintainern das Leben schwer zu machen.

- da inzwischen normal ist, telefone fuer alles zu verwenden, sollten wir die Doku auch dafuer optimieren.

Explizit für Telefone würde ich das nicht tun. Ich glaube wir gewinnen aber alle, wenn wir eine zugänglichere Version der CommandRef haben können.

- jeder Eintrag sollte einen direkten Link zum Text der anderen Sprache haben (manche Module machen das selbst, das ist doof, da es generisch sein sollte).

Ja, das ist auf jeden Fall sinnvoll.

Alle Aufgaben sind eigentlich TODO fuer mich, ich wehre mich aber nicht, wenn man mir helfen will.

Ich benutze FHEM nun seit über zwei Jahren sehr intensiv und freue mich mal etwas zurück geben zu können.

[nils_]

- jeder Eintrag sollte einen direkten Link zum Text der anderen Sprache haben (manche Module machen das selbst, das ist doof, da es generisch sein sollte).

gerade was entdeckt:
https://fhem.de/commandref_DE.html#Astro
der link auf die englische version funktioniert in der online cref nicht...


(ich poste auch noch einen hinweis im astro thread!!)

[nils_]

- jeder Eintrag sollte einen direkten Link zum Text der anderen Sprache haben (manche Module machen das selbst, das ist doof, da es generisch sein sollte).

Alle Aufgaben sind eigentlich TODO fuer mich, ich wehre mich aber nicht, wenn man mir helfen will.

ich hab da mal was versucht....
siehe anhang


ob die formatierung passt, weiß ich nicht, hier beim testen fehlen mir glaube ich ein paar hintergründe/css/o.ä. (hatte mir nur die commandref_join.pl runtergeladen und dann darin gebastelt, zum testen noch ein paar *.pm's)

unschön finde dabei, das es über der Überschrift steht. also über dem Modulnamen.
mir ist nicht klar, ob alle module _immer_ ein <h3>-Tag (als Einstiegspunkt) haben. Falls ja, könnte man daran unterscheiden bzw. dann die Links danach generieren. in einer neuen Zeile, oder aber in der gleichen Zeile (in kleiner schrift). letzteres wäre meine bevorzugte variante (persönliche Meinung )


ach so: ich übe noch mit perl, also immer her mit den verbesserungen

btw.: ist das noch der richtige thread dafür??



//edit:
versuch für Sprachlinks nach der Überschrift (auch im anhang!)

[rudolfkoenig]

Danke, habs etwas umformatiert, und die Links in einem div zwecks besserer Styling gepackt.
Dann etwas getestet und eingecheckt.
Wenn bei einem Modul die Links nicht auftauchen, dann fehlt es an <h3>Modulname</h3>, und dann hat man die Ehre es in der Doku zu fixen. Und die Module, die es selbst eingebaut haben, sollten es jetzt natuerlich ausbauen.

[nils_]

Danke, habs etwas umformatiert, und die Links in einem div zwecks besserer Styling gepackt.

dachte mir schon das es ein perl-profi etwas anders zusammenbaut

Wenn bei einem Modul die Links nicht auftauchen, dann fehlt es an <h3>Modulname</h3>, und dann hat man die Ehre es in der Doku zu fixen. Und die Module, die es selbst eingebaut haben, sollten es jetzt natuerlich ausbauen.

evtl. sollte man das mit dem <h3>-Tag noch irgendwo erwähnen (habe auf die schnelle dazu nix gefunden!).
auch das es "am besten" nur für den Modulnamen verwendet wird.

[nils_]

@rudi:
was mir gerade noch aufgefallen ist, ist das die links momentan nur für Module erzeugt werden. (vmtl. die aus dem SubFolder /FHEM)
aber keine Links zB. bei global und den FHEM-Befehlen (zB. define )

//edit:
müsste da eine änderung in commandref_frame.html / commandref_frame_DE.html vorgenommen werden?
wird die auch erzeugt?? oder manuell bearbeitet??

[rudolfkoenig]

Leider waere das eine manuelle Arbeit.