[Tiptoi] Wiki Zufallszahlen

Joachim Breitner mail at joachim-breitner.de
Do Sep 21 06:01:09 CEST 2017


Hi,

wenn hier gerade so viel Motivation zur Dokumentation statt findet,
will ich meinen Senf dazugeben und sagen, wie ich es machen würde, wenn
 ich die Zeit und Muße hätte:

Ja, wir brauchen eigentlich eine bessere Anwender-Orientierte
Dokumentation. Etwas das enthält was auf tttool.entropia.de und in den
beiden Magazinartikel steht, plus eine Referenz, plus Tricks und
Kniffe.

Es ist erstmal naheliegend, da ein Wiki draus zu machen, weil schnell
aufgesetzt und schnell mal was geschreiben. Aber Erfahrungsgemäß ist
das Ergebnis wenig erfreulich: Solche wikis werden in der Regel schnell
 unübersichtlich, unstrukturiert, uneinheitlich, veraltet und
unvollständig. Der interessierte Elter wird damit nicht besonders gut
zurechtkommen.

Was ich statt dessen machen würde ist folgendes:
 * Ein neues Git-Repository anlegen. Nennen wir es “tttool-buch”.
 * Dort in einem geeigneten Text-basierten Format anfangen, ein
   „Buch“ zu schreiben.
   Als Format bietet sich markdown an, weil es uns vermutlich genügt.
   (Alternativen wären asciidoc, restructuredText oder LaTeX).
   Eine Datei pro Kapitel, damit ein durchdachte Struktur schon 
   vorhanden ist.
 * Bei einer Änderung an den Dateien wird daraus automatisch eine 
   übersichlichte Webseite erzeugt, und vielleicht auch gleich eine 
   druckfertige PDF-Datei, für die, die lieber sowas lesen.
 * Es gibt Editoren, die den Überblick über das Buch haben und grob 
   wissen was wo steht. Jeder kann etwas Beitragen und Fehler 
   korrigieren, in dem er einen Pull-Request anlegt (das geht auch
   komplett im Browser, man muss sich nicht mit git rumschlagen).
   Diese werden dann von einem Editor kurz geprüft, ggf. werden
   Verbesserungen vorgeschlagen, oder sie werden übernommen.

Das ganze ist gar nicht groß anders als ein Wiki – jeder kann (mit drei
Klicks mehr vielleicht) Änderungen am Text einreichen. Der Unterschied
ist psychologisch: Es ist ganz was anderes ob ich irgendwo in einem
Wiki einen Absatz absetze mit irgendwas was da vielleicht irgendwo
irgendem was nützt, oder ob ich mir vornehme zu einem Thema (z.B. „Wie
mache ich Zufallszahlen“) einen Kapitel für etwas Buch-mäßiges zu
schreiben, und mir Gedanken mache, wie ich die Information am besten
aufbereite.

Die Struktur im Dokuwiki kommt der Sache schon nah…

Mit readthedocs.org geht vieles von dem was ich oben beschreibe
automatisch, hat ein vernünftiges Layout, generiert HTML, PDF und ePub.
Siehe z.B. http://gitpython.readthedocs.io/en/stable/intro.html.
Wenn wir das mit dem tiptoi-reveng repository verbinden, dann würde es
sogar anzeigen für welche Version die Dokumentation ist.

Hmm, ich glaube ich habe mich selbst überzeugt es so zu machen… also
hab ich mal angefangen, und hier ist das Ergebnis:
http://tttool.readthedocs.io/

Mit PDF! http://readthedocs.org/projects/tttool/downloads/pdf/latest/
Vielleicht finden wir ja einen Verleger :-)


Was haltet ihr davon? Konnte ich wen dazu begeistern sich da hinter den
Schreibtisch zu klemmen und sich hier ein Kapitel vorzunehmen und das
ordentlich auszuarbeiten?

Liebe Grüße aus der Ferne,
Joachim

Am Donnerstag, den 21.09.2017, 00:46 +0200 schrieb Boris Baumann:
> Hi Hendrik,
> 
> ja, genau. Mir geht es um eine Sammlung der ganzen Befehle und auch
> Verfahren zu Schleifen usw. und Zufallszahlen natürlich. 
> 
> Ich finde so viel tolle YAML-Sachen und Lösungen im Mailinlisten-
> Archiv und würde mir das zentral auf einer website wünschen. Mir wäre
> egal ob ich da ein Wiki mache oder ob das auf dem GitHub-Wiki
> stattfindet. Das Wiki würde ich mir so etwa vorstellen:
> tttyamlwiki.nullwert.com/doku.php ... ist ein Dokuwiki, ich glaube
> das reicht sicher, da muss ja keine dicke Datenbank hinter. Ich bin
> aber gerade noch dabei das etwas zu ordnen und gestalten. Oder
> willste dich schon anmelden? 
> 
> Den Zufall-Thread auf der Mailingliste haste sicher schon gesehen,
> oder? https://lists.nomeata.de/archive/tiptoi/2016/001184.html
> 
> Viele Grüße,
> Boris
> 
> 
> 
> 
> 
> --
> pgpid: 0x44B30067
> 9288 B559 5CC4 208C 98DA 29AD DECC 272C 44B3 0067
> 
> 
> 
> Am 20. September 2017 um 17:45 schrieb Hendrik Fuß <hendrik at kontrafus
> s.de>:
> > Hi Boris,
> > 
> > Heißt das, du hättest ein eigenes Wiki zu Programmiertechniken mit
> > tttool im Sinn? Das fände ich interessant. Da würde ja auch das
> > Thema Zufallszahlen gut hineinpassen. Aus Sicht des Programmierers
> > würde ich so eine Resource begrüßen, und ich denke auch, dass da
> > Wachstumspotential besteht. Also wenn du sowas aufsetzt, kümmere
> > ich mich um die Seite mit den Zufallszahlen. :)
> > 
> > Im GitHub-Wiki geht es eigentlich primär um das GME-Format, die
> > Stifthardware und Firmware und ein paar Themen drumherum. Über die
> > Programmierung mit dem tttool steht da wenig drin, da geht es mehr
> > um Reverse-Engineering. Die Frage ist, ob man das GitHub-Wiki nicht
> > um ein Kapitel zur Programmierung erweitern könnte.
> > 
> > viele Grüße
> > Hendrik
> > 
> > 
> > 
> > 
> > 
> > > Am 20.09.2017 um 14:05 schrieb Boris Baumann <boris.baumann at googl
> > > email.com>:
> > > 
> > > Hi Hendrik,
> > > 
> > > Ich würde gerne ein wiki aufsetzten, wo auch allgemein alle
> > > Befehle erklärt werden und aber auch wie man Schleifen usw.
> > > macht. Da würden Zufallszahlen gut reinpassen. 
> > > Wiiste das lieber auf einer Wikiseite zum Projekt machen? Also
> > > auf den GitHub-Wikiseiten?
> > > 
> > > Viele Grüße,
> > > Boris
> > > 
> > > 
> > > 
> > > 
> > > 
> > > --
> > > pgpid: 0x44B30067
> > > 9288 B559 5CC4 208C 98DA 29AD DECC 272C 44B3 0067
> > > 
> > > 
> > > 
> > > Am 20. September 2017 um 12:05 schrieb Hendrik Fuß <hendrik.fuss@
> > > gmail.com>:
> > > > Hallo zusammen,
> > > > 
> > > > ich beschäftige mich gerade zum ersten Mal mit dem Thema
> > > > Erzeugung von Zufallszahlen auf dem tiptoi-Stift. Nach einiger
> > > > Recherche stelle ich fest, dass das noch ein nicht vollständig
> > > > gelöstes Problem zu sein scheint.
> > > > 
> > > > Daher meine Frage: hat jemand von euch einen Überblick über den
> > > > aktuellen Stand der Technik, verwendete Algorithmen in RV-
> > > > Produkten, von RV verwendete Instruction-Codes wie (00 FF),
> > > > Laufzeitprobleme etc.? Ich fände es interessant, darüber eine
> > > > Wiki-Seite zusammenzustellen, bin aber gerade erst am Anfang
> > > > meiner Recherchen. Würde aber auch nach Möglichkeit dazu
> > > > beitragen, wenn sich jemand findet, der das Grundgerüst stellt.
> > > > 
> > > > Oder gibt es sowas schon und ich hab’s nur nicht gefunden? Für
> > > > Hinweise auf weitere Resourcen bin ich ebenfalls dankbar.
> > > > 
> > > > viele Grüße
> > > > Hendrik
> > > > 
> > > > 
> > > > --
> > > > tiptoi mailing list
> > > > tiptoi at lists.nomeata.de
> > > > https://lists.nomeata.de/mailman/listinfo/tiptoi
-- 
Joachim Breitner
  mail at joachim-breitner.de
  http://www.joachim-breitner.de/
-------------- nächster Teil --------------
Ein Dateianhang mit Binärdaten wurde abgetrennt...
Dateiname   : signature.asc
Dateityp    : application/pgp-signature
Dateigröße  : 833 bytes
Beschreibung: This is a digitally signed message part
URL         : <https://lists.nomeata.de/pipermail/tiptoi/attachments/20170921/c56b7b26/attachment.asc>


Mehr Informationen über die Mailingliste tiptoi