Doku in Git

[fuddl]

Ich werde die Doku bald nachführen (bin da ziemlich hinten nach )

Spricht etwas dagegen die Doku mit ins Git zu legen? Spaßeshalber habe ich einen kleinen Teil der deutschen Doku in Markdown übertragen, ins Verzeichnis Documentation/ gelegt und mit pandoc nach HTML übersetzen lassen, was gut genug funktioniert. Mein git branch liegt hier: https://salsa.debian.org/fuddl/railcont ... type=heads

Um es auf die Schnelle auszuprobieren:

Code: Select all

pandoc --standalone --from=markdown --to=html --output=Documentation/main_de.html Documentation/main_de.md

Pro
1. Doku und Version/Git tag passen zusammen
2. Es ist leicht zur Doku beizutragen, also: Git klonen, Zweig erstellen, dir einen pull-request zukommen lassen, tadaaaa
3. Die Doku ist statisches HTML und du kannst sie bspw. bei jedem Release auf dem Webserver aktualiseren + sie kann auf der Festplatte des Nutzers lokal installiert werden (Dann ist sie auch "auf dem Steuer-PC im Keller mit dem schlechten WLAN")

Contra
1. Weniger flexibel bei der Formatierung bzw. Darstellung der Doku
2. Zusätzliche Abhändigkeit auf pandoc oder etwas ähnliches.

Was denkst du, top oder flopp?

[teddy]

Hallo Bruno

Die jetzige Lösung ist semi-cool. Ich hab alles als Joomla-Artikel erfasst und die Joomla-Version will geupdated werden, was aber wegen der verwendeten Standard-Sprachmodule nicht so einfach will.

Mit der jetzigen Lösung bin ich deshalb nicht wirklich glücklich. Ich hab mir aber noch keine Gedanken gemacht zu Alternativen.

Markdown kannte ich beim Start des Projektes noch nicht, pandoc kannte ich bis jetzt auch nicht. Ich muss mir das mal anschauen.

Gruss
Teddy

[fuddl]

Hallo Teddy,

als mir Joomla ins Auge stach kam mir schon die Vermutung auf, dass es die üblich verdächtigen "Freuden" bereitet.

Ich übertrage einfach weiter die jetzige Doku nach Markdown und stoße entweder auf ein unlösbares Problem oder bin irgendwann fertig.

Erst nach meinem vorherigen Kommentar fiel mir noch ein Bonus für dich auf: Github und Gitlab können Markdown on-the-fly anzeigen, d.h., ein Hyperlink von railcontrol.org auf bspw. main.md in Github und dein Aufwand zur Pflege der Doku reduziert sich auf Null, also dafür brauchst du nicht mal pandoc.

Was is noch nicht herausgefunden habe: Die Schritte damit aus Markdown erzeugtes HTML mit pandoc ähnlich genug dem jetzigen Joomla Theme aussieht.

Viele Grüße
Fuddl