[WIP] reloaded 2020: "Einsteiger-pdf" - Mitwirkende gesucht

[Beta-User]

Hallo zusammen,

2014 ist die letzte Version der "Heimautomatisierung mit fhem" erschienen. Seitdem ist nicht nur Zeit ins Land gegangen, es hat sich auch manches getan in "FHEM-Land"...

Uli Maaß hatte das Projekt bis Version 4 geschultert, eine riesige Leistung, für die ihm auch heute noch mein großer persönlicher Dank gilt - ohne "das pdf" hätte ich mich in FHEM-Land wohl nicht zurechtgefunden.

Zwar kann man zwischenzeitlich auch Literatur zu FHEM kaufen (insbesondere pah's Buch ist sehr zu empfehlen), aber zu einem Community-Projekt gehört jedenfalls nach meinem Geschmack auch eine einführende Doku aus der Community selbst, die die Zusammenhänge wenigstens halbwegs so darstellt, dass man sie als interessierter Einsteiger - ohne allzuviel IT-Hintergrundwissen - verstehen kann (nun ja: hoffentlich... ).

Im nächsten Post hier findet ihr daher ein pdf (und eine E-Book-Fassung) mit dem Versuch, das Thema anzupacken - das ist in weiten Teilen allerdings noch unvollständig. Teilweise ist es einfach noch nicht geschrieben, teilweise muß manches auch "außen vor" bleiben. Aufgrund der Fülle von Optionen, die es in FHEM gibt, muß man m.E. die Themen irgendwie begrenzen, und es liegt in der Natur der Sache, dass dabei manches unter den Tisch fällt, das vielleicht auch noch wichtig oder "nur" wünschenswert gewesen wäre.

Mein Plan ist, das im Lauf des Jahres vollends "irgendwie" zum Abschluß zu bringen, und je mehr ggf. bereit sind, an dem Projekt mitzuwirken, desto "besser" und vollständiger kann es werden. Was man bereits jetzt erkennen können sollte, ist

   
• in etwa das, was an Themen darin zu finden sein soll, (allerdings teils auch für die Zukunft nur kurz angerissen bzw. als Stichwort zum "woanders weiterlesen");
• die "Tonlage", in der ich das gerne gestalten will und
• der "Erwartungslevel" an das "Publikum", was die Übertragung von Beispielen auf die eigene Installation usw. angeht.

Wer mitwirken will, ist herzlich willkommen! Es sollte aber folgendes klar sein:

   
• Es soll in absehbarer Zeit auch "fertig" werden. Das bedeutet, dass notfalls jemand entscheiden muß, wie und was gemacht wird, was reingenommen wird, was nicht usw, usf.. Bis auf weiteres bin dieser "jemand" ich...
• Das Ergebnis gehört der Community!

Die files liegen heute schon auf dem Server des FHEM e.V.. Ich behalte mir vor, die zu eigenen Zwecken zu nutzen (v.a. die Teile, die ich am Ende selbst von A-Z machen mußte!), und jeder andere darf das - ganz im Sinne der GPL - auch tun, (nicht nur zitateweises) Kopieren zu kommerziellen Zwecken ist jedoch ausdrücklich nicht erlaubt.
Sollte ich irgendwann keine Lust mehr haben, den "jemand" in obigem Sinn zu machen, oder das aus anderen Gründen nicht mehr übernehmen können, kann der Vereinsvorstand jemand anderes benennen. Es würde mich in diesem Fall freuen, wenn es im begonnen Sinne weitergeführt wird, aber eine Auflage oder Bedingung ist das nicht.

Vorab jedenfalls mal: Viel Spaß beim Lesen!

Gruß,

Beta-User

[Beta-User]

In diesem Post findet ihr jeweils die aktuellen Fassungen.

Plan wäre, die ca. alle 1-2 Wochen (je nach Fortschritt) zu erneuern.

Statistic:
Downloads ca.:

pdf: 36
epub: 5
zip: 0

[Beta-User]

Das ganze ist ein größeres Projekt - leider habe ich aber keinen Plan, wie man sowas am besten organisiert... An der Stelle also erst mal ein paar Hintergrundinfos zu den verwendeten Tools und zu dem, was eigentlich rauskommen soll:

   
• Ich bin ein "analoger" Mensch, dem es hilft, wenn er ein "Handbuch" in Papier neben die Tastatur legen kann: Da kann man reinkritzeln, Zettel reinkleben, Ecken wegknicken und notfalls das Vesperbrot darauf deponieren... Ergo: Es muß eine druckbare Version geben, wichtigstes Zielformat ist damit "pdf". Dass es ein pdf sein soll, in dem (auch interne) Links in der elektronischen Fassung funktionieren, versteht sich von selbst...
• "eigentlich" wäre das auch gut im Wiki aufgehoben gewesen, aber: Es ist ziemlich steinig, aus mehreren Wiki-Artikeln ein hübsches pdf zu generieren (falls jetzt jemand schnell eine Suchmaschine anwerfen sollte, um dann auf welche Tools auch immer hinzuweisen: ja, die gibt es, aber man muß die auch bedienen können und das Ergebnis sollte "gut" sein; was ich bisher gesehen habe, hat mich nicht wirklich überzeugt, und bis auf weiteres ist mein Lernbedarf an derartigen Tools gedeckt... Will sagen: Wenn, dann bitte "mundgerchte" Alternativ-Vorschläge, die getestet sind! (PS: Das ist ausdrücklich keine Kritik an denen, die bis hierher Vorschläge und Hinweise gegeben haben!)).
• Kleinster gemeinsamer Nenner ist - jedenfalls nach bisherigem Stand der Erkenntnisse - "Markdown". Das ist sehr nah an dem, was Wiki-Autoren kennen, man hat z.B. mit Okular oder der Markdown-Viewer Extension für notepad++ bzw. Chrome auf allen Systemen Optionen beim Schreiben zu sehen, wie es so in etwa ausschaut, und - vor allem - man kann Markdown-Files recht einfach in - im Prinzip - beliebige Zielformate konvertieren. Neben der E-Book-Fassung (epub) sollte es also auch möglich sein, irgendwann eine Wiki-Fassung daraus zu generieren.

Im Moment gibt es für (fast) jedes Kapitel eine eigene .md-File.
Das Tool, über das - jedenfalls im Moment - die ganzen Umwandlungen laufen, heißt "pandoc", und mit den richtigen "tweaks" scheint die einzige ernsthafte Einschränkung die zu sein, dass man nicht einfach Bilder nach links oder rechts positionieren kann und den Text drumrum brechen (Falls jemand das in seinem Browser/Viewer anschaut, html-code verwendet und das nicht versteht: Ja, man kann Markdown generieren, der dann insbesondere in einem Browser das gewünschte Ergebnis liefert, aber man kann das afaik nicht in der Form in ein pdf drucken, weil insbesondere "class" von pandoc unterdrückt wird... Vermutlich kommt da auch manches Problemchen mit den Bildern in der E-Book-Fassung her.).

   
• Wiki: Wäre also dann mittelfristig auch ein wichtiges Zielformat.

Wer mitwirken will, darf sich bitte einfach melden, und wir finden dann schon einen Weg... Wie genau, wird wohl auch davon abhängen, wie viele es sind und wer was macht, im einfachsten Fall läuft das als Textfile-Anhang über das Forum.

Aber auch hier gilt: zielführende Vorschläge, die einfach und mit der bestehenden Infrastruktur umzusetzen sind: Gerne!




Hier noch ein kurzer Auszug, wie das im Markdown-Quelltext aussieht:

Code Auswählen Erweitern

# FHEM-Grundlagen

## Installation
Die Installation hatten wir ja eigentlich vorher schon gemacht: Es gibt entweder irgendwo einen Perl-Interpreter auf Deinem Windows-PC, oder Du hast ein Linux-System, auf dem die entpackten FHEM-Dateien liegen, oder einen Debian-basierten Server (ohne GUI!), auf den Du mit *ssh* zugreifen kannst, und auf dem Du entsprechend des *easy way* nach [https://debian.fhem.de](https://debian.fhem.de) FHEM installiert hast. 

## Systemüberblick
Schauen wir uns also FHEM mal gemeinsam an. Da es in einer leeren Installation wenig zu sehen gibt, nehmen wir dafür zunächst einmal die Demoversion. 
Um diese zu starten, muss - sofern Du FHEM mit dem Debian-Paket installiert hast - FHEM zunächst einmal beendet werden. Dazu tippst Du auf der Linux-Konsole `sudo service fhem stop` ein und gibst das Kommando frei, falls Du nach einem Passwort gefragt wirst. 
 
Dann wechselst Du in das Verzeichnis, in dem die Datei *fhem.pl* liegt. Nach einer Debian-Installation ist das */opt/fhem*, mit `cd /opt/fhem` kommst Du auf der Linux-Konsole direkt dort hin. Dann startest Du FHEM mit `perl fhem.pl fhem.cfg.demo`. 
 
Auf einem Windows-PC, bei dem FHEM im Verzeichnis `E:\fhem` liegt und der Perl-Interpreter in einem Unterverzeichnis `E:\fhem\perl\perl\bin\`, kann man - wieder aus dem FHEM-Verzeichnis `E:\fhem` heraus - FHEM so starten: `perl\perl\bin\perl fhem.pl fhem.cfg.demo` 

![FHEM-Start von der Windows-Kommandozeile][demostart_win] 

[Beta-User]

Diesen Post soll jeweils zu entnehmen sein, wer grade an was dran ist und (eventuell) für welche Themen grade jemand gesucht wird...

1. "pandoc" (oder Alternativen)

   
• md to pdf und Bilder:
  Wenn jemand damit wirklich Erfahrung hat: Interesse...!
• dto. für die Generierung der Wiki-Seiten - relative Links usw. passend setzen

2. E-Book-Fassungen
Das epub ist bisher nur ein Nebenprodukt, das sich recht einfach generieren läßt. Eventuell wird es aber "besser", wenn jemand den Quelltext daraufhin optimiert, der Erfahrung hat. V.a. die Darstellung/Positionierung der Bilder ist da ein Thema...

3. Ganz viele inhaltliche Themen:
Obwohl ich schon einiges gesehen habe, nutze ich insgesamt vieles doch nicht - angefangen bei Sprachsteuerung... Vor allem in diesen Teilen wäre Zuarbeit wirklich sinnvoll.

4. Homematic (CUL_HM)- Anhang des heutigen "Einsteiger-pdfs":
Ein sehr wertvolles Dokument, das aber mMn. besser je als eigenständiges Dokument in einem angepinnten Thread im Homematic-Bereich sowie (mittelfristig) getrennt im Wiki zu finden sein sollte.

5. "Artwork"

   
• Eine hübsche Titelseite wäre cool... (Und: Wie bindet man die jeweils am einfachsten ein?)
• Wir werden das eine oder andere Schaubild brauchen, z.B. für direkte vs. indirekte Verbindungen zwischen Geräten
• meine Screenshots sind so nebenbei entstanden, und "im Prinzip" ok, aber eben in vielen Details verbesserungsfähig. Schön wäre es, wenn sich da jemand um ein noch einheitlicheres Layout bemühen könnte, ggf. einheitliche Hinweispfeile auf das grade besprochene Element einfügen usw. usf...

Ihr seht also: viel zu tun...

[Schotty]

Dann hier nochmal 'offiziell' & für alle:
Ich habe mit den md-Dateien und einer anderen Konverterlösung rumgespielt, die ich auch für mein eigenes Handbuch (s. Signatur) nutze.
Das epub habe ich mittels eines Onlinekonverters erstellen lassen (btw: Kap02 wird mir bei deinem epub nicht angezeigt @Beta-User).
Sieht imho insgesamt schon etwas besser aus, allerdings sind teilweise nicht-funktionierende Links innerhalb des Textes noch ein Problem. Ich hatte diesbzgl in eigenem Interesse schonmal im Forum angefragt (https://forum.fhem.de/index.php/topic,106850.0.html), leider hatte niemand geantwortet. Aber vielleicht ist das FHEM-Einsteiger-PDF ja eine 'bessere' Motivation

Eingesetzte Konverter:
- md -> pdf: https://github.com/yakivmospan/github-wikito-converter
- das daraus erzeugte html -> epub: https://ebook.online-convert.com/de/umwandeln-in-epub

Wiki: Wäre also dann mittelfristig auch ein wichtiges Zielformat.

Just my 2ct:
Wie an anderer Stelle schonmal erwähnt wäre es meiner Meinung nach sinnvoll, die Wiki-Erstellung bzw Konvertierungsmöglichkeiten von md->mediawiki bereits jetzt am Anfang zu testen und idealerweise eine akzeptable Lösung zu finden. Wenn später erstmal zig Seiten Text formatiert vorliegen und man dann feststellt, dass gewisse Änderungen an der Formatierung oder md-Syntax nötig wären, um ein besseres Ergebnis zu erzielen, ist der Arbeitsaufwand sicherlich um Einiges höher. Dazu wäre es m.A.n. jedoch bereits jetzt schon notwendig, einen entspr Onlinezugang wie beim FHEM-Wiki zu schaffen, so dass die (Test-)Ergebnisse da dann auch begutachtet werden können.
Alternative:
Die 'Onlineversion' nicht als FHEM-Wiki, sondern rein mit den md-files als GitHub-Pages umsetzen und dann einen entspr. Link (bspw "epdf.fhem.de" oder sowas) setzen. So könnte man sich die ganze Konvertiererei nach mediawiki sparen und mit einer entspr Vorlage für die GitHub-Pages könnte man sicherlich auch einen gewissen 'Wiki-Look' erreichen, wenn's denn so sein soll.

Bzgl des Inhalts: Mal ganz doof gefragt - ist Ulli Maaß noch erreichbar/aktiv? Vielleicht könntest du gewisse Inhalte von ihm übernehmen und/oder anpassen? Dann müsste nicht alles komplett neu geschrieben werden..?

[Beta-User]

Hi Schotty,

vorab nochmal auch an dieser Stelle für die vielen Infos rund um md!
Ohne das "Muster" von deinem Handbuch wäre ich aufgeschmissen gewesen bzw. würde mich heute noch darüber wundern, wie seltsam sich LibreOffice gelegentlich verhält, wenn man versucht, da was mit vielen Bildern zu machen... (Man bekommt andere schöne Spielereien damit hin, aber das ist ein ganz anderes Thema.)

Vorab ein paar Worte noch zu Uli Maaß: Ich hatte ihn vor längerer Zeit mal angeschrieben, aber leider keine Antwort erhalten. Dem Hörensagen nach ging es auch anderen so, die auch früher schon versucht hatten, ihn zu kontaktieren. Seine letzte Anmeldung im Forum war Ende 2018, von daher hoffe ich, dass es ihm gut geht und er lediglich kein Interesse an FHEM mehr hat, aber sonst nichts schlimmeres ist.

Er hatte nicht nur "das pdf" erstellt, sondern auch die "ersten Schritte", und war bei beidem sehr darauf bedacht, dass keiner ohne seine Zustimmung etwas daran ändert bzw. den Quelltext für das pdf scheint er irgendwo privat abgespeichert zu haben. Ich werde das respektieren, und letztlich war es vermutlich gut, sich von der Vorlage ziemlich zu lösen, weil "mein pdf" erst mal viele Dinge "drumrum" behandelt, die "damals" noch gar keine Rolle gespielt hatten oder jedenfalls nicht im Fokus waren. Es wird natürlich trotzdem so sein, dass Gegenstand der Darstellung FHEM ist, und von daher wird es auch gewisse Überschneidungen geben, das sind aber nach meiner bisherigen Erfahrung tatsächlich eher kleinere Anteile.

Wie dem auch sei, diese Erfahrung, von neuem anfangen zu müssen, war mit einer der Gründe für die sehr klaren Statements im ersten Post: Es ist wichtig, dass jemand entscheidet, was wie am Ende dargestellt wird (sonst kann man "endlos" auch über "Kleinigkeiten" diskutieren), von daher kann ich Uli sehr gut verstehen, dass er "seine" Dokumente auch teils hart verteidigt hat (und eventuell genau deswegen auch nicht mehr hier aktiv ist?), es ist aber genauso wichtig, dass diese Dinge weiterleben können, selbst wenn der "jemand" die Verantwortung nicht mehr wahrnimmt - warum auch immer.
Und genau deswegen ist der Quelltext
- auf dem Server des Betreibers, der auch sonst für alles die Infrastruktur bereitstellt (=FHEM e.V.)
- einfach gehalten (relativ... Aber dass man schnell auch mit anderen Tools brauchbare Ergebnisse mit einem anderen - auch schönen Look! - hinbekommt, wenn man "nur" die files mit der wenigen Formatierung darin hat, hast du ja schön gezeigt!).

Welches Toolset am Ende genutzt wird, ist mir im Prinzip egal, ich will nur weder externe Infrastruktur verwenden, noch Kapazität von den Fachleuten, die sich damit auskennen (oder eben auch (noch) nicht...) mehr als nötig binden, die an anderer Stelle besser eingesetzt werden kann. Kurz: Wenn jemand, der sich mit der hier vorhandenen Serverinfrastruktur auskennt, einen Viewer einrichten kann und will, der die Files direkt rendert und die Verlinkung ins Wiki erlaubt, soll mir das genauso recht sein, wie wenn das ganze von svn in ein git käme oder ich gelegentlich die aktuelle Fassung nachbearbeiten und ins Wiki transferieren muß.

Dass jede Lösung immer irgendwelche Nachteile hat, ist klar, im Moment liegt mein persönlicher Schwerpunkt eher wieder beim "Texten".

Den Transfer nach Wikimedia hatte ich kurz angetestet, was da rauskam, war grundsätzlich ok, auch wenn viele features aus der Mediawiki-Sprache nicht funktionieren und Nacharbeit erforderlich ist. Mal schauen, was man da ggf. automatisieren kann, oft ist es schlicht so, dass man den richtigen "Knopf" finden muß...

Das mit Kap02 schaue ich mir noch an, auf dem Laptop scheint das zu funktionieren, vielleicht hatte ich versehentlich eine alte Fassung erwischt?
Das mit den Dokument-Übergreifenden relativen Links kann ich leider auch nicht lösen, bei der pandoc-Variante klappt das deswegen, weil das afaik erst alles in ein "Groß-Dokument" konvertiert, und dann erst rendert - selbst der scheinbar kapputte interne Link mit den Umlauten funktioniert, sieht aber halt im pdf nicht schön aus...

[CoolTux]

Wie genau ist das Quellfomat für das PDF und das epub?
Gibt es ein Dokument zum bearbeiten mit Änderungshistorie? Ich würde da OpenDocumentFormat vorschlagen. Würde das dann mit LibreOffice bearbeiten und dann kann man auch Änderungsverläufe sehen.


Grüße

[Beta-User]

Es ist Markdown, ein Beispiel, wie das konkret ausschaut, ist in Beitrag #3 zu finden.

EDIT: was da ggf. "seltsam aussieht ist ein indirekter Link auf ein Bild:

Code Auswählen Erweitern

![FHEM-Start von der Windows-Kommandozeile][demostart_win] 
@CoolTux, sorry für den Aufwand im Vorfeld, aber odt wäre m.E. ein Rücksschritt.
In dem odt-Format hatte ich angefangen, und da gab es ein paar schöne Effekte, die man damit erzeugen konnte. ABER: Das Teil ist dann gewachsen, und dann waren die Ergebnisse teils auch "nicht gut" (eigentlich: Schei..e), die ich lokal hatte, nachdem da die ersten paar Bilder drin  waren, und Übertragbarkeit nach Wiki stelle ich mir besser erst gar nicht vor. Es gibt sicher Möglichkeiten, das alles irgendwie zu lösen, aber im Moment fehlt mir dazu die Lust, mich in sowas wie Master-Dokumente oä. einzudenken; Markdown hat sich nach meinen bisherigen Erfahrungen als guter Kompromiß erwiesen.
Es wäre vermutlich sinnvoller, wenn dann weiter über die Frage des End-Renderings zu sprechen. Da ist "mit einer Prise Latex" vermutlich ganz viel möglich, weil das mit Variablen arbeiten kann und die Variablen für unterschiedliche Zielformate auch unterschiedlich auflösen.

Zur Technik an sich:
Im Moment liegen die files auf einem separaten svn-repo, die Änderungen sind also transparent, es gibt jedenfalls derzeit nur kein trac oä., auf dem man sich das anzeigen lassen könnte.

Wenn ich mir was wünschen darf, wäre das neben einem Mitwirkendem mit etwas Latex-Expertise eher ein Vorschlagssystem, bei dem Änderungsvorschläge ähnlich angezeigt werden wie wenn man im Wiki zwei Versionen vergleicht und das dann bearbeiten oder auch 1:1 annehmen kann. Das würde es allen Mitwirkenden (so es einfach zu bedienen ist...!) erleichtern. Keiner braucht sich mit riesen-Dokumenten rumschlagen, wenn es nur um Typos geht und ich sehe bei Änderungen, was eigentlich vorgeschlagen ist...

Markdown an sich ist einfach zu lernen, und m.E. für alle auch viel einfacher, als das ggf. unbekannte LibreOffice (ich kenne und schätze das). Je nachdem werde ich wohl eher hergehen und lokale diffs erstellen und die dann einarbeiten, wenn mir jemand was schickt... Und wie gezeigt: Das geht ohne weiteres auch hier im Forum. Entweder in Code-Tags packen, oder als txt-file in den Anhang und gut ist...

[CoolTux]

Es ist Markdown, ein Beispiel, wie das konkret ausschaut, ist in Beitrag #3 zu finden.

EDIT: was da ggf. "seltsam aussieht ist ein indirekter Link auf ein Bild:

Code Auswählen Erweitern

![FHEM-Start von der Windows-Kommandozeile][demostart_win] 
@CoolTux, sorry für den Aufwand im Vorfeld, aber odt wäre m.E. ein Rücksschritt.
In dem odt-Format hatte ich angefangen, und da gab es ein paar schöne Effekte, die man damit erzeugen konnte. ABER: Das Teil ist dann gewachsen, und dann waren die Ergebnisse teils auch "nicht gut" (eigentlich: Schei..e), die ich lokal hatte, nachdem da die ersten paar Bilder drin  waren, und Übertragbarkeit nach Wiki stelle ich mir besser erst gar nicht vor. Es gibt sicher Möglichkeiten, das alles irgendwie zu lösen, aber im Moment fehlt mir dazu die Lust, mich in sowas wie Master-Dokumente oä. einzudenken; Markdown hat sich nach meinen bisherigen Erfahrungen als guter Kompromiß erwiesen.
Es wäre vermutlich sinnvoller, wenn dann weiter über die Frage des End-Renderings zu sprechen. Da ist "mit einer Prise Latex" vermutlich ganz viel möglich, weil das mit Variablen arbeiten kann und die Variablen für unterschiedliche Zielformate auch unterschiedlich auflösen.

Zur Technik an sich:
Im Moment liegen die files auf einem separaten svn-repo, die Änderungen sind also transparent, es gibt jedenfalls derzeit nur kein trac oä., auf dem man sich das anzeigen lassen könnte.

Wenn ich mir was wünschen darf, wäre das neben einem Mitwirkendem mit etwas Latex-Expertise eher ein Vorschlagssystem, bei dem Änderungsvorschläge ähnlich angezeigt werden wie wenn man im Wiki zwei Versionen vergleicht und das dann bearbeiten oder auch 1:1 annehmen kann. Das würde es allen Mitwirkenden (so es einfach zu bedienen ist...!) erleichtern. Keiner braucht sich mit riesen-Dokumenten rumschlagen, wenn es nur um Typos geht und ich sehe bei Änderungen, was eigentlich vorgeschlagen ist...

Markdown an sich ist einfach zu lernen, und m.E. für alle auch viel einfacher, als das ggf. unbekannte LibreOffice (ich kenne und schätze das). Je nachdem werde ich wohl eher hergehen und lokale diffs erstellen und die dann einarbeiten, wenn mir jemand was schickt... Und wie gezeigt: Das geht ohne weiteres auch hier im Forum. Entweder in Code-Tags packen, oder als txt-file in den Anhang und gut ist...

Ok das ist doch auch eine gute Sache. Das beste daran ist das Du das Teil dann auch bei Bedarf über die FHEM e.V. Cloud weiter entwickeln kannst. Da müsste ich erstmal nichts weiter umstellen oder Office konfigurieren.
Also melde Dich einfach wenn Du das in die Cloud schupsen willst 

[Prof. Dr. Peter Henning]

Ich habe ja schon viele Seiten aus dem FHEM-Buch frei zur Verfügung gestellt, bin also gerne bereit, das Eine oder Andere beizutragen.

LG

pah

[xenos1984]

Zum Thema "Vorschlagssystem": Wie wäre es, die Markdown-Quellen z.B. auf GitHub o.ä. unterzubringen? Dann kann jemand, der dazu beitragen möchte, einen Pull-Request erstellen.

Zum Thema Markdown / LaTeX: Ich bin mit beiden recht versiert (benutze bei der Arbeit durchgehend LaTeX und für Notizen Markdown), und steuere auch gerne etwas bei, wenn ich kann. Zumindest so weit ich FHEM bisher beherrsche.

Ein Kollege von mir schwört auf Typora als Markdown Editor. Damit kann man sowohl den Quelltext bearbeiten, als auch in einen "WYSIWYG" Modus wechseln.

Von der Struktur her sieht es sehr gut aus. Eine Frage zum Inhalt: Soll DOIF auch behandelt werden, oder ist das schon zu fortgeschritten für einen Einsteiger-Leitfaden?

[CoolTux]

GitHub finde ich gut.
GitHub.com/fhem

Da könnte man ein Repo machen.

[Beta-User]

@all:

Danke schon mal für die viele Resonanz! 
Klingt danach, als könnte das was werden (auch wenn mir beim durchsehen dann auch schon wieder ein paar "Holprigkeiten" aufgefallen sind, und das ganze noch einiges Feintuning braucht ).

Ungefähr der Reihe nach:

Zum Thema "Vorschlagssystem": Wie wäre es, die Markdown-Quellen z.B. auf GitHub o.ä. unterzubringen? Dann kann jemand, der dazu beitragen möchte, einen Pull-Request erstellen.

Hatte ja geschrieben: Wünschenswert wäre es eventuell, das von der Form her in der Weise zu organisieren - aber:
- ich habe weder Erfahrung mit dem Akzeptieren von Vorschlägen in Git/Github und will mich eigentlich auch nicht auch noch dort einarbeiten;
- es ist m.E. zwingend, dass die files auf FHEM-eigenen Servern verbleiben, für eine Infrastruktur außerhalb sehe ich jedenfalls im Moment keine "schlagenden Gründe".

@CoolTux:
Bitte fangen wir diese Diskussion daher nicht hier und an dieser Stelle wieder an... Hier geht es um simplen Text, etwas css/tex/yaml und ein paar Screenshots, nicht um komplexen Perl-Code, bitte nicht vergessen!

Ganz grundsätzlich: Ich habe kein Problem mit einem lesenden Zugriff von wem auch immer. Ebensowenig mit diffs (-u, falls jemand es genauer wissen will) oder ganzen Neufassungen, wenn die hier oder anderswo eingehen, und ich werde mich auch bemühen, die abzuarbeiten oder Rückmeldung zu geben, wenn ich was nicht oder anders will. Wenn jemand Lust hat, das mit dem allg. Lesezugriff auf den FHEM-Servern möglich zu machen: gerne!
Aber es sollte für alle Beteiligten (einschl. derjenigen, die das dann von der infrastrukturellen Seite schlicht machen müßten!) mit "simple Tools" zu erschlagen sein...

Zum Thema Markdown / LaTeX: Ich bin mit beiden recht versiert (benutze bei der Arbeit durchgehend LaTeX und für Notizen Markdown), und steuere auch gerne etwas bei, wenn ich kann. Zumindest so weit ich FHEM bisher beherrsche.

Es würde mich sehr freuen, wenn du dir den Quelltext mal mit deinen "kundigen Augen" ansehen könntest und wir das eine oder andere ggf. auch mal bilateral besprechen könnten. Imo ist es von Vorteil, dass du nicht zu den "alten Hasen" gehörst, was FHEM-Nutzung angeht, du liest das noch mit ganz anderen Augen - ich bin schon betriebsblind, und gerade die "wieso"... Fragen bringen uns vermutlich bei dem Thema weiter...
Fachliche Korrektur folgt dann schon von meiner (soweit ich das selbst überblicke, ich weiß nämlich auch bei weitem nicht alles) oder von anderer Seite.

Ein Kollege von mir schwört auf Typora als Markdown Editor. Damit kann man sowohl den Quelltext bearbeiten, als auch in einen "WYSIWYG" Modus wechseln.

Schaue ich mir an, Danke. Aufgrund meiner bisherigen Wiki-Aktivitäten kann ich zwischenzeitlich schon recht gut abschätzen, wie das in etwa aussieht. (ich bin mit WordPerfect groß geworden: Tippen in der DOS-Version, dann Win 3.0 hochfahren, dort ansehen und ab auf den Nadeldrucker... Leidensfähig halt )

Von der Struktur her sieht es sehr gut aus. Eine Frage zum Inhalt: Soll DOIF auch behandelt werden, oder ist das schon zu fortgeschritten für einen Einsteiger-Leitfaden?

Danke für das Lob!
DOIF "kann" ich nicht, ich werde das daher auch nicht vertieft behandeln. Falls jemand was beisteuert, das vom Stil her dazupaßt und substantielle Erkenntnisse zur Funktionsweise des Moduls liefert, werde ich mir das wohlwollend ansehen, bin aber kritisch:
Die Syntax ist einfach eine ganz andere als sonst sehr häufig erforderlich, und in der einfachen Version bringt es kaum einen Vorteil gg. at bzw. notify (außer, dass man für denselben Effekt teilweise viel mehr Attribute braucht, über deren richtigen Einsatz sich teils die Experten nicht einig zu sein scheinen...), und komplexe Dinge sprengen sehr schnell den Rahmen.
Ich plane übrigens z.B. auch nicht, Value() oder "set magic" großen Raum zu geben - man muß das (wie DOIF) erwähnen, weil man es oft findet, aber für meine Einführung gilt im Prinzip "FHEM ist ein Perl Server...", und es macht imo wenig Sinn, auf die Frage "Muß ich mit Perl Programmieren lernen?" ausweichend zu antworten: Im Ergebnis programmiert man mit jedem "define" einen Teil seiner "Haus-firmware", und von daher finde ich persönlich, man sollte sich zuerst mehr mit den Basics beschäftigen und erst später mit "Abkürzungen" und "Vereinfachungen".

Just my2ct.

Ich habe ja schon viele Seiten aus dem FHEM-Buch frei zur Verfügung gestellt, bin also gerne bereit, das Eine oder Andere beizutragen.

Vielen lieben Dank! Mal schauen, wie und wo sich das dann ergibt.

[xenos1984]

- ich habe weder Erfahrung mit dem Akzeptieren von Vorschlägen in Git/Github und will mich eigentlich auch nicht auch noch dort einarbeiten;
- es ist m.E. zwingend, dass die files auf FHEM-eigenen Servern verbleiben, für eine Infrastruktur außerhalb sehe ich jedenfalls im Moment keine "schlagenden Gründe".

Ich persönlich habe mit GitHub durchweg positive Erfahrungen, zumal man viel automatisieren kann (z.B. das PDF oder andere Formate nach jedem Update automatisch erstellen), und auch Pull-Requests sind sehr einfach. Aber wenn sich eine ähnlich nützliche Funktionalität auf FHEM eigener Infrastruktur auch einrichten lässt - sicher, warum nicht.

Es würde mich sehr freuen, wenn du dir den Quelltext mal mit deinen "kundigen Augen" ansehen könntest und wir das eine oder andere ggf. auch mal bilateral besprechen könnten.

Sehr gerne - wenn ich denn wüsste, wo ich den finde Du hattest etwas vom FHEM Server geschrieben, aber ich muss zugeben, dass ich daraus nicht hinreichend schlau geworden bin, um die Dateien zu finden.

Schaue ich mir an, Danke. Aufgrund meiner bisherigen Wiki-Aktivitäten kann ich zwischenzeitlich schon recht gut abschätzen, wie das in etwa aussieht. (ich bin mit WordPerfect groß geworden: Tippen in der DOS-Version, dann Win 3.0 hochfahren, dort ansehen und ab auf den Nadeldrucker... Leidensfähig halt )

Ich bin auch eher für Quelltext zu haben. Mein bevorzugter Editor ist Vim, und für Markdown gibt es dafür ein Pandoc Plugin,

DOIF "kann" ich nicht, ich werde das daher auch nicht vertieft behandeln. Falls jemand was beisteuert, das vom Stil her dazupaßt und substantielle Erkenntnisse zur Funktionsweise des Moduls liefert, werde ich mir das wohlwollend ansehen, bin aber kritisch:
Die Syntax ist einfach eine ganz andere als sonst sehr häufig erforderlich, und in der einfachen Version bringt es kaum einen Vorteil gg. at bzw. notify (außer, dass man für denselben Effekt teilweise viel mehr Attribute braucht, über deren richtigen Einsatz sich teils die Experten nicht einig zu sein scheinen...), und komplexe Dinge sprengen sehr schnell den Rahmen.

Ich kann es versuchen, da ich manche Dinge mit DOIF recht komfortabel gelöst finde und es für manches auch einsetze (z.B. für verzögertes Ausschalten, eine einfache State Machine etc.), aber eben wirklich auf sehr einfachem Niveau.

[CoolTux]

Ich persönlich habe mit GitHub durchweg positive Erfahrungen, zumal man viel automatisieren kann (z.B. das PDF oder andere Formate nach jedem Update automatisch erstellen), und auch Pull-Requests sind sehr einfach. Aber wenn sich eine ähnlich nützliche Funktionalität auf FHEM eigener Infrastruktur auch einrichten lässt - sicher, warum nicht.

Leider ist mir da nichts dergleichen bekannt. Gerade pull request empfinde ich als große Erleichterung genau für so ein Projekt wie die Dokumentation.