Modul-Dokumentation in commandref oder wiki?

Begonnen von tupol, 18 März 2018, 11:24:23

Vorheriges Thema - Nächstes Thema

Thorsten Pferdekaemper

Zitat von: tupol am 18 März 2018, 13:49:43
Dafür würde ich Syntax-Highlighting für perl und html benötigen. Kann das Dein Editor?
Weiß ich nicht und eigentlich ist mir das auch egal. Ich brauche kein "Syntax-Highlighting". Möglicherweise könnte ich Notepad++ manuell zwischen Perl und HTML umschalten.

Zitat
Das mit der Kurzreferenz finde ich einen guten Kompromiss.
Ich würde mal sagen, dass das sowieso der monentane Konsens ist.

Zitat
Beibt die Frage, was man unter Kurzreferenz versteht? Kannst Du es definieren?
Da hat man natürlich immer ein bisschen Interpretationsspielraum. Für mich heißt das, das alle Attribute, Readings, Sets und Gets aufgeführt sein sollten mit mindestens einem erklärenden Satz.

Zitat
Wie würdest Du die "Kleinigkeit" bzgl. dem commandref-Ungetüm denn lösen?
Das meinte ich gar nicht mit "einer Datei". Die Commandref wird sowieso aus vielen Dateien aufgebaut und wenn Du zur "modularen" Commandref umschaltest, dann siehst Du sie nicht mehr nur als ein großes Monster.
Ich meinte, dass man statt nur einer .pm mehrere Dateien für ein Modul haben könnte. Also z.B. eine .pm für das Coding, eine .en.html für die englische Commandref, eine .de.html für die deutsche Commandref etc.
Auf der anderen Seite ist das auch etwas Geschmacksache und IMHO nicht wirklich wichtig.

Gruß,
   Thorsten
FUIP

tupol

Zitat von: Thorsten Pferdekaemper am 18 März 2018, 16:18:37
Da hat man natürlich immer ein bisschen Interpretationsspielraum. Für mich heißt das, das alle Attribute, Readings, Sets und Gets aufgeführt sein sollten mit mindestens einem erklärenden Satz.
Das ist dann über nicht kurz sondern komplett. Insbesondere bei den Readings weichen da einige Module jetzt schon davon ab.
FHEM 5.5 auf RPi B Rev.2 (mit LCD4Linux, BMP180 und CUL v3 868.35 MHz), FB7490, Fritz!DECT 200, FS20, FHT80TF-2, S300TH, KS300, Homematic, PRESENCE
Modul-Entwickler von: FRITZBOX, statistics, PROPLANTA, OPENWEATHER, JSONMETER, LUXTRONIK2

tupol

Zitat von: Benni am 18 März 2018, 16:05:31
contrib wird nicht per update verteilt.
Damit macht man es dem Anwender aber dann tatsächlich schwer. :(
FHEM 5.5 auf RPi B Rev.2 (mit LCD4Linux, BMP180 und CUL v3 868.35 MHz), FB7490, Fritz!DECT 200, FS20, FHT80TF-2, S300TH, KS300, Homematic, PRESENCE
Modul-Entwickler von: FRITZBOX, statistics, PROPLANTA, OPENWEATHER, JSONMETER, LUXTRONIK2

Thorsten Pferdekaemper

Zitat von: tupol am 18 März 2018, 16:45:40
Das ist dann über nicht kurz sondern komplett.
Klar, so wie beim Linux "man". Es steht im Prinzip alles drin, aber ohne zu viel Blabla. Das ist insbesondere für denjenigen gedacht, der schon weiß, was das Ding macht, aber in Einzelfällen mal kurz nachschauen will.

Zitat
Insbesondere bei den Readings weichen da einige Module jetzt schon davon ab.
Das kann schon sein. Vielleicht ist nicht jeder meiner Meinung. ...oder es gibt Dinge, die sehr unwichtig sind, oder sowieso klar, oder...
Wie gesagt, es gibt da bestimmt einigen Interpretationsspielraum und man wird niemals alles formal vorschreiben können.

Gruß,
   Thorsten
FUIP

helmut

Zitat von: rudolfkoenig am 18 März 2018, 14:09:46
oder (was ich bevorzuge), schreibst die Umlaute in der HTML-Notation (ä Ä &szlig etc), womit dann alle zurechkommen.

Der Meinung bin ich auch. Der Einfachheit halber schreibe ich alle HTML-Dokumente mit dem vi mit Umlauten
hin und wenn ich fertig bin, wandle ich alles mittels eines vi-Makros, definiert in der .vimrc, einfach mit einem
CTRL-H in die HTML-konforme Schreibweise:

function HtmlUmlaute()
  silent %s/ä/\ä/eg
  silent %s/ö/\ö/eg
  silent %s/ü/\ü/eg
  silent %s/Ä/\Ä/eg
  silent %s/Ö/\Ö/eg
  silent %s/Ü/\Ü/eg
  silent %s/ß/\ß/eg
  silent %s/,,/\„/eg
  silent %s/"/\“/eg
  silent %s/–/\–/eg
  silent %s/é/\é/eg
endfunction
map <silent> <C-H> :call HtmlUmlaute()<CR>


Anschliessend pruefe ich die Dateien mit "tidy".
http://www.html-tidy.org/

Speziell zur commandref siehe auch tst-cmdref
https://forum.fhem.de/index.php/topic,84992.msg773003.html#msg773003

Zitat von: Thorsten Pferdekaemper am 18 März 2018, 17:00:41
Wie gesagt, es gibt da bestimmt einigen Interpretationsspielraum und man wird niemals alles formal vorschreiben können.

Die perfekte Doku gibt es auch bei kostenpflichtigen Produkten nicht. Meiner bescheidenen Meinung nach ist
die commandref (plus ergaenzendem WIKI) von fhem schon sehr gut. Sogenannte professionelle Erzeugnisse
sind in aller Regel nicht besser.

Gruss Helmut
Intelligenz ist die Fähigkeit, Arbeit zu vermeiden, aber dafür zu sorgen, daß die Arbeit gemacht wird.
(Linus Torvalds)

tupol

Wau. Das ist ja ein ganz schöner Aufwand, den Du da betreibst und ein gutes Beispiel, dass die beschriebenen Probleme mit HTML nicht nur bei mir vorkommen.
FHEM 5.5 auf RPi B Rev.2 (mit LCD4Linux, BMP180 und CUL v3 868.35 MHz), FB7490, Fritz!DECT 200, FS20, FHT80TF-2, S300TH, KS300, Homematic, PRESENCE
Modul-Entwickler von: FRITZBOX, statistics, PROPLANTA, OPENWEATHER, JSONMETER, LUXTRONIK2

helmut

Im Vergleich zu dem Aufwand der hinter dem Verlauf von der Idee ueber die Programmierung und
den Tests bis zur Fertigstellung eines Moduls und nicht zu vergessen, der Pflege steht, schaetze ich
diesen Teil als eher gering ein.

Wenn ich damit helfen kann, stelle ich mich gerne Dir und auch anderen zur Verfuegung, an
der Form Deiner/ihrer Modul-Doku mitzuarbeiten.

Gruss Helmut
Intelligenz ist die Fähigkeit, Arbeit zu vermeiden, aber dafür zu sorgen, daß die Arbeit gemacht wird.
(Linus Torvalds)