Faui2k17 Generator Repo
=======================

In diesem Repo werden alle Komponenten gesammelt, welche für das Bauen
der studentischen Seite https://fau2ik17.de benötigt werden.

Zentral hierbei ist der statische Website generator [_Haunt_][haunt]
(basierend auf [GNU Guile][guile], einer [Scheme][scheme]
Implementierung), welches die einzelnen Komponenten verbindet. Folge dem
obigen Link oder lese die `haunt.scm` Datei für mehr Informationen dazu.

Nachbauen
---------

**Anmerkung:** Zum Beitragen (siehe unten) ist prinzipiell nicht
notwendig die Seite auch selbst bauen zu müssen, Guile, Haunt oder sonst
was installiert zu haben.

Installiere zunächst GNU Guile mit einer Version größer-gleich 2.0 (2011
Veröffentlicht). Dieses sollte in den meisten Paketmanagern zu finden
sein.

Wenn Haunt/[Guile CommonMark][guile-cm] nicht verfügbar sind mit
Standard Systempaketmanager (mit ist dieses nur für
[Guix](https://guix.gnu.org/packages/haunt-0.2.4/) bekannt), muss man
sich von der Website den Quelltext herunterladen.

Dazu wird erstmals notwendig sein [Guile CommonMark][guile-cm] zu
installieren, wie im README beschrieben, und nachdem sichergestellt
wurde, dass `GUILE_LOAD_PATH` auch zu diesem verweist, Haunt zu
installieren.

Dieses bedeutet das die folgenden Befehle in den meisten fällen
Funktionieren sollten (angenommen `guile`, `make`, `autoconf`, ...) sind
zuvor installiert worden:

	$ curl -Ls https://files.dthompson.us/haunt/haunt-0.2.4.tar.gz | tar xz
	$ cd haunt-0.2.4
	$ ./configure --prefix=/usr
	$ make
	# make install
	$ cd ..
	$ curl -Ls https://github.com/OrangeShark/guile-commonmark/releases/download/v0.1.2/guile-commonmark-0.1.2.tar.gz | tar xz
	$ cd guile-commonmark-0.1.2
	$ ./configure --prefix=/usr
	$ make
	# make install
	
Struktur
--------

Hier ist alles bis auf die selbst Kurznachrichten zu finden. Diese
werden mittels [Git Submodules][submodule] eingeblendet, und sind unter
[`faui2k17/posts`][posts] hochgeladen.

Die restlichen Dateien sind dann noch:

- **local/**: Scheme Bibliotheken welche von `haunt.scm` benötigt werden.

	Besteht wiederum aus:
	- `micronews/paged-blog.scm`: Setzt "Blogformat" mit mehreren Index
      Seiten um.
	- `theme.scm`: Beschreibt für Haunt mittels [SXML][sxml] wie Seiten
      aufgebaut werden sollten.
	- `common.scm`: Gemeinsame Hilfsfunktionen Funktionen.
	- `pages.scm`: "Konstante" Seiten, dessen Inhalt nicht als Kurznachrichten
	  angesehen werden sollten. Geschrieben in [SXML][sxml].
- **posts/**: [Submodule][submodule] (siehe oben) mit Beiträgen in
  [CommonMark][commonmark]. Siehe auch [Haunt Dokumentation][haunt-cm]
  zu den Thema.
- **site/** (nicht im Repo): Enthält die generierte HTML Seiten.
- **static/**: Alle Dateien die direkt in **site** kopiert werden
  sollten, ohne Vor- und Nachverarbeitung.
- **haunt.scm**: Beschreibt den Aufbau der Seite. Importiert
  Bibliotheken aus `local`, und Seiten aus `pages`.
  
  Siehe [Haunt Tutorial][haunt-tutorial] für mehr Infos.

Beitragen
---------

Grundsätzlich ist jeder eingeladen Beiträge beizutragen,
siehe dafür [`faui2k17/posts`][posts]. In diesem ist jede Datei ein
"Post", welches mit seinem Metadaten zusammen in ein Beitrag auf der
Seite umgewandelt werden.

Dateien sehen darin Grundsätzlich so aus:
	
	title: Name des Artikels
	date: 2019-06-03 14:58
	author: Max Mustermann
	tags: tag1, tag2
	---
	
	Inhalt des _Artikels_.
	
Es ist dabei wichtig zu beachten, dass `date` richtig formatiert wird!
Tags sind allgemein erwünscht, da dieses dabei helfen kann Nutzern
ungewollte Inhalte heraus zu filtrieren.

Posts können direkt via Push Requests hinzugefügt werden, oder auch
einem Maintainer ([z.B.][ich]) via Email geschickt werden. Wer Interesse
hat öfters beizutragen, kann auch in die [GitLab Gruppe][gruppe]
hinzugefügt werden.

In der Konsole, kann man durch ausführen von `./newpost.sh` einfach ein
Skelett generieren und im bevorzugtem Text Editor (siehe `$EDITOR`)
bearbeiten.

[commonmark]: https://commonmark.org/
[gruppe]: https://gitlab.cs.fau.de/faui2k17
[guile-cm]: https://github.com/OrangeShark/guile-commonmark
[guile]: https://www.gnu.org/software/guile/
[haunt-cm]: https://dthompson.us/manuals/haunt/CommonMark.html#CommonMark
[haunt-tutorial]: https://dthompson.us/manuals/haunt/Tutorial.html#Tutorial
[haunt]: https://dthompson.us/projects/haunt.html
[ich]: https://wwwcip.informatik.uni-erlangen.de/~oj14ozun/
[posts]: https://gitlab.cs.fau.de/faui2k17/posts
[scheme]: https://schemers.org/
[submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
[sxml]: https://www.gnu.org/software/guile/manual/html_node/SXML.html