comandref.html split

[Rudolf Koenig]

Hab commandref.html gerade zerschlagen :), d.h. die Dokumentation
eines Moduls befindet sich ab sofort am Ende des jeweiligen Moduls,
nach dem 1;, und faengt mit =pod an, auch wenn es html und kein pod
ist. Der Rest befindet sich in docs/commandref_frame.html,
commandref.html habe ich im SVN geloescht.

Zum Zerschlagen habe ich contrib/commandref_split.pl verwendet, ich
meine das brauchen wir aber nie mehr.

Zum Erzeugen von docs/commandref.html muss man im fhem Verzeichnis
contrib/commandref_join.pl aufrufen, ohne Argumente, das braucht jeder
um die Doku zu testen(!).

Bemerkungen:
- 23_WEBTHERM.pm und 46_TRX_ELSE.pm haben keine commandref.html
Eintraege. Bitte nachziehen, sonst muessen die beiden nach contrib.
- 98_SVG auch nicht, dieser wird noch umbenannt nach FhemwebSvg.pm
oder ich erfinde eine Dokumentation.
- die Dokumentation einiger Module aus contrib wird nicht mehr ins
commandref.html geschrieben (HOL, LUXTRONIK2, DbLog, dumpdef,
FHEMRENDERER), da docs/commandref.html erstellt wird, indem docs/
commandref_frame.html mit der Doku in den fhem/NN_*.pm Dateien
ergaenzt wird.
- falls jemand ein neues Command oder ein Helper baut, dann muss der
Hinweis in dem richtigen Index-Abschnitt in commandref_frame.html
eingetragen werden, wenn nicht, dann wird angenommen, dass es ein
Device ist.
- bitte auf fehlende </ul> achten, ich bin es Leid immer wieder zu
suchen, und zu ergaenzen.

Hab die geaenderten Module (das sind fast alle) eingecheckt, ein
update muss also alles neu herunterladen.

fhemupdate.pl ruft taeglich contrib/commandref_join.pl auf, um
commandref.html zu erstellen, damit sollte sich fuer den Endbenutzer
erstmal nichts aendern. Das Makefile ist noch nicht angepasst.

Bitte melden, wenn ich was uebersehen habe.

[Martin Fischer]

was hälst du davon, wenn wir in diesem zuge auch gleich noch ein
"help" command einbauen, der die hilfe auf der konsole angibt?

ala: help at

nur als vorschlag.. ich arbeite derzeit an einem weiteren grossen modul,
worauf ich mich im moment konzentriere..

[Willi]

Am Sonntag, 4. November 2012 15:35:03 UTC+1 schrieb Rudolf Koenig:

- 23_WEBTHERM.pm und 46_TRX_ELSE.pm haben keine commandref.html

Gerade für  46_TRX_ELSE.pm erstellt und eingecheckt.

MfG Willi

[Rudolf Koenig]

> ala: help at

Meinst Du sowas wie FHEMWEB -> Definition... -> at ?

Bin nicht wirklich begeistert, weil es mAn aufwendig ist html sinnvoll zu
strippen, und diese Texte sind nicht fuer Terminal-Breite/Laenge optimiert.
Wenn Du sowas hinkriegst, koennen wir es aber versuchen.

Die meisten lesen eh kein Doku, und in der Kommandozeile schon gar nicht :(

[Martin Fischer]

Am Sonntag, 4. November 2012, 16:53:47 schrieb Rudolf Koenig:
> [...]

> Wenn Du sowas hinkriegst, koennen wir es aber versuchen.

wie gesagt... nur als idee und auf der todo mit prio -99 meilenweit am ende..

vielleicht wäre es andersum evtl. besser:

im modul nicht mit
=pod
=begin html
=end html

zu nutzen, sondern mit "normalen" pod direktiven zu arbeiten. anschliessend
das mittels "pod2html" zur commandref wandeln.

das trägt
a) zur übersichtlichen dokumentation innerhalb des moduls bei
b) ermöglicht sogar in der bash die hilfe anzuzeigen
c) spart 'ne menge überflüssigen speicher, da der ganze "html-overhead"
rausfliegt
d) verhindert das "vergessen" von </ul> tags
e) sicher noch weitere vorteile...

ich hatte das ja schonmal so vorgeschlagen...

und wenn sich keiner findet _alle_ nun von dir gewandelten module anzupassen,
dann könnte man ja das ganze mal als aufgabe an die community auslagen... da
finden sich bestimmt freiwillige, da keine programmierkenntnisse notwendig
wären.

gruss martin

[Dr. Boris Neubert]

Hallo,

habe soeben die Dokumentation ins Wiki getan:

http://www.fhemwiki.de/wiki/DocumentationGuidelines

Gr��e
Boris

[Rudolf Koenig]

> dann k�nnte man ja das ganze mal als aufgabe an die community auslagen...

Ich sage nur: deutsch-Uebersetzung der commandref.html

[Dr. Boris Neubert]

Am 04.11.2012 17:10, schrieb Martin Fischer:
> Am Sonntag, 4. November 2012, 16:53:47 schrieb Rudolf Koenig:
> und wenn sich keiner findet _alle_ nun von dir gewandelten module

> anzupassen, dann k�nnte man ja das ganze mal als aufgabe an die

> community auslagen... da finden sich bestimmt freiwillige, da keine

> programmierkenntnisse notwendig w�ren.

ich habe mal HTML2Pod (sic) an einem Modul ausprobiert, um das zu
automatisieren. Aus dem erzeugten .pod habe ich dann mit pod2html wieder
HTML gemacht. Tabellen gehen dabei ueber die Wupper. Weiter habe ich
dann nicht getestet.

Ich bin bereit .pod zu lernen aber nicht die Arbeit zu machen, die Doku
komplett so nach .pod zu portieren oder anderer Leute Arbeit
nachzubessern, damit die commandref.html ansehnlich bleibt.

Gruesse
Boris

[Martin Fischer]

Am Sonntag, 4. November 2012, 19:15:36 schrieb Rudolf Koenig:
> > dann könnte man ja das ganze mal als aufgabe an die community auslagen...

>
> Ich sage nur: deutsch-Uebersetzung der commandref.html

ja, das ist zwar ein argument..

aber ich denke, das würde man hinbekommen. ich schau mir das mal an,
vielleicht mache auch ich mir die mühe.

ABER: vorab möchte ich wissen ob es _überhaupt_ ein ansatz wäre?

nicht das ich da anfange und dann heisst es: april, april...

[Martin Fischer]

Am Sonntag, 4. November 2012, 19:19:58 schrieb Dr. Boris Neubert:
> [...]

> ich habe mal HTML2Pod (sic) an einem Modul ausprobiert, um das zu
> automatisieren. Aus dem erzeugten .pod habe ich dann mit pod2html wieder
> HTML gemacht. Tabellen gehen dabei ueber die Wupper. Weiter habe ich
> dann nicht getestet.

die frage ist: benötigt man überhaupt tabellen? heute sind eigentlich divs
"state-of-the-art".. aber das ist ein anderes thema.

> Ich bin bereit .pod zu lernen aber nicht die Arbeit zu machen, die Doku
> komplett so nach .pod zu portieren oder anderer Leute Arbeit
> nachzubessern, damit die commandref.html ansehnlich bleibt.

pod ist eigentlich einfach und vorallem: es gehört zum perlstandard. also
vertrete ich die meinung (die nicht stimmen muss), wer perl "beherrscht" kommt
auch mit dem bisserl pod klar.

vorteil aus meiner sicht:
der aufbau bleibt bei allen module sehr identisch, da mit pod (vielleicht)
nicht soviel "murks" angestellt werden kann, wie mit html. also vergessene
"closing-tags", "veraltete tags", "inframe", etc.

ich habe mir pod2html vor längerer zeit mal angesehen, daher kann ich dazu
keine aussage treffen. vorteil wäre halt, das man dann schön mit einer css
arbeiten kann.

wie gesagt: es muss "übereinstimmung" zwischen uns vorhanden sein, dann schaue
ich mir das auch tiefer an.

ich meine aber, das die vorteile von reinem pod überwiegen.

gruss martin

[Dr. Boris Neubert]

Am 04.11.2012 15:35, schrieb Rudolf Koenig:

- bitte auf fehlende </ul> achten, ich bin es Leid immer wieder zu
suchen, und zu ergaenzen.

habe commandref.html_join um einen Checker fuer unbalanced tags erweitert (ul li code). Die verbleibenden "Suenden":

FHEM/00_CUL.pm: Unbalanced li
FHEM/10_CUL_HM.pm: Unbalanced li
FHEM/10_CUL_IR.pm: Unbalanced li
FHEM/16_CUL_RFR.pm: Unbalanced li
FHEM/14_CUL_TX.pm: Unbalanced li
FHEM/10_EIB.pm: Unbalanced li
FHEM/63_EMGZ.pm: Unbalanced li
FHEM/61_EMWZ.pm: Unbalanced li
FHEM/10_EnOcean.pm: Unbalanced li
FHEM/11_FHT.pm: Unbalanced li
FHEM/11_FHT.pm: Unbalanced code
FHEM/95_FLOORPLAN.pm: Unbalanced li
FHEM/10_FS20.pm: Unbalanced li
FHEM/92_FileLog.pm: Unbalanced li
FHEM/59_HCS.pm: Unbalanced li
FHEM/00_HMLAN.pm: Unbalanced li
FHEM/12_HMS.pm: Unbalanced li
FHEM/10_IT.pm: Unbalanced li
FHEM/00_KM271.pm: Unbalanced li
FHEM/00_OWX.pm: Unbalanced ul
FHEM/95_PachLog.pm: Unbalanced li
FHEM/40_RFXCOM.pm: Unbalanced code
FHEM/99_SUNRISE_EL.pm: Unbalanced li
FHEM/00_TCM.pm: Unbalanced li
FHEM/45_TRX.pm: Unbalanced code
FHEM/20_X10.pm: Unbalanced li
FHEM/00_ZWDongle.pm: Unbalanced li
FHEM/10_ZWave.pm: Unbalanced li
FHEM/98_average.pm: Unbalanced li
FHEM/91_notify.pm: Unbalanced li
FHEM/98_telnet.pm: Unbalanced li
FHEM/91_watchdog.pm: Unbalanced li
FHEM/98_weblink.pm: Unbalanced li

Gruesse
Boris

[Rudolf Koenig]

> wie gesagt: es muss "�bereinstimmung" zwischen uns vorhanden sein, dann schaue

> ich mir das auch tiefer an.

Ich habe nichts dagegen, ich habe aber schon mal 2-3 Stunden lang vergeblich
versucht ein pod so zu bauen, dass es danach im html aehnlich dem aktuellen
commandref.html ist.

Also wenn Du das so hinkriegst, dass es wie heute ausschaut (css darf beliebig
angepasst werden), dann haben wir den ersten Schritt geschafft. Danach muesste
nur geklaert werden, wer den Rest umbaut, am besten waere automatisch.

Wenn _beides_ klappt, oder das eine Format mit dem anderen kombinierbar ist,
dann koennen wir von mir aus loslegen. Oder anders: gerne, solange wir keine
Funktionalitaet verlierem, im Sinne dass die haelfte der Doku nicht verfuegbar
ist.

[Martin Fischer]

Am Sonntag, 4. November 2012, 20:33:52 schrieb Rudolf Koenig:
> [...]

> Also wenn Du das so hinkriegst, dass es wie heute ausschaut (css darf
> beliebig angepasst werden), dann haben wir den ersten Schritt geschafft.
> Danach muesste nur geklaert werden, wer den Rest umbaut, am besten waere
> automatisch.

ob es 100%ig so aus sieht wie heute, mag ich nicht einzuschätzen.

wenn es dem aber "ähnelt" und dazu führt, das doku "einfacher" ist, kann das
dann ja auch akzeptiert werden und nicht eine "killing point" darstellen..

ich nehms mir auf die todo..

melde mich dann, wenn es was zu berichten gibt..

[Prof. Dr. Peter A. Henning]

Ein wenig Vorwarnung wäre natürlich angenehmer gewesen, aber, ok.

Werde also die OWX-Module künftig nur noch mit pod hochladen.

"unbalanced ul" in OWX werde ich suchen, geht aber nicht vor morgen abend.

LG

pah

[Dirk Hoffmann]

> die frage ist: benötigt man überhaupt tabellen? heute sind eigentlich divs

> "state-of-the-art".. aber das ist ein anderes thema.

Tabellen haben auch heute noch Ihre Berechtigung. Nämlich da, wo
Tabellarischer Inhalt angezeigt werden soll.

Gruß
Dirk

[strauch]

Sorry für einen kurzen Offtopicbeitrag. Ich habe das mit der Übersetzung der commandref gelesen. Mir war bisher garnicht bewusst, das dies geplant ist. Ich helfe z.B. Bei Drupal Übersetzungen und da gibts extra Schnittstellen aus Drupal heraus und Sprachserver um dies zu machen. Was ich sagen will, vielleicht muss das irgendwie Dauerhaft an die Community übermittelt werden. Wenn die sehen es gibt einen Deutschen Ansatz und dort kann ich mithelfen, wird dies denke ich auch geschehen.

[Martin Fischer]

wie ich schon schrieb:

> > [...] aber das ist ein anderes thema.

und auf die commandref.html sehe _ich_ zumindest nicht die _unbedingte_
notwendigkeit, das dort eine tabelle vorhanden sein muss.

das lässt sich dort alles mit <li> tags abbilden..

führt jetzt aber zu weit und desweiteren möchte ich nun keine
grundsatzdiskussion führen, sofern ich die "killing points" für die umstellung
auf ggf. komplettes pod nicht geklärt habe...

gruss..

[Martin Fischer]

hallo andre,

Am Montag, 5. November 2012, 02:13:20 schrieb strauch:
> Sorry für einen kurzen Offtopicbeitrag. Ich habe das mit der Übersetzung der
> commandref gelesen. Mir war bisher garnicht bewusst, das dies geplant ist.

danke für den beitrag... so "off-topic" ist der gar nicht. er geht in die
richtung die ich denke. aber dazu müssen erst ein paar grundlagen geschaffen
werden.

ich hatte mir schon vor release 5.3 auf die todo genommen, das ich fhem
"internationalisiere". erst wil ich aber meine angefangenen module fertig
stellen, bevor ich diese (doch etwas grössere) baustelle angehe.

wenn das soweit ist, dann wäre es evtl. auch möglich übersetzungen in andere
sprachen an die community auszulagern.

dauert aber noch a bisserl..

gruss

[Prof. Dr. Peter A. Henning]

Auch mal etwas OT: Wer hat denn die ganzen Module OWX etc wieder aus der "langen" commandref.html herausgeworfen, nachdem ich sie dort mühsam eingefügt hatte ?

LG

pah

[Rudolf Koenig]

> > Auch mal etwas OT: Wer hat denn die ganzen Module OWX etc wieder aus der

> > "langen" commandref.html herausgeworfen, nachdem ich sie dort m�hsam
> > eingef�gt hatte ?

1. "> " am Anfang einer Zeile in einem Reply bedeutet "Zitat":
Nach etwas Verwirrung vermute ich: das ist hier nicht der Fall.

2. mit "svn log 00_OWX.pm" muesste die Frage jeder beantworten koennen.

3. Ich zitiere den allerersten Beitrag in diesem Thread:

> Hab commandref.html gerade zerschlagen :), d.h. die Dokumentation
> eines Moduls befindet sich ab sofort am Ende des jeweiligen Moduls,
> nach dem 1;, und faengt mit =pod an, auch wenn es html und kein pod
> ist. Der Rest befindet sich in docs/commandref_frame.html,
> commandref.html habe ich im SVN geloescht.

...

> Zum Erzeugen von docs/commandref.html muss man im fhem Verzeichnis
> contrib/commandref_join.pl aufrufen, ohne Argumente, das braucht jeder
> um die Doku zu testen(!).

Aber vielleicht verstehe ich die Frage immer noch nicht.

[Martin Fischer]

Am Sonntag, 4. November 2012, 06:35:02 schrieb Rudolf Koenig:
> [...]

> Zum Erzeugen von docs/commandref.html muss man im fhem Verzeichnis
> contrib/commandref_join.pl aufrufen, ohne Argumente, das braucht jeder
> um die Doku zu testen(!).

verständnisfrage:

1) muss _ich_ contrib/commandref_join.pl (ausser zum testen) aufrufen oder
wird das automatisch im rahmen von fhemupdate gemacht?

2) ich nutze seit ewigkeiten "$id: $" einträge in meinen modulen.. beim
auschecken sind die oft immer noch so, ohne versionsnummer..

verhalten so korrekt?

gruss...

[Dr. Boris Neubert]

Hallo,

Am 07.11.2012 23:07, schrieb Martin Fischer:
> wird das automatisch im rahmen von fhemupdate gemacht? 2) ich nutze

> seit ewigkeiten "$id: $" eintr�ge in meinen modulen.. beim auschecken

> sind die oft immer noch so, ohne versionsnummer.. verhalten so
> korrekt? gruss...

Du musst noch explizit die SVN property svn-keyword id an der Datei
setzen (habe Syntax gerade nicht parat).

Gruesse
Boris

[Willi]

svn propset svn:keywords 'Id' DATEINAME

[Rudolf Koenig]

> 1) muss _ich_ contrib/commandref_join.pl (ausser zum testen) aufrufen

Nein.

> wird das automatisch im rahmen von fhemupdate gemacht?

Ja.


> 2) ich nutze seit ewigkeiten "$id: $" eintr�ge in meinen modulen.. beim

> auschecken sind die oft immer noch so, ohne versionsnummer..

Das hat Boris und Willi schon beantwortet.

[Martin Fischer]

Am Mittwoch, 7. November 2012, 23:31:58 schrieb Willi:
> svn propset svn:keywords 'Id' DATEINAME

danke willi und boris...

man lernt halt nie aus :-)