Das Dateiformat der Download-Datei kann alles sein, auch ein Bild (wobei ein Bild eher in den Bilderpool-Bereich gehört).
Zu jeder Download-Datei gibt es eine zugehörige Markdown-Datei mit Beschreibung und Info zur Darstellung.
Aus organisatorischen Gründen sind die Download-Datei und die Datei mit der Beschreibung namensgleich und unterscheiden sich nur in der Datei-Endung. Das muss allerdings nicht zwingend so sein. Ein Admin freut sich allerdings über sofort sichtbare Bezüge. Die Beschreibung ist immer in einer .md-Datei untergebracht. [Das geht genau so lange gut, bis jemand mal eine Markdowndatei mit der Endung .md hochlädt.] Auf der Platte sieht das dann etwa so aus:
$ ls
grundbaustein.md
grundbaustein.pdf
flipflop.md
flipflop.pdf
grundbaustein.md enthält die Beschreibung zum Download grundbaustein.pdf und flipflop.md enthält die Beschreibung zum Download flipflop.pdf.
Der Dateiname der Download-Datei soll keine Leerzeichen, keine Klammern oder sonstige Sonderzeichen enthalten. Unser Server ist inzwischen in der Lage, in Links verwendete Großbuchstaben nach Kleinbuchstaben umzuleiten. Sicherheitshalber sollten die Dateinamen aber nur aus Kleinbuchstaben und eventuell noch Unter- und Bindestrichen bestehen.
Zuerst haben wir den “Frontmatter”-Abschnitt. Er enthält diese Felder (die Reihenfolge ist nicht so wichtig, aber eine einheitliche Anordnung macht es den Admins leichter):
| Frontmatter | Angabe | Erläuterung |
|---|---|---|
| --- | Leitet den Frontmatter-Block ein | |
| layout: "file" | Pflicht | Das Layout für einen Download-Eintrag heißt "file". |
| title: "Flip Flop Baustein" | Pflicht | Der Titel, der als Überschrift oben erscheint |
| date: 2005-06-06T00:00:00+0200 | Pflicht |
Das Datum des uploads - wird automatisch erzeugt.
Codierung: yyyy-mm-ddThh:mm:ss+hhmm Beim manuellem Erstellen neuer Seiten bitte die Zeitzone (`+0100` MEZ bzw. `+0200` MESZ nicht vergessen)! Es wird empfohlen, vorhandene Archetypes zu nutzen. Hugo kümmert sich dann um das korrekte Datum mitsamt der Zeitzone. Für legacy-Dateien, die älter als 2 h sind, ist die Angabe der Zeitzone unerheblich und kann entfallen. Für alles Aktuelle soll sie rein; sonst wird die Seite von Hugo nicht (zur richtigen Zeit) gebaut. |
| file: "flipflop.pdf" | Pflicht | Das zugehörige Download-File. Vorzugsweise unterscheiden sich die Namen von Download-File und Markdownfile nur in der Endung. Das hilft den menschlichen Admins sehr zu erkennen, was zusammen gehört. Beispiel: flipflop.pdf <=> flipflop.md |
| konstrukteure: - "Michael Becker" |
Option | 'Autoren' wäre hier von der Wortwahl geschickter, 'konstrukteure' ist technisch aber das gleiche. Also nennen wir es genau so, wie es auch im Bilderpool benannt ist. Für den Fall der Fälle (wir haben tatsächlich welche) ist das als Liste mit mehreren Einträgen vorbereitet. Je Autor eine Zeile und bitte das "-" davor! Mittlerweile ist die zugehörige Steuerdatei für die Darstellung in der Lage, auch mit leeren Listen umzugehen. Trotzdem bitte bei manuellen Pflegearbeiten darauf achten, hier entweder den Eintrag mit wenigstens einem Autor zu machen oder die Zeile komplett weg zu lassen. |
| uploadBy: - "Michael Becker" |
Pflicht | Logisch macht es keinen Sinn hier eine Liste zu führen, denn der upload erfolgt natürlich nur von einem Nutzer. Nun gibt es da aber eine kleine Kosmetik für eine angenehme Formulierung der Angaben auf der Seite. Und diese Kosmetik funktioniert (derzeit) nur mit gleichen Datentypen. Deswegen: Liste mit nur einem Eintrag. Mittlerweile ist das zugehörige Kontrollfile für die Darstellung in der Lage, auch mit leeren Listen umzugehen. Trotzdem bitte bei manuellen Pflegearbeiten darauf achten, hier entweder den Eintrag mit exakt einem Eintrag zu machen oder die Zeile komplett weg zu lassen. `-LegacyAdmin-` ist reserviert für Dateien, bei denen nicht herauszufinden ist, wer den Upload gemacht hat (exklusiv für Altlasten aus der ftc vor 2019). |
| license: "unknown" | Option | Die Angabe der Lizenz zur Veröffentlichung. Gab es in der alten ftc nicht, ist neu hier. Wenn keine Angabe gemacht wird, gilt automatisch "Alle Rechte vorbehalten" und die Rechte liegen beim Autor. |
| legacy_id: - /data/downloads/ebausteine/schaltplne/flipflop.pdf |
Option |
Das ist gedacht für Seiten, die aus der alten ftc übernommen wurden.
Ebenso nützlich aber auch, wenn mal was verschoben wurde. Dann bleiben
die Links darauf alle wirksam.
'https://www.ftcommunity.de' wird rausgeworfen, der Rest kommt so wie
in der url-Zeile vom Browser. Original hieß das mal https://www.ftcommunity.de/data/downloads/ebausteine/schaltplne/flipflop.pdf Falls ein imported tag vergeben ist, muss auch eine legacy_id vorhanden sein! |
| imported: - "2019" |
Option |
Wird dieser Eintrag gemacht, ist die Datei aus einer vorherigen
ftc-Version übernommen worden. "2019" steht dann für das Jahr, in
dem der Import gemacht wurde.
Stammt der Download aus der aktuellen Version der ftc, wird dieser Eintrag nicht gemacht! Die Idee ist, hier bei Bedarf einen Automaten drauf loszulassen der die Einträge vornimmt / ergänzt (z. B.: - "2019" -> - "2019" - "2033"). Vorläufig wird das Feld nicht ausgewertet, hilft uns aber eines Tages herauszufinden, was schon vorher da war. legacy_id ist dafür ungeeignet, da dort jede ehemalige ID reinkommt - also auch wenn innerhalb der aktuellen ftc-Seite was verschoben wird. Zukunftssicher ist eine Liste besser geeignet als ein einzelner String. |
| --- | Schließt den Frontmatter-Block ab. |
Nach dem Frontmatter kommt nun die Beschreibung der Download-Datei.
Für das gewählte Beispiel (flipflop.md) haben wir diesen Dateiinhalt:
---
layout: "file"
title: "Flip Flop Baustein"
date: 2005-06-06T00:00:00
file: "flipflop.pdf"
konstrukteure:
- "Michael Becker"
uploadBy:
- "Michael Becker"
license: "unknown"
legacy_id:
- /data/downloads/ebausteine/schaltplne/flipflop.pdf
imported:
- "2019"
---
<!-- https://www.ftcommunity.de/data/downloads/ebausteine/schaltplne/flipflop.pdf -->
Schaltplan "Flip Flop Baustein" (36479)
In der Beschreibung steht der vollständige Link zur alten ftc als html-Kommentar, um notfalls die volle Info über die Herkunft zur Verfügung zu haben. Der Link selbst erscheint nirgends. Der alte Link ist natürlich nur für Seiten aus der alten ftc sinnvoll.
Die Beschreibung darf, mit allem was
Markdown
bietet, formatiert werden.
Da wäre dann die Frage wie das der geneigte Benutzer ohne entsprechende Kenntnisse
im Upload hinbekommt? Zumindest für Admins aber zumindest schon mal wichtig.
Das Beispiel stammt von einem der Silberlinge:
/knowhow/elektronik/silberlinge/flipflop/
Wie das in der Darstellung genau aussieht, bestimmt die zugehörige “Beschreibung”
in der Datei
/layouts/_default/file.html,
die die Angaben für das layout: “file” liest und für eine schöne
Browseransicht umsetzt. Dieses Skript für die Darstellung ist
hier beschrieben.