Tags in der Doku

[Dr. Boris Neubert]

bin auch dafür.

Schlussendlich aber Rudis Kompetenzbereich, und der hat nö gesagt. Muss man akzeptieren, geht ja auch so.

Tabellen mit Rahmen sind für mich leserlicher als Tabellen ohne Rahmen. Ich habe nichts dagegen, die HTML-Attribute zu entfernen, wenn wir die Style-Sheets so aufbohren, dass Tabellen Rahmen haben.

Gravierender finde ich, dass wir mal angefangen haben <ul> missbräuchlich für Einrückungen zu verwenden. Und dass jeder Autor seinen eigenen Stil für die Darstellung wählt. Ich befürworte daher die Vorgabe von Styleguides und/oder die Nutzung von <div class="get"> oder so für Markup. Oder wir stellen die Doku gleich auf xml um 

[betateilchen]

Bitte zeige mir den Beitrag. Ich habe Tomaten auf den Augen.

Beispielsweise hier: http://forum.fhem.de/index.php/topic,47035.msg387832.html#msg387832

(es gibt übrigens noch mehr neue pre-commit hooks, beispielsweise Zeilenlänge in CHANGED oder pm-Dateien ohne $Id)

[Dr. Boris Neubert]

Also keine Ankündigung des Hooks - der Beitrag zeigt nur das Symptom und auch nur, wenn man ihn liest, was ich nicht getan habe.

Die Ankündigung zu den Zeichen findet sich in diesem Thema. Die Ankündigung zu den Tags nicht.

Ich möchte so nicht arbeiten.

[betateilchen]

Boris, schau doch mal genau nach: Rudi hat am 01.01. hier im Thread eindeutig kundgetan, dass er die Attribute in Tabellenelementen nicht mehr zulässt:

Sonst fangen die Leute mit "style='color:light-blue;font-size:48px'" und Vergleichbares an. Das habe ich fuer ul vor (gefuehlt) 2 Jahren einmal schon unterbunden, jetzt folgte nur table & co, da ich damals nicht auf die Idee kam, das man table in der Doku verwenden koennte.

[Dr. Boris Neubert]

Hallo,

das habe ich so gelesen, dass er es nicht wünscht, und commandref_join.pl daher meckern lässt. Dass das Gemeckere ein Einchecken verhindert, kann ich daraus nicht ablesen.

Wie sieht jetzt eine Konsenslösung für das Markup aus?

Viele Grüße
Boris

[betateilchen]

Auf welche Weise er das unterbindet, ist doch Rudis Sache.

Wie sieht jetzt eine Konsenslösung für das Markup aus?

Für mich unmissverständlich von Rudi kommuniziert: Keine Attribute in html tags.

[Dr. Boris Neubert]

Das ist eine Lösung aber keine Konsenslösung.

Wo hat man denn schon mal davon gehört, dass eine Dokumentation nur Tabellen ohne Rahmen enthalten darf?

Die saubere Lösung wurde ja schon vorgeschlagen: Styleguide und CSS-Klassen, oder gleich XML zur Trennung von Content und Darstellung. Mit XLST kommt dann jedes gewünschte Format dabei raus, HTML, Plaintext, RTF...

[betateilchen]

Das ist eine Lösung aber keine Konsenslösung.

Das ist eine königliche Entscheidung. Eine Monarchie ist nunmal keine Demokratie 

[justme1968]

ich denke rudi würde jede der vorgeschlagenen alternativen gerne als patch entgegennehmen .

aber im ernst: die meldungen ohne aussicht auf besserung sind wirklich unbefriedigend. da habe ich lieber deine doku bei der nicht alles identisch formatiert ist.

es wäre besser gewesen das eincheck verbot zu aktivieren und commandref join beim update erst nach einer weile zu verschärfen.

[rudolfkoenig]

Meiner Ansicht nach haben Tabellen in dem commandref nichts zu suchen, genauso wie Farbangaben und Buchstabengroessen. Ich moechte keinen Wettbewerb, wer seine Doku am schoensten bauen kann, sondern was Einheitliches, was auf vielen Frontends angezeigt werden kann.

Wenn ich mich nicht irre, macht es wenig Sinn CSS Klassen zuzulassen, weil dann alle Module angepasst werden muessen, und solange das nicht erfolgt, ist die Doku unleserlich. Wenn das nicht der Fall sein sollte, dann bin ich offen.

Der Haken mit XML+XSLT ist, dass es viel Arbeit bei der Umstellung bedeutet, und vielen Anfaengern nicht zumutbar ist. Weiterhin erfordert es eine zentrale Generierung der commandref.html (wovon ich weg will) oder eine aufwendigere Client-Installation wg. XSLT.

es wäre besser gewesen das eincheck verbot zu aktivieren und commandref join beim update erst nach einer weile zu verschärfen.

Verstehe ich nicht: ist das Problem, dass man Module nicht einchecken kann, oder dass man beim update Meldungen hat? Letzteres haben nur Benutzer, die FHEM auch per SVN updaten, also vermutlich nur wenige.

[rudolfkoenig]

Sorry, habs schon vergessen: commandref_join.pl wird ausgeliefert...
Ich kann das gerne in commandref_join.pl wieder auskommentieren, wenn das gewuenscht wird.

[justme1968]

die meldungen die die endanwender beim update durch das lokale bauen der doku erhalten.

d.h. alles was der endanwender sieht erst aktivieren nach dem die entwickler zeit zum fixen hatten.

d. h. eincheck verbot und die neuen commandref join meldungen für entwickler aber nicht beim lokalen bauen nach update.

[justme1968]

zu lagsam...

nicht ausbauen aber für den aufruf nach dem update deaktivieren.

[Dr. Boris Neubert]

Meiner Ansicht nach haben Tabellen in dem commandref nichts zu suchen, genauso wie Farbangaben und Buchstabengroessen. Ich moechte keinen Wettbewerb, wer seine Doku am schoensten bauen kann, sondern was Einheitliches, was auf vielen Frontends angezeigt werden kann.

Es geht mir nicht um schön sondern um gut lesbar. Für eine strukturierte gut lesbare Darstellung gibt es Tabellen. Wir haben mal entschieden, dass die Doku HTML ist. HTML kann Tabellen. Warum das jetzt verbieten? Ich kenne keinen HTML-Renderer, der Tabellen nicht beherrscht. Selbst in Man-Pages gibt es Tabellen (siehe man perl).

Ich bin auch für Einheitlichkeit. Die haben wir aber sicher derzeit nicht. Und das liegt nicht an Tabellen sondern an Kraut und Rüben bei der Formatierung. Daher das Votum für einen Styleguide. Darin verbieten wir Unterstreichungen (typographische Totsünde), Farben (nicht barrierefrei), von der Norm abweichende Schriftgrößen, Blinken, etc.

Weiterhin erfordert es eine zentrale Generierung der commandref.html (wovon ich weg will) oder eine aufwendigere Client-Installation wg. XSLT.

Warum lässt Du die commandref nicht wie zentral vor der Bereitstellung des Update generieren? Welche Vorteile bringt es, die Generierung nach dem Update beim Benutzer anzuwerfen?

Viele Grüße
Boris

[justme1968]

der grund war das damit das datenvolumen vom updateserver deutlich reduziert wird und aussderdem die doku für module aus anderen quellen auch generiert wird.

gruss
  andre